用途
该技能用于创建、维护和管理架构决策记录（Architecture Decision Records，ADR），帮助团队捕获重大技术决策背后的背景与理由。当需要做出重大架构决策、记录技术选型、记录设计权衡、帮助新成员入职、回顾历史决策或建立决策流程时，可使用本技能。
不适用场景：只需记录小型实现细节、变更属于小补丁或日常维护、或不存在需要捕获的架构决策时，不应使用本技能。
主要能力
- 捕获决策的背景、约束和驱动因素。
- 记录已考虑的选项及其权衡。
- 记录决策、理由和后果。
- 关联相关 ADR，并随时间更新状态。
核心概念
- 什么是 ADR：ADR 捕获背景（为什么需要做决策）、决策（决定了什么）、后果（结果是什么）。
- 何时编写 ADR：应编写 ADR 的情况包括新框架采用、数据库技术选择、API 设计模式、安全架构、集成模式；可跳过 ADR 的情况包括次要版本升级、缺陷修复、实现细节、日常维护、配置变更。
- ADR 生命周期：Proposed → Accepted → Deprecated → Superseded，另有 Rejected 分支。
模板
技能提供五种模板：
- 模板 1：标准 ADR（MADR 格式），包含状态、背景、决策驱动因素、已考虑选项、决策、理由、后果（正面/负面/风险）、实现说明、相关决策、参考。
- 模板 2：轻量级 ADR，包含状态、日期、决策者、背景、决策、后果（好/坏/缓解措施）。
- 模板 3：Y-Statement 格式，以“在……背景下，面对……，我们决定采用……而非……，以实现……，接受……”的单句结构表达。
- 模板 4：弃用型 ADR，包含状态（取代某 ADR）、背景、决策、迁移计划、后果、经验教训。
- 模板 5：RFC 风格，包含摘要、动机、详细设计、缺点、替代方案、未解决问题、实施计划、参考。
使用方式
目录结构
docs/adr/ 下包含 README.md（索引与指南）、template.md（团队模板）以及按编号命名的 ADR 文件。
ADR 索引
README.md 中以表格形式列出 ADR 编号、标题、状态、日期，并说明创建新 ADR 的步骤（复制模板、填写、提交 PR 评审、批准后更新索引）以及各状态含义。
自动化（adr-tools）
安装：brew install adr-tools
初始化：adr init docs/adr
创建新 ADR：adr new "Use PostgreSQL as Primary Database"
取代某 ADR：adr new -s 3 "Deprecate MongoDB in Favor of PostgreSQL"
生成目录：adr generate toc > docs/adr/README.md
关联 ADR：adr link 2 "Complements" 1 "Is complemented by"
评审流程
提交前检查：背景是否清晰说明问题、是否考虑所有可行选项、利弊是否平衡诚实、后果（正负）是否记录、相关 ADR 是否关联。
评审中检查：至少 2 名资深工程师评审、咨询受影响团队、考虑安全影响、记录成本影响、评估可逆性。
接受后检查：更新 ADR 索引、通知团队、创建实现工单、更新相关文档。
最佳实践
应做：尽早编写 ADR（实现开始前）、保持简短（最多 1-2 页）、诚实对待权衡（包含真实缺点）、关联相关决策（构建决策图）、更新状态（被取代时标记弃用）。
不应做：不要修改已接受的 ADR（应编写新 ADR 取代）、不要跳过背景、不要隐藏失败（被拒绝的决策也有价值）、不要含糊、不要忘记实现。
适用场景
适用于需要记录重大技术决策背景与理由的团队，例如选择数据库、采用新框架、设计 API 模式、制定安全架构、定义集成模式等。也适用于新成员入职时了解历史决策，以及回顾和审查过往决策。
限制
仅当任务明确匹配上述范围时使用本技能。不应将输出视为环境特定验证、测试或专家评审的替代品。如果缺少必要输入、权限、安全边界或成功标准，应停止并请求澄清。