adr-authoring

ADR 编写

用于记录设计依据的架构决策记录。ADR 补充了时间维度——决策随时间的变化——这是仅展示结构的视图（C4）所缺少的。

首先遵循仓库约定

1. 起草前，阅读仓库的 Agent 指令、贡献指南、ADR 索引、模板和几篇近期记录。沿用现有的存放位置、编号、标题、状态术语、审批流程和修订政策。
2. 仅将此技能中的布局和模板作为备用方案。不要为了适配此技能而移动、重新编号、重命名或改写现有 ADR。如果本地约定存在冲突，应保留现有记录，并在更改约定前指出具体冲突。
3. 如果没有现成约定，请使用扁平的 docs/adr/ 目录、稳定的连续编号、简明索引和轻量级 Nygard 模板（需要更深入的选项分析时使用 MADR）。仅在建立新的决策日志时阅读 references/project-setup-guide.md。
4. 仅当项目已使用工件金字塔，或用户要求采用这种组织方式时，才阅读 references/adr-to-pyramid-mapping.md。索引链接可以提供分层导航，无需移动规范记录。

决策、审批与证据

使用仓库现有字段或关联记录，明确区分以下三项：

• 提案： 推荐方案、原因、备选方案、影响和未解决的问题。草案或建议不等于已接受的决策。
• 决策权限与范围： 谁在何时批准了什么，以及适用于哪个环境或阶段。批准进行实验仅允许开展有明确范围的实验，并不意味着已批准在生产环境中采用。如果明确限定了范围，已接受的 ADR 也可以仅授权开展实验。不要臆造决策者、日期或更广泛的批准。
• 实施证据： 指向变更、检查、观察结果和剩余差距的链接。接受决策并不能证明已完成实施；原型检查通过也不能证明已具备生产就绪条件。在结果尚未产生前，应将验证计划标记为计划中。

例如，“已批准进行隔离数据库试验”支持的是范围限定为试验的决策。成功完成恢复演练，是已测试恢复场景的证据；这两项事实单独来看，都不意味着“已在生产环境中采用该数据库”。

ADR 生命周期

遵循本地的生命周期和修订规则。若没有相关规则，则使用 proposed → accepted | rejected，已接受的决策之后可由关联的后继记录标记为 deprecated 或 superseded。

保留已接受决策的依据。默认情况下，决策变更时应新建 ADR；更新旧记录的状态和后继记录链接，同时保留其编号和位置。如果仓库使用持续更新的文档，则根据其政策进行注明日期和归属的修订。不要强行将不可变日志改为可变文档，也不要用不可变流程取代持续更新的文档流程。

记录拒绝和取代的原因，维护索引并保留链接。评审形式和会议时长遵循团队流程；接受决策需要相关决策权限的证据，而不需要强制举行特定仪式。

模板选择

优先使用仓库模板。仅当没有既定模板时，才适用下表。

适用情况	模板	章节
快速决策，依据单一	Nygard	状态、背景、决策、影响
多个选项的权衡分析	MADR	决策驱动因素、考虑过的选项、优缺点、链接
高风险、受监管、合规	Tyree & Akerman	12 个章节：问题、立场、论据、影响等
供应商/采购决策	Business Case	评估标准、成本/SWOT、建议
QA/合同驱动的环境	Planguage	标签、要点、优先级、利益相关方、风险

完整目录及逐章节指南见 references/adr-format.md。

文件命名约定

优先遵循本地约定。对于新日志，使用现在时祈使动词短语、小写连字符和 .md 扩展名：

001-choose-database.md
002-format-timestamps.md
003-manage-secrets.md

状态应写在文档标题中，而不是文件名中——状态变更不应要求重命名。

团队协作与治理

• 谁可以创建： 任何阅读过 ADR 流程文档的团队成员
• 适用情形： 影响未来决策缘由、跨团队协调、长期可维护性或外部接口的决策
• 通常不适用的情形： 已有标准涵盖的常规变更。当实验的授权、约束或后果需要持久记录其依据时，应记录范围明确的实验。
• 每份 ADR 的角色： 主要联系人、次要联系人、负责团队
• 修订： 遵循仓库政策；保留决策历史，并区分新证据与决策变更。

完整的治理模型和团队协作问题请参阅 references/adr-format.md。

适用性函数确认

适用范围： 当 ADR 中的主张可通过代码、配置、运行时遥测、定期审计或范围明确的人工审查进行核验时使用。

阅读 references/fitness-functions.md，以选择函数的范围、频率、证据、阈值、负责人、例外处理路径和退役规则。使用 templates/fitness-function-record.md 编写运行记录。ADR 应负责记录持久决策及其与确认机制的链接；实现和执行则应由项目的测试、CI、遥测或治理系统负责。

完成标准与边界

当所请求的 ADR 或审查遵循本地约定、在不臆造的前提下明确决策范围和权限、保留历史，并区分已观察到的证据与计划中的检查时，即视为完成。如果验收尚未确定，应提交拟议记录并指出缺少的决策，而不是声称已获验收。

不适用情形

系统级架构和变更顺序交由 software-architecture 处理；具体工具的实现交由相应的运维技能处理。本技能负责决策依据和确认链接，不负责执行实现或一般性的可观测性计划。

目录

• 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 — active→L2、superseded→L3、使用者路由
• references/fitness-functions.md — 用于选择、运行、解读、审查和退役检查的方法，将 ADR 主张与持久证据关联起来
• references/decision-sustainability.md — 用于在验收前评估 ADR 质量的 5 项可持续性标准和 8 条指南
• references/project-setup-guide.md — 在新项目中引入 ADR：目录设置、README 索引、CONTRIBUTING.md/AGENTS.md 文档、附有完整示例的先建 issue 再提 PR 工作流
• templates/fitness-function-record.md — 用于选择、运行、审查和退役适用性函数的可复用记录
• references/source-index.md — 本技能的来源和综合范围边界

权威参考资料

• Architecture Decision Record 社区仓库 — https://github.com/architecture-decision-record/architecture-decision-record
• Michael Nygard，《记录架构决策》 — https://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions

可移植性

本技能有意保持与宿主环境无关。使用 Agent 的常规机制加载此处列出的参考资料、模板和脚本。不要假设存在特定的配置文件系统、任务编排器、记忆服务或响应交接格式。