technical-writing

技术写作

概述

技术文档的风格规范。规则以英文编写；文档保留自身语言：荷兰语文档用荷兰语撰写和审阅。结构和真实性规则适用于任何语言；references/style.md 中的词汇表仅适用于英文，其他语言有各自的词汇表。核心原则：文档陈述当前且经过验证的行为，结论先行，每项主张都可追溯至来源，每项事实都只在一个地方出现。内容精简的文档胜过夸大其词的文档。

这些规则适用于文档，不适用于聊天回复。长度和章节规则适用于正文，不适用于本文件这样的参考列表。

何时调用

撰写任何技术文稿时都加载此技能，并叠加加载相应的文档类型技能。以下是路由提示；每项技能自身的正文才是权威依据。

如果某个代码库经常产出文档，请在项目记忆中记录调用方式：在其 CLAUDE.md 或平台的等效文件中添加一行，告知 Agent 在此处撰写任何技术文稿时都要加载此技能。

任务类型	还需加载
提案、RFC、设计文档、规范或迁移计划	writing-design-docs
记录决策、ADR 或决策日志条目	recording-decisions
更新日志条目、发布说明、“已发布内容”	writing-changelogs
运维手册、设置指南、操作流程或故障排除条目	writing-runbooks
跟踪项：史诗、故事、任务、缺陷报告、技术探查、验收标准	writing-issues
迁移或弃用指南	writing-runbooks
事后复盘、事故报告、根本原因分析	writing-postmortems
记录现有但文档不足的系统；依据代码重新核对过时文档	documenting-legacy-codebases
流程、生命周期或交互图；绘制业务逻辑	diagramming-processes
API 参考：端点、消息载荷、DTO、CLI 命令、文件格式、webhook	documenting-contracts
审阅或改写他人文本；交付任何文档前的最终检查	reviewing-technical-prose

非目标

• 不适用于营销文案、社交媒体帖子或 UI 微文案；只有 references/truth.md 中的真实性规则仍然适用。
• 不决定内容：事实应以来源为准，而非风格。
• 不允许重设遵循自身规范的现有文档的风格；应遵循以下优先级规则。
• 不因“更有冲击力”“更吸引人”或“更有说服力”的要求而改变文风：说服力来自数据，语气应保持平实。

起草前的强制检查点

起草新文档或重要章节前，在工作笔记中推导并写明：

Kind: <normative|descriptive|historical|runbook|reference> | Audience: <who> | Purpose: <the verb the reader must accomplish> | Non-goals: <what this deliberately does not cover>

根据请求、来源和代码库背景填写各字段。如果某项未知信息不会实质性改变结果，请做出安全假设并继续。只有当未知信息会改变受众、实质内容或范围时才提问。切勿为填写检查点而编造事实；除非文档架构要求，否则不要将检查点加入最终文档。

先阅读，再撰写

动笔前：

1. 阅读同一目录中最多两份可比较的文档；沿用其结构、语气和惯例。如果可比较的文档少于两份，则阅读所有可用示例，再遵循代码库级惯例。不要因目录是新建的而停滞不前。
2. 检查是否有索引这些文档的 README.md。如果存在，请将新文档加入其中。
3. 检查主题是否已在其他位置说明。扩展现有文档通常远胜于在旁边新建一份竞争文档。

规则优先级

当指令冲突时，按以下顺序执行：

1. 真实性、安全性和历史完整性规则。
2. 当前文档类型技能中的明确例外。
3. 以下共享硬性规则。
4. 明确的架构，以及目标目录中的惯例。
5. references/style.md 中的共享风格偏好。

现有做法只决定更高优先级规则未明确规定的选择。它不能削弱来源要求、改写已接受的历史记录，也不能把未经验证的工作说成已交付。文档类型例外必须指出其调整的规则以及例外的边界。

作者明确表达的风格选择仅优先于共享风格偏好，不影响其他规则。当作者说“保留我的表达风格”时，风格修改应停止；无论谁提出异议，真实性、安全性和历史记录要求仍然有效。

编辑前先对文档分类

不同类型的文档适用不同的编辑规则。其中五类中的两类，按“更新文档以匹配代码”的做法是完全错误的。

