架构决策记录

先别急着写文档，先想清楚要记什么

很多仓库的 README.md 只复制了命令行参数，docs/ 目录里躺着一份过期的架构图，新人（或者 agent）接手时只能靠翻提交记录猜当年为什么这么选。真正有价值的文档记录的是 why：当时的约束是什么、备选方案有哪些、为什么最后选了 PostgreSQL 而不是 MongoDB。这个技能针对的就是这个缺口——它把「决策」当作一等公民，而不是代码的附属说明。

它是怎么工作的

核心分三层：

1. ADR 优先。 遇到框架选型、数据模型设计、认证策略、API 架构这类代价高昂的决策时，写一份 Architecture Decision Record。技能会先检查仓库里是否已有既定约定——.adr-dir、docs/adr/、adr-tools、MADR 布局——有就完全沿用，包括目录位置、文件后缀、编号方式（ADR-004-Title.rst 而不是从 001 重开）和章节标题。只有确认没有约定时才回退到默认模板 docs/decisions/。如果发现证据互相冲突，要明确指出冲突，而不是悄悄加进第二种方案。

2. 不删除旧 ADR。 ADR 是历史上下文的载体。决策变更时写一份新的，引用并取代旧的，而不是把旧文件删掉。

3. 分层补文档。 行内注释只写 why，不写 what；公共 API 用 OpenAPI/Swagger 或类型内联；README 覆盖快速开始、常用命令和架构概览；CLAUDE.md 这类规则文件让 agent 也能遵守项目约定。

什么时候不该用

• 明显的代码不需要文档，重述代码的注释只会增加噪音
• 一次性原型、实验性脚本不必写 ADR
• 「等 API 稳定了再补文档」是个陷阱——文档是设计的第一道测试，边写边改通常比事后补更快

写完后可以用技能提供的 checklist 自查：重要架构决策是否有 ADR、README 是否完整、函数是否有参数与返回类型说明、已知陷阱是否就地记录、是否存在遗留的注释代码。