awesome-design-doc

设计文档 / ADR

将功能需求或架构问题转化为团队可以执行、未来读者也能追溯的决策。核心原则：先明确需求和数字，再讨论组件；先列出真实的备选方案，再给出建议；并在文末前作出推荐——只罗列选项却不做选择的文档是会议议程，不是设计文档。

何时启用

• “设计 X”“Y 应该怎么构建”“撰写设计文档 / ADR / RFC”。
• 评审者指出一项关键决策需要 ADR（awesome-code-review 会在此处采用这种格式）。
• 存在两种可信的方案，且选择之后很难更改。

可逆的日常选择（命名、辅助函数的位置）不需要启用——为此编写 ADR 只会制造噪声；是否需要 ADR，由下方的三项条件测试决定。

何时需要 ADR

三项条件必须全部满足，否则就不要写：

1. 更改成本高——架构、公共 API 形式、持久化格式、事件名称、框架 / 存储选择、服务边界。
2. 跨越边界——多个模块、团队或服务都必须遵循该决策。
3. 背景信息会丢失——六个月后，无法从代码中还原“为什么”。

单个决策写一页 ADR；如果功能需要同时确定数据模型、API 范围和发布计划，则编写完整设计文档。

工作流程

1. 先明确组件之前的要求——将功能要求写成可测试的陈述，每条都有稳定标签，供文档其他部分引用；并将强制要求与期望要求分开列出。随后写明影响设计的约束：预期规模（用户数、QPS、数据量及增长）、延迟目标、一致性需求（哪些内容必须支持读己之写，哪些可以有延迟）、可用性预期、合规边界，以及由谁负责运营和维护——团队已经掌握的运维能力也是一种约束。范围弄错，会让技术上令人印象深刻的设计解决错误的问题——应在设计之前而不是之后向用户确认。命名之前，先阅读已经记录的决策（现有 ADR）和项目自己的术语表：重新命名代码库已有的概念，会迫使每位读者进行一次转换；悄然违背已接受的 ADR，则会让评审变成重新争论，而不是在此作出决策。
2. 粗略估算负载——每秒请求数、每年存储量、工作集大小、每次操作的扇出量。三行算术比任何图表都更能淘汰糟糕的设计；没有数字的设计只是凭感觉。写明假设，以便假设过时时读者能够重新计算。最后用一行写出该规模下的每月运行成本及其主要构成——根据同样的计算给出数量级，而不是列出价格清单。
3. 先勾勒契约，再写内部实现——API 端点或事件的输入和输出，以及包含核心实体及其不变量的数据模型。契约能在问题仍易于修正时暴露范围错误（HTTP 资源的详细设计参见 awesome-api-design）。先从代码着手：找到最接近的同类现有实现，并通过搜索而非凭记忆，列出契约变更会影响的所有调用方或使用者。在现有模式旁再引入第二种模式的设计，必须说明现有模式为何无法满足需求；而找到的每个使用者都必须出现在发布计划中。
4. 提出 2–3 个切实可行的备选方案——包括能够奏效的最简单方案（“什么也不做”或“一个 cron 任务加一张表”往往都是合理的候选方案）。仅为驳倒而添加的方案只是凑数；每个方案都要如实说明其最佳之处。
5. 根据需求涉及的权衡维度进行评估——不要使用固定的评估标准：一致性与可用性、同步与异步、SQL 与 NoSQL、扩展单体与新建服务、自建与购买、延迟与成本、团队已在运行的技术与团队不熟悉的技术。对于每个实际存在权衡的维度，说明需求倾向哪一侧以及原因；团队无人能运维的方案，不能仅凭技术维度胜出。跳过不存在权衡的维度——凑数会稀释关键分析。
6. 根据需求提出建议——只给出一个建议，并通过标签将其与驱动该建议的需求关联起来（“由于信息流可容忍 30 秒延迟，最终一致性已足够——因此可以采用成本更低的读时扇出”）。说明哪些新信息会改变决策，以及设计的上限：写明第 2 步中的哪个数字一旦超过，设计就会失效；哪个组件会最先出问题；届时下一步该怎么做——用一句话说明，而不是列出分阶段路线图。当未知信息会改变备选方案的选择时，不要猜测：文档应规定一次设有时间限制的验证试验——明确一个问题、完成标准、决策日期，以及不同结果分别对应哪个备选方案；在问题得到回答前，将其列入开放问题。
7. 先逆向推演，再制定缓解措施，然后明确非目标和路径——先反向进行风险评估：设想一年后，事实证明这项决策是错误的，设计正在被撤销。具体指出导致失败的三件事（例如“回填始终未完成，写入数据出现分歧”），而不是抽象地说“扩展风险”。逆向推演能揭示正向评估时容易被合理化带过的问题，因为“什么会导致失败”不能用“我们会小心”来回答。每个具体原因都必须对应一个读者实际可观察到的早期预警信号，以及缓解措施或书面接受的风险。然后明确非目标（此设计有意不解决什么问题，让范围蔓延必须面对明确的文字），列出主要风险及其缓解措施、现有数据和使用者的迁移／发布顺序，以及回滚方案（无法增量发布的设计必须在此说明，而不能等到 PR 阶段才发现）。必须提前用数字固定回滚标准——包括指标、阈值和观察窗口；同时列出每个发布窗口中要关注的可观测信号，以免事故处理中再争论。明确不可逆点：完成某个契约步骤（删除列或移除旧路径）之后，或新格式开始出现首次写入之后，回滚就会变成向前修复；文档必须说明在该节点之后该怎么做。

ADR 格式

# ADR-<n>: <decision, stated as a decision>
Status: proposed | accepted | superseded by ADR-<m>
Date: <date>

