用途
Architecture Decision Records（ADR）技能用于编写和维护架构决策记录，遵循技术决策文档化的最佳实践。它帮助团队捕捉重大技术决策的背景与理由，适用于以下情况：做出重大架构决策、记录技术选型、记录设计权衡、帮助新团队成员入职、回顾历史决策、建立决策流程。
以下情况不适用：只需记录小型实现细节、变更为次要补丁或例行维护、没有架构决策需要捕捉。
核心概念
ADR 捕捉三部分内容：Context（为什么需要做决策）、Decision（决定了什么）、Consequences（产生什么结果）。
判断何时编写 ADR：应编写的情况包括采用新框架、选择数据库技术、API 设计模式、安全架构、集成模式；可跳过的情况包括次要版本升级、缺陷修复、实现细节、例行维护、配置变更。
ADR 生命周期：Proposed → Accepted → Deprecated → Superseded，以及 Rejected 分支。
主要能力与模板
技能提供五种模板：
- 标准 ADR（MADR 格式）：包含 Status、Context、Decision Drivers、Considered Options（含各选项优缺点）、Decision、Rationale、Consequences（正面/负面/风险）、Implementation Notes、Related Decisions、References。示例为「使用 PostgreSQL 作为主数据库」。
- 轻量级 ADR：包含 Status、Date、Deciders、Context、Decision、Consequences（Good/Bad/Mitigations）。示例为「前端开发采用 TypeScript」。
- Y-Statement 格式：单段式表达，包含背景、面对的约束、决定采用/反对的方案、期望达成的目标、接受的代价。示例为 API 网关选择。
- 弃用型 ADR：记录弃用某技术并迁移的计划，包含迁移分阶段计划、后果、经验教训。示例为「弃用 MongoDB 改用 PostgreSQL」。
- RFC 风格：包含 Summary、Motivation、Detailed Design、Drawbacks、Alternatives、Unresolved Questions、Implementation Plan、References。示例为订单管理采用事件溯源。
使用方式
目录结构：docs/adr/ 下包含 README.md（索引与指南）、template.md（团队模板）、按 NNNN-title-with-dashes.md 命名的记录文件。
创建流程：复制 template.md 为 NNNN-title-with-dashes.md，填写模板，提交 PR 评审，批准后更新索引。
状态定义：Proposed（讨论中）、Accepted（已决策、实施中）、Deprecated（不再相关）、Superseded（被另一 ADR 替代）、Rejected（考虑过但未采用）。
自动化（adr-tools）：
brew install adr-tools
adr init docs/adr
adr new "Use PostgreSQL as Primary Database"
adr new -s 3 "Deprecate MongoDB in Favor of PostgreSQL"
adr generate toc > docs/adr/README.md
adr link 2 "Complements" 1 "Is complemented by"
评审检查清单：提交前确认背景清晰、可行选项均已考虑、优缺点平衡诚实、后果（正负）已记录、相关 ADR 已链接；评审时确认至少两名资深工程师评审、受影响团队已咨询、安全影响已考虑、成本影响已记录、可逆性已评估；接受后更新索引、通知团队、创建实施工单、更新相关文档。
最佳实践
应做：在实施开始前尽早编写 ADR；保持简短（最多 1-2 页）；诚实对待权衡，包含真实的缺点；链接相关决策以构建决策图；状态变化时更新（被替代时标记弃用）。
不应做：不要修改已接受的 ADR（应编写新 ADR 替代）；不要跳过背景；不要隐藏失败；不要含糊；不要忘记落实。
适用场景与限制
适用于需要文档化重大技术决策、技术选型、架构取舍、帮助团队传承决策历史的工程团队。资料未提供该技能的具体收费、价格、平台限制或效果承诺，相关内容暂未提供。