类型	示例	编辑规则
规范性	架构原则、契约、风格指南	如果代码违反契约，切勿弱化契约；应记录违规情况。只有当契约本身提到的概念已被删除或重命名时，才进行编辑。
描述性	流程、组件文档、状态机	精确更新，使其与代码一致。应根据实现验证，而不是根据名称。
历史性	更新日志、旧规范、决策日志、已应用的迁移	绝不改写历史。标记差异，并通过新条目取代旧内容。
操作手册	运维、故障排除、发布流程	更新以匹配实际情况；每个步骤都必须实际执行过。
参考资料	API 文档、配置参考、索引	内容必须详尽：列出每个键、每个标志，包含默认值和“用法”列。

如果整份文档描述的内容已被删除，不要删除文件：添加一行横幅标记，说明其已过时（“> 注意：描述的是已移除的组件 X；请参阅 Y”），并将删除工作留给负责人。

硬性规则

以下规则在所有文档中都不可妥协：

• 不得使用 em dash、en dash 或 -- 形式的破折号。 使用逗号、冒号、分号、句号、括号，或用 - 作为插入语标记。普通连字符可用于表示范围（2026-2030）。交付前检查以上三种形式。
• 文档中不得有更新日志章节或“最后更新”字段。 这项要求也适用于每个句子：描述当前行为，绝不描述先前行为；“此步骤取代了手动检查”应写在迁移文档或发布说明中，而不是操作流程中。
• 不得在叙述性状态文字、注释、名称或字符串中记录交付历史：不得提及阶段、任务 ID、工单键、SHA 或仅用于描述工作交付方式的计划引用。固定的提交记录只能作为声明的证据出现。工单键可以作为功能性元数据出现在跟踪记录、提交消息、规划文档和引用中，但不得出现在代码注释或面向用户的内容中。
• 不得将无法追溯至所引用路径中的代码、固定的提交记录、测试、文档或一手来源的内容陈述为事实。 把合理猜测当作事实，比说明“来源对此没有说明”更糟。参见 references/truth.md。
• 一条事实，一个归属位置。 其他所有内容都链接到其归属位置。摘要可以引导读者，但不能作出判断：当索引与来源不一致时，以来源为准，索引才是错误所在。
• 已接受的决策和已应用的迁移不可更改。 更正必须作为新的带日期条目添加，绝不能编辑历史记录。
• 标题使用句式大小写，不得使用标题式大小写。

工作流

1. 先阅读上文，并对文档分类。
2. 起草前先声明：填写上方的检查点（类型、受众、目的、非目标）。
3. 各层级都先写结论：文档、章节、段落都如此。不要铺垫，也不要在给出结果前写背景段落。每章开篇就说明结论，而不是说明采用了什么方法。
4. 为每项主张提供依据，并标明其可信度：references/truth.md。
5. 检查风格，涵盖句子、词语、标题和禁用表达清单：references/style.md。
6. 交付前核验：加载 reviewing-technical-prose，查看检查清单。实际访问引用内容并进行检查。

受众

开始前先明确写给谁。不要笼统地说“用户”：要明确具体读者是谁、身处何种情境，以及他们要完成什么操作。

读者	他们需要什么
开发者	选择背后的原因，以及这会如何影响他们明天的工作
技术负责人 / 架构师	权衡、替代方案、长期影响
管理层 / 产品负责人	产出、成本、风险
外部人员	不使用未经解释的内部团队名称或术语

面向多个群体时：摘要要让最广泛的群体都能读懂，其余部分可进一步深入。需要脚注才能理解的表达，应当改写，而不是加脚注。

常见错误

• 一开始就提出解决方案。先讲问题，再讲提议。
• 记录代码已经说明的内容。文档应说明理由、约束、不变量和替代方案；代码负责说明具体内容。
• 主张无法核实，例如没有数字或来源的“更快”“更好”。补上数字，或删掉该主张。
• 用看似合理的猜测填补空白，而不是明确指出空白。
• 负责人含糊不清，例如只说“仍需调查”，却不说明由谁或哪个角色负责。
• 只罗列好处。每项提议都要说明代价。
• 在编辑时悄悄删减、为突出重点而调整顺序，或改变原文风格。编辑应精准克制：保留原有语气、结构、编号和 ID。
• 文档的正文篇幅约超过 800 行时，应拆分文档，并让主文档链接到各部分。