用途
Design Doc 是一个用于撰写和评审软件设计文档的技能，覆盖技术设计文档、工程设计提案、架构决策文档和内部 RFC。设计文档是工程师在动手构建之前产出的书面材料，用于思考那些一旦做错代价高昂的决策。
该技能围绕三个核心问题提供判断：这个项目到底该不该有文档、文档里应该放什么、以及怎么写才能让一个从未与你交流过的读者真正读懂。
设计文档不是形式主义，也不是状态汇报。它的目的是杠杆作用：一份好的设计文档可以节省数年的开发时间。撰写设计文档迫使你在把时间浪费在错误实现或把自己逼入死角之前，想清楚重要决策。它同时是两样东西：一个决策强制工具（把困难的部分写下来，会暴露那些你原本会在构建中途才发现、届时难以逆转的选择），以及一个沟通工具（让队友、合作团队和评审者在代码存在之前就能理解并压力测试方案）。
两种失败模式
该技能要求始终同时记住两种失败模式，所有决策都是为了在两者之间保持平衡。
- 写得太少：跳过文档，或遗漏难以逆转的决策。你可能在写了 20 万行 C++ 之后才发现错误，此时重写已无法挽回。解药是“何时该写”测试和“出错代价”过滤器。
- 写得太多：规定每一个细节（按钮间距、每个辅助函数）。如果在设计文档中规定所有可能的细节，你实际上是在设计阶段就写完了实现，这违背了设计文档的整个目的。解药同样是“出错代价”过滤器，用于删减。
好的设计文档工作几乎完全在于决定省略什么。抓住高出错代价的决策；让廉价、可逆的选择在代码中被发现。
阶段一：决定是否要写
并非每个项目都值得写文档。有时，在设计文档上投入的正确数量是零。运行以下清单——任何一项回答“是”，文档可能就值得写；两项或更多，几乎肯定值得：
- 是否有多人协作实现该设计？
- 项目是否需要超过三个月的全职开发工作？
- 实现是否会在生产环境运行数年？
- 项目是否涉及跨团队协作？
- 目标和需求是否模糊？
- 是否存在可以在设计阶段预防的灾难性风险（安全、法律、数据丢失）？
如果达到标准，就根据项目风险和截止日期调整投入——没有通用的“正确长度”，就像没有规定该测试多少一样。如果没达到，就说明并停止；建议不写文档是一个有效且有用的答案。
阶段二：决定包含什么
有一个问题支配每一个纳入决策：出错的代价是什么？
高代价 → 写入文档。难以或无法逆转的选择：编程语言、存储后端、公共接口、信任边界、数据模型、任何有多年锁定效应的东西。要深入思考哪些依赖在实现后难以更改，不必太担心那些容易替换的。（语言和存储后端极难更改；第三方邮件提供商一个下午就能换掉。）
低代价 → 不写。1000 篇文章是一次性全部渲染还是放在“加载更多”按钮后面，之后改起来只花一个下午——这不属于设计文档。
然后选择章节子集。章节目录是一份菜单，不是强制要求：通常不需要每份文档都包含每一个章节，选择对你合理的子集。一个小型内部服务可能只需要目标、背景、目标、非目标、接口和备选方案。一个涉及 PII 的多年平台可能需要几乎全部章节。
阶段三：起草文档
依据章节目录工作——文章定义的每个章节，分组呈现，每个都有其目的、回答的问题、好/坏示例以及“何时包含”。典型分组：
- 前置内容：标题、元数据、目标、背景、相关文档、术语表——让冷读者快速定位；一句话目的；项目为何存在。
- 范围（契约）：目标、非目标、约束——上线后的结果、明确的超出范围、硬性限制。
- 设计：场景、图表、接口、依赖与基础设施——构建出的系统如何行为与组合。
- 可运维性：SLO、监控与告警、日志、时间线——如何运行、衡量并按里程碑交付。
- 风险与合规：安全、隐私、法律——威胁、敏感数据、监管与许可义务。
- 活文档章节：未决问题、已解决问题、考虑过的备选方案——未解决的问题、其历史以及未走的路。
一份完整、可模仿的示例文档——RecencyBank 缓存层，篇幅恰当且从头到尾独立成篇——在参考资源中。起草前先阅读它，它是目标形态。
阶段四：让文档独立成立
设计文档是一种写作产物，大多数失败在于写作而非工程。主导测试是：想象一下在队友或合作团队阅读你的设计文档之前，你会对他们说什么。现在意识到有些读者会在听到你任何解释之前就看到文档。他们需要理解的内容都应该在第一页上。
由此得出的写作规则：用任何利益相关者都能理解的平实语言写目标；目标写成结果而非实现；要可衡量，不要模糊（“p50 延迟 ≤ 200ms”，绝不要“在移动端性能良好”）；优先使用可识别的术语并就地定义，而不是埋在术语表里；保持图表可编辑（Mermaid、D2、Excalidraw、draw.io——绝不要白板照片）并链接其源文件。这些规则连同前后改写示例都在写作技巧参考中。对每一份草稿运行这些规则作为自编辑环节。
阶段五：推动评审
文档的存在是为了在代码之前接受压力测试。传阅它，收集有意义的反馈，并在未决问题中跟踪未解决的事项（每项包含：问题、选项、立即的下一步）——随着它们关闭，将其移入已解决问题并保留讨论以供后人参考。在写代码之前写文档，并在实现时遵守它，同时接受低于出错代价线的细节在代码中而非文字中确定。完整指导——何时该写的理由、出错代价框架、篇幅调整、传阅反馈以及问题生命周期——在评审与生命周期参考中。
附带资源
- 章节目录：起草时阅读——文章定义的每个章节，分为六组，每个都有目的、回答的问题、好/坏示例以及何时包含。
- 写作技巧：阶段四期间阅读——沟通层：独立成立测试、平实语言目标、结果形态目标、可衡量而非模糊、就地定义优于术语表、可编辑图表、简洁、命名，附前后改写。
- 完整示例：起草前阅读——一份完整、篇幅恰当的范例设计文档（RecencyBank 缓存层），可从头到尾模仿。
- 评审与生命周期：阶段一、二、五期间阅读——何时该写清单与理由、出错代价框架、投入篇幅调整、推动文档评审、收集反馈以及未决/已解决问题生命周期。
范围说明
该技能撰写的是工程/技术设计文档——系统、服务、功能、迁移、架构。它不是创意、视觉或品牌类的“设计”产物。品牌识别和 UI 创意方向请使用 creative-director；标志和资产系统请使用 logo-studio。