架构决策与文档

要解决的问题

代码能告诉你"做了什么"，但很少说明"为什么这么做"。一次选型的权衡、一套数据模型背后的妥协、某个公共接口被否决的历史，往往只留在口口相传里。后果很具体：新人或智能体接手时只能靠猜；同一个问题被反复解释；半年后没人记得当初为什么拒绝某个方案，于是它又被重新搬回来。

技能如何工作

核心思路是记录决策，而不是复述代码。 该技能围绕 ADR（Architecture Decision Record，架构决策记录）展开，把一次重大技术决策的上下文、约束和被考虑过的替代方案固化成文档。

触发时机包括：

• 在多个竞争方案之间做选型（框架、库、构建工具、托管平台）
• 设计数据模型或数据库 schema
• 确定认证策略与 API 架构（REST vs GraphQL vs tRPC 这类决策）
• 发布改变用户行为的 feature
• 需要反复向别人解释同一件事的时候

关键步骤：

1. 先找现有约定。 创建 ADR 前先检查仓库里是否已有 docs/adr/、.adr-dir、MADR 布局或 adr-tools 配置。已有约定优先于默认规则。
2. 沿用格式。 匹配现有目录位置、文件扩展名和标记语言（Markdown 或 reStructuredText）。
3. 续接编号。 按已有序列继续命名，如 ADR-004-Title.md，而不是从零重新编号。
4. 写清"为什么"。 记录背景、约束、取舍和放弃的替代方案，而非只有结论。

适用边界

反过来，不要为显而易见的代码写文档，不要把注释写成对代码的复述，也不要给一次性原型补 ADR。判断标准很简单：如果半年后还有人可能质疑、推翻或需要复用当时的理由，它就值得被记录。