一句话

把决策的「为什么」留下来：ADR 记录架构决策，内联注释只写读者猜不到的，API 文档贴着类型走。

何时用

• 适合：做了架构决策要留痕；改公共 API、发功能；给后来的工程师和 agent 留上下文。
• 不适合：代码本身能说明白的 what；没人会读的长篇设计文档。

怎么用

给「改用 PostgreSQL 存任务」这个决定写一份 ADR

1. 先看项目现有约定，有 ADR 格式就沿用，不另起炉灶。
2. 按模板写：Status、Date、Context、Decision、Alternatives Considered、Consequences。
3. 内联注释只写 why 和已知坑，不复述代码做了什么。
4. API 文档优先贴着类型写，REST API 用 OpenAPI。
5. 交付前过 Prose Review：保住名字、数字、条件、限定词，删掉空话。

产出

• ADR-XXX 决策记录、内联注释、API 文档、README 结构。

要点与坑

• ADR 记决策和备选方案，不是工作日志；状态从 Proposed 到 Accepted、Superseded。
• 写 what 的注释会腐烂，只写 why 和 gotcha。
• Prose Review 是给文档做事实核查式润色，不许把没依据的保证写圆。

本机版本差异

仓库版新增 Prose Review 审校流程和 ADR 的 Proposed 状态，并要求润色后核对事实细节；本机旧版没有这段。

关联

• 上游：addy-spec-driven-development、addy-api-and-interface-design · 同类：matt-codebase-design
• 所属：00-addy-概览 · 工作流：W4-大型模糊项目