需要记录架构决策或设计理由时，用 ADR…

在做出重大架构决策、变更公共 API、发布功能或需要为未来工程师和 AI agent 保留上下文时，记录决策理由而非仅记录代码。

适用场景

解决思路

1. 先检查仓库中是否已有 ADR 约定：查看现有 ADR、项目说明、ADR 相关配置或工具（如 .adr-dir 文件）；已有约定优先于默认模板。
2. 匹配现有约定的位置与格式：沿用现有目录（如 docs/adr/*.md、Documentation/Decisions/*.rst）、文件扩展名和标记语言（Markdown 或 reStructuredText），不要另起一套。
3. 匹配现有编号与命名：延续已有序列和文件名模式（如 ADR-004-Title.rst、0004-title.md），不要从 001 重新开始或引入第二套编号方案。
4. 复用项目已有的章节标题集合，而不是强加模板中的标题；若证据冲突，先暴露冲突而不是默默引入新方案。
5. 仅在无法确定任何约定时，才使用默认模板：将 ADR 存放在 docs/decisions/ 并按顺序编号。
6. ADR 模板包含：标题（如 # ADR-001: Use PostgreSQL for primary database）、Status（Accepted | Superseded by ADR-XXX | Deprecated）、Date、Context（需求与约束）、Decision、Alternatives Considered（每个替代方案的 Pros、Cons、Rejected 理由）、Consequences。
7. 遵循 ADR 生命周期：PROPOSED → ACCEPTED → (SUPERSEDED 或 DEPRECATED)；不要删除旧 ADR，决策变更时写新 ADR 引用并取代旧的。
8. 在以下情况写 ADR：选择框架/库/主要依赖、设计数据模型或数据库 schema、选择认证策略、决定 API 架构（REST vs. GraphQL vs. tRPC）、选择构建工具/托管平台/基础设施、任何逆转成本高的决策。
9. 内联注释只写「为什么」不写「什么」：例如解释滑动窗口限流为何在窗口边界重置计数器以防突发攻击，而不是写「counter += 1」。
10. 不要注释自解释代码、不要留 TODO 注释（应直接做）、不要保留被注释掉的代码（直接删除，git 有历史）。
11. 用文档注释记录已知陷阱：如说明某函数必须在首次渲染前调用，否则水合后会导致无样式内容闪烁，并引用 ADR-003 获取完整设计理由。
12. 为公共 API（REST、GraphQL、库接口）写文档：TypeScript 优先用类型内联 JSDoc，包含 @param、@returns、@throws 和 @example。
13. REST API 使用 OpenAPI/Swagger 描述：在 paths 下定义 summary、requestBody、responses（如 201 创建成功、422 校验错误）及 schema 引用。
14. 每个项目 README 应覆盖：项目名与一段话描述、Quick Start（clone、npm install、cp .env.example .env、npm run dev）、Commands 表格（dev/test/build/lint）、Architecture 概述并链接 ADR、Contributing 指南。
15. 为已发布功能维护 Changelog：按版本和日期分组，使用 Added、Fixed、Changed 等小节并引用 issue 编号。
16. 为 AI agent 维护文档：用 CLAUDE.md / rules 文件记录项目约定，保持 spec 文件最新，用 ADR 帮助 agent 理解过去决策以避免重复决策，用内联陷阱说明防止 agent 踩坑。
17. 警惕常见借口：代码自解释只展示 what 不展示 why；等 API 稳定再写文档反而更慢，文档是设计的第一次测试；agent 和未来的工程师会读文档；10 分钟 ADR 可避免 6 个月后 2 小时的争论；只写「为什么」的注释是稳定的。
18. 识别红旗信号：架构决策无书面理由、公共 API 无文档或类型、README 不说明如何运行项目、用注释代码代替删除、TODO 注释存在数周、有重大架构选择却无 ADR、文档只是复述代码。
19. 文档完成后验证：所有重大架构决策都有 ADR、README 覆盖快速开始/命令/架构概述、API 函数有参数和返回类型文档、已知陷阱在相关位置内联记录、没有残留的注释代码、rules 文件（CLAUDE.md 等）保持最新准确。

适用边界 · 注意事项

• 不要为显而易见的代码写文档，不要添加只是复述代码的注释。
• 不要为一次性原型写文档。
• 当仓库中已有明确 ADR 约定时，不要套用默认模板或另起编号方案。