ADR Authoring 是一个围绕架构决策记录（Architecture Decision Records，ADR）编写的技能，用于捕获设计决策及其理由。其核心观点是：ADR 提供了仅看结构（如 C4）所缺失的时间维度——即决策随时间演进的路径。没有 ADR，智能体只能看到结构的快照，无法重建导致该结构的决策路径。
用途与定位 该技能面向需要记录架构决策理由、备选方案与后果的工程团队。活跃 ADR 位于 L2 提供决策理由，被取代的 ADR 位于 L3 保留被拒绝备选方案的历史。
ADR 到 Artifact Pyramid 的映射
- 导航索引：L1（摘要），路径 01-summary/adr-index.md
- 活跃 ADR：L2（分析），路径 02-analysis/architecture-decisions/ADR-NNN.md
- 被取代的 ADR：L3（档案），路径 03-dossiers/adr-superseded.md
ADR 生命周期 ADR 经历六个阶段，每个阶段有门槛标准：Initiating → Researching → Evaluating → Implementing → Maintaining → Sunsetting。
- Initiating：状态 proposed，位于 L2，面向评估中的工程师
- Researching：状态 proposed，位于 L2，面向评估中的工程师
- Evaluating：状态 proposed，位于 L2，面向决策中的工程师
- Implementing：状态 accepted，位于 L2，面向实现者与评审者
- Maintaining：状态 accepted，位于 L2，面向新团队成员与审计者
- Sunsetting：状态 deprecated/superseded，位于 L3，面向历史研究者 所有活跃 ADR（proposed + accepted）留在 L2。只有被取代/弃用的 ADR 移入 L3。被拒绝的 proposed ADR 应移入 L3，状态标记为 rejected，并附上拒绝原因说明。
备选生命周期：AWS ADR 流程 AWS Prescriptive Guidance 定义了互补的生命周期，为偏好正式不可变性的团队提供结构化评审流程。状态：proposed → accepted | rejected | superseded。关键区别：AWS 将 ADR 视为一旦接受即严格不可变；更改决策需要创建新 ADR 来取代旧 ADR。社区 ADR 仓库的团队协作建议则偏好可变的活文档，带日期戳更新。应选择适合团队文化的模型。 AWS 评审流程：
- 提案——任何团队成员创建 proposed 状态的 ADR，作者即 ADR 负责人。
- 评审会议——专门时间段，结构化格式：10-15 分钟静默阅读（每人阅读 ADR 并添加评论）；评论宣读（负责人逐条朗读评论，团队讨论）；行动点（识别的问题分配负责人并跟踪至解决）。
- 决策——三种结果：Accepted（负责人添加时间戳、版本、利益相关者列表，状态改为 accepted，不可变）；Rework（状态保持 proposed，负责人解决行动点并重新安排评审）；Rejected（负责人记录拒绝原因以防未来重复争论，状态改为 rejected，文件移入 L3）。
- 取代——新决策使已接受的 ADR 失效时，创建新 ADR；新 ADR 被接受后，将旧 ADR 状态更新为 superseded 并移入 L3。
模板选择
- 快速决策、单一理由：Nygard，章节为 Status、Context、Decision、Consequences
- 多选项权衡分析：MADR，章节为 Decision Drivers、Considered Options、Pros/Cons、Links
- 高风险、监管、合规：Tyree & Akerman，12 个章节：Issue、Positions、Argument、Implications 等
- 供应商/采购决策：Business Case，评估标准、Cost/SWOT、Recommendations
- QA/合同驱动环境：Planguage，Tag、Gist、Priority、Stakeholders、Risks 完整目录及逐节指引见 references/adr-format.md。
文件命名规范 使用现在时祈使动词短语、小写连字符、.md 扩展名，例如：001-choose-database.md、002-format-timestamps.md、003-manage-secrets.md。状态写在文档头部而非文件名中——状态变化不应要求重命名。
团队协作与治理
- 谁可创建：任何已阅读 ADR 流程文档的团队成员
- 什么值得记录：影响未来“为什么”的决策、跨团队协调、长期可维护性、外部接口
- 什么不值得：范围/时间/风险有限、已被标准覆盖、临时变通方案/POC
- 每个 ADR 的角色：主要联系人、次要联系人、负责团队
- 偏好活文档：插入带日期戳的新信息，而非为每次更新取代 ADR。不可变性理论上理想，可变性在实践中效果更好。 完整治理模型与团队协作问题见 references/adr-format.md。
配套内容
- references/adr-format.md——模板目录（11 种格式：Nygard、MADR、Tyree & Akerman、Business Case、Planguage、Alexandrian、ITD、arc42、EdgeX、Gareth Morgan、NHS Wales）、模板选择决策树、生命周期阶段、文件命名、团队治理、示例参考
- references/adr-to-pyramid-mapping.md——活跃→L2、被取代→L3、消费者路由
- references/fitness-functions.md——决策即代码：ArchUnit、ArchUnitTS、AI 辅助适应度函数、金字塔映射（适应度函数→L3）
- references/decision-sustainability.md——5 项可持续性标准 + 8 条指南，用于在接受前评估 ADR 质量
- references/project-setup-guide.md——在新项目中引导 ADR：目录设置、README 索引、CONTRIBUTING.md/AGENTS.md 文档、issue-first PR 工作流及完整示例
权威参考
- Architecture Decision Record 社区仓库——https://github.com/architecture-decision-record/architecture-decision-record
- Michael Nygard，“Documenting Architecture Decisions”——https://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions
- Magnus Hedemark，“Clanker Technical Architect: First on the Scene with Progressive Disclosure”——https://magnus919.com/2026/05/clanker-technical-architect-first-on-the-scene-with-progressive-disclosure/