Context: <the forces — requirements, constraints, numbers — that make this a decision at all>
Decision: <what we will do, one paragraph, active voice>
Alternatives considered: <each with its honest best case and why it lost against the requirements>
Consequences: <what becomes easier, what becomes harder, what debt is accepted knowingly>
Non-goals: <what this decision deliberately does not cover>

Agent 简报（将决策交给实施者时）

设计文档向读者解释决策；简报则告诉实施者——无论是人员还是无人值守的 Agent——要构建什么。当工作交接给他人而非在同一会话中完成时，每个工作单元都应附上一份简报，并确保简报经得起时间推移：它可能搁置数天，而代码库在此期间不断变化。

持久性优先于精确性。描述接口、类型、配置结构和行为约定；切勿写文件路径或行号，因为它们很快就会过时，还会让实施者去找一个已不存在的文件。说明系统应该做 什么，而不是应该 如何 修改代码——实施者会自行探索当前代码树并作出实现决策。

## Brief: <one-line summary of what must happen>

Category:          feature | bug | migration
Current behavior:  <what happens today — the status quo the work builds on>
Desired behavior:  <what happens after, including edge cases and error conditions>
Key interfaces:    <the types, signatures, events or config shapes that change, and how>

Acceptance criteria:
- [ ] <requirement label> <specific, independently verifiable — "returns 409 on a duplicate
      idempotency key", not "handles duplicates correctly">

Out of scope:      <the adjacent thing that must NOT be touched, so gold-plating has to argue>

如果决策拆分为多份简报，请按依赖顺序发布，并在每份简报中列出阻塞它的简报，这样无需重新阅读文档也能看清哪些工作已就绪。

输出

完整设计文档：标题 → 问题与需求（附编号）→ 拟议设计（先写约定，再写内部实现）→ 备选方案与权衡 → 建议 → 非目标 → 风险与缓解措施 → 发布与回滚 → 待解决问题（明确标记，不要隐藏）。以 Markdown 文件形式放入仓库遵循的文档目录规范（docs/adr/、docs/design/ 或现有文档所在位置——先查明，不要自行发明）。文件名遵循所在目录的命名惯例，因此编号系列应使用下一个可用编号，而不是磁盘上已有的编号；绝不覆盖现有文档：如果设计文档要取代另一份文档，应在正文中说明，并将旧文件保留在原处，以免破坏审阅者引用的链接。

交付前自检

先解决机械性检查，这样阅读以下内容时，就能把注意力放在判断上，而不是寻找占位符上。每一行都是针对文档当前状态的一个是非问题；如何确认由你决定——可以通读、搜索，或为这份文档编写一次性检查并在之后丢弃。

阻断项：文档中只要有任何一项，就还不能交付：

• 正文中没有任何残留占位符：TBD、TODO、FIXME、需要引用的标记、lorem ipsum、“fill this in”、带方括号的 ，或以续写说明结尾的句子。
• 完整文档包含以下各项对应的章节：需求或问题、设计或提案、替代方案、建议或决策、非目标、风险，以及推出或回滚；每个章节下都有正文，不能只有标题。ADR 则必须包含 Status、Context、Decision、Alternatives considered 和 Consequences，且都不得为空。
• ADR 的状态必须是 proposed、accepted 或 superseded，不能是其他内容。
• 替代方案至少有两个，按列表项或表格行计数。一段文字提到一个选项，无论写得多长，都只算一个替代方案。
• 存在验收标准时，每个需求标签至少对应一项验收标准，且每项验收标准引用的标签都必须由需求章节明确定义。

警告项：每项都必须得到回应，或明确豁免：

• 开头三分之一至少包含一个数字。没有数量信息的背景说明，就没有明确陈述问题。
• 风险（或 ADR 的后果）必须指出一个早期预警信号：如果风险正在形成，读者会观察到什么。
• 完整文档必须有一个明确标出的开放问题章节，不能藏起来。

然后是无法通过检查解决的判断：

• 用一行陈述三条件测试的结论——说明这个决策为什么值得写成文档。
• 每个规模数字都必须能追溯到一个读者可以复算的明确假设；没有假设的数字，只是带数字的感觉。
• 必须有一项建议，按标签引用促成该建议的需求，说明什么新信息会改变建议，并指出其上限及最先出问题的组件。
• 站在每个替代方案的支持者立场重新审视：如果某个方案连自己最有利的情况都无法成立，那它就是稻草人论证——请替换或删除。
• 风险清单必须来自逆向推演，而非只列出方便缓解的风险：每项风险都要指出读者可观察到的早期预警信号；没有缓解措施的风险要写明已接受，不能删掉。
• 回滚方案必须写明一个数字触发条件（指标、阈值、时间窗口）和不可逆点，以及越过该点后会发生什么；会决定替代方案取舍的未知事项，应安排一次有日期的探查，而不是猜测。
• 必须包含非目标、回滚和明确标出的开放问题；任何未经确认而自行提出的需求，都要移至“开放问题”或删除。

反模式

反模式	应采取的做法
挑选组件——在明确需求前就指定技术	先列需求和数字；由此推导出技术
只比较取舍、不提出建议	每次比较都以一项关联需求的建议收尾
稻草人式替代方案	每个替代方案都先以最有力、最公允的方式论证，再说明为何不选
臆造需求（“我们可能需要多区域部署”）	只写明或确认过的需求；推测内容放到“非目标”
ADR 泛滥——每个可逆选择都单独写一份文档	使用三条件测试；可逆选择写在代码注释中
有设计、无推出计划	在文档中说明迁移顺序、向后兼容性和回滚方案
正向罗列风险，每项都附上令人安心的缓解措施	先逆向推演：指出导致失败的因素，再缓解已列出的原因
通过省略来悄悄解决开放问题	明确设置读者可以回答的“开放问题”章节