用途：该技能为在软件项目中记录实现决策提供统一约定，把决策以 ADR（架构决策记录）形式存放在 docs/decisions/ 目录，使团队能追溯“为什么这样做”以及撤回成本。
主要能力：
- 文件组织。每个决策一个文件，命名为 NNNN-short-title.md，使用四位且永不重复的编号；所有决策放同一文件夹，类型用字段表示而非文件夹；若仓库已有其他记录位置或格式，则沿用原有方案。
- 区分可逆与不可逆。不可逆指撤销需要数据迁移、会破坏已存数据，或破坏与用户、客户端、运维方的契约（如表结构、存储格式、公共 API 标识、环境变量格式、持久化数据中的标记）；可逆指只存在于代码中，撤销只是常规重构（如模块布局、接口后的库选择、中间件顺序、日志格式），其一次性副作用写入后果。
- ADR 格式。包含标题、日期、状态（Accepted、被修订、被取代、废弃）、类型、来源，以及 Context（问题与约束，必要时含测量数据）、Decision（所选方案，指明文件或设置）、Consequences（更易之处、更难之处及撤回成本）。
- README 索引。docs/decisions/README.md 按不可逆与可逆两组列出带链接的决策清单，编号跨两表唯一，须与 ADR 在同一提交中更新。
- 编号冲突处理。合并出现重复编号时，较旧分支保留编号，另一分支在最大编号后重新编号，并更新所有引用（如 ADR NNNN、Superseded by NNNN 及链接）。
- 何时写 ADR。出现依赖、架构模式或难以回退的决策时写；判断可问四个问题，任一为“是”即可：是否存在多个合理方案、日后撤销代价是否大、是否有其他部分依赖它、是否会有人问“为什么这样做”。此外，偏离规格或计划、改变先前决策的修复、评审发现的隐性决策（如缺少迁移路径、标识方案、被关闭的默认值）也应记录，即使结论是“暂时接受”。常规修复或已由 linter/formatter 检查的偏好不写，小选择放提交正文。改变先前决策时写新 ADR 并保留旧文：整体替换则标记 Superseded by NNNN；部分修改则标记 Accepted (amended by NNNN: 变更内容)，并在不再成立的段落下加 > Amended by NNNN。
使用方式：按上述格式在 docs/decisions/ 新建 ADR，同步更新 README 索引，并在同一提交中完成。提交前对照示例核对 Type（环境变量、公共 URL、存储格式即使代码改动很小也属不可逆）；每条后果须在提交时真实且有证据，如运行变异测试证明指定测试失败，或用 grep 验证指定文档，不得仅写“测试已固定”或“已记录”，也不得引用仓库外文件（如 .scratchpad/）。若 AGENTS.md 对此主题另有约定，则遵循 AGENTS.md。若项目关闭此技能，则改为在提交正文中为每个决策写明理由。
适用场景：需要长期留存实现决策依据的软件仓库，尤其是涉及表结构、数据格式、公共接口、环境变量等不可逆变更，或存在多种合理方案、后续撤销成本高的选择时。
限制：ADR 应控制在一页内；不适用于例行修复或格式类偏好；后果必须可验证，禁止无证据表述；编号不得重复；不得引用仓库外资料。