writing-technical-design-docs

编写技术设计文档

• 设计文档是决策记录，而不是规范。
• 它的作用是让大家对方向达成一致，既要严谨到足以启动工作，也要谦逊到允许计划调整。
• 目标是方向正确，而非尽善尽美：现在传阅一份完成度为 60% 的草稿，比三周后传阅一份完成度为 95% 的草稿更能获得有益反馈。
• 如果写文档花的时间比完成第一阶段实现还长，那就过度设计了。

原则

• 决定单向门；默认双向门。 单向门很难撤回（数据模型、公共 API、持久化格式、身份方案）：要充分讨论。双向门易于撤回（超时、重试次数、内部模块边界、日志格式）：说明默认方案，指出可以修改，然后继续推进。争论双向门超过一段话，就删掉相关讨论。不确定错误决策的修改成本时，就把它视为单向门。
• 指出未知；绝不捏造数字。 写“QPS 未知，将在第 1 周测量”，而不是“大约 500 QPS”。评审者可以质疑未知项；编造数字会让文档失去可信度。
• 选定一个方向，并说明一个替代方案。 写明选定的方案、考虑过的一个替代方案，以及一句话说明它为何落选：“使用 Postgres LISTEN/NOTIFY。考虑过 Kafka；因在我们的规模下运维复杂度过高而弃用。”不要罗列一堆选项；倾向其他方案的评审者会主动提出。
• 具体但不求面面俱到。 端到端写清承重场景及其关键边界情况，其余部分标注为“遵循相同模式”或“实现在实施阶段确定”。
• 写下只有你知道的内容。 评审者和后续读者只能看到文档及其链接的文件，看不到这段对话。因此，对话中的每项需求、约束和决策都要写进文档，或写进文档链接的文件中。

结构

默认结构，可根据需要调整；如果团队已有模板，就融入团队自己的模板。

1. 先写状态栏： Status: Draft v0.1 (seeking [direction | implementation | rollout] feedback)。 这能提醒评审者不要提交逐行修改意见。
2. 先说决策： 问题陈述之后，立即用 3 到 5 句话说明选定的方案。其他内容都是论据或细节。
3. 标注详略： 对需要严谨阐述的章节标注 [deep]，对有意简写的章节标注 [sketch]，让评审者知道该重点提出哪些问题。
4. 开放问题： 编号列出，每个问题都注明负责人和需要得到答案的日历日期。五个诚实的开放问题胜过零个。负责人是一项指派，而不是未知事实：如果无法指定具体人员，就写明负责团队、角色或作者，并根据文档日期提出日期。两者都不要写 TBD。
5. 以可逆性表格结尾： 将每项主要决策评为单向门或双向门。表格之后不再添加任何章节。

评审

• 本次会话负责产出文档：它承载着这段对话，因此不能评判自己的草稿。遵循 独立评审规则。
• 返回草稿前，调用 Skill 工具，并对草稿使用 reviewing-design-docs 进行对抗性评审。
• 如果未安装该工具或无法在此处运行（例如无法将草稿保存到文件），就在文档分隔线下方说明未进行独立评审、原因以及下一步操作：将草稿保存到文件，然后运行 /reviewing-design-docs <path>。
• 返回草稿，然后在分隔线下方逐字附上评审输出，包括存在时仅含提示词的那一行。不要根据评审发现修改草稿。由用户决定采取哪些行动。
• 如果没有 Skill 工具，请遵循 技能调用规则。

不应使用此技能的场景

• **合规、法律或安全关键规范：**这些内容需要精确，而非指导。请编写完整、详尽的规范。
• **面向外部客户发布的公共 API 合约：**默认属于不可逆的决策；应优先确保内容全面。
• **事后复盘和事件报告：**侧重回顾过去并陈述事实。
• **最终签署的架构文档：**方向已经确定。