architecture-decision-record · diff
git:20260810.2f916d1 to git:20260812.c55b6ba
33 added, 131 removed. Audit A to A.
---
name: architecture-decision-record
- description: 在已经形成具体技术决策、需要判断是否应记录 ADR，或需要创建/更新架构决策记录时使用。适用于有真实备选方案、取舍、不可逆约束或未来维护者需要理解“为什么这么选”的场景。
+ description: 在已经形成具体技术决策，需要判断是否记录 ADR，或创建、更新、替代架构决策记录时使用。适用于有真实备选、非平凡取舍、难以回滚约束，或未来维护者需要理解“为什么”的场景。
---
# 架构决策记录
- ## 目标
-
- 判断一个技术决策是否值得写成 ADR，并在需要时创建或更新 `docs/adr/NNNN-<slug>.md`。
-
- 本 skill 不替代架构探索。它只记录已经有足够上下文的决策：为什么要选、认真考虑过哪些备选、接受了什么代价、未来维护者应该知道什么。
-
- ## 何时使用
-
- - 用户明确要求写 ADR、decision record、架构决策记录
- - `brainstorming` 或 `writing-plans` 已经比较过多个方案，并确认了一个会影响未来实现的选择
- - 改动引入新的数据模型、存储、队列、缓存、权限边界、外部服务、部署方式或兼容策略
- - 未来读代码的人如果只看 diff，会不知道为什么没有选另一个方案
-
- ## 何时不要使用
-
- - 只是单点 bugfix、命名调整、样式修改或机械迁移
- - 没有真实备选方案，只是采用仓库既有约定
- - 决策还没有成形，还需要先做探索或方案对比
- - 用户只是要实现，不希望新增文档；这时只在计划或总结里标记文档债务
+ 记录已经有足够上下文的决策，不替代前期架构探索。
- ## ADR 值得记录的标准
+ ## 是否值得记录
- 满足下面任意 2 条，默认建议写 ADR：
+ 满足以下任意两项时，默认建议写 ADR：
1. 有多个认真考虑过的备选方案
- 2. 有非平凡取舍：接受了真实成本，而不是单纯“X 更好”
- 3. 不容易回滚，或会约束未来设计
- 4. 如果缺少“为什么”，未来维护者会困惑
-
- 只满足 1 条时，通常不写 ADR；把理由放到 PR body、设计文档或代码注释中即可。
-
- ## 工作模式
-
- ### 评估
+ 2. 接受了真实且非平凡的成本
+ 3. 决策不容易回滚或会约束未来设计
+ 4. 只看代码无法理解为什么没有选择另一个方案
- 用于判断是否应该写 ADR。
+ 单点 bugfix、机械迁移、命名样式调整、沿用既有约定，或尚未形成选择时不写 ADR。理由较轻时放进 PR body、设计文档或代码注释。
- 输出：
+ ## 评估模式
```text
结论：建议写 ADR / 不建议写 ADR
- 满足标准：1, 3
- 原因：<一句话，必须基于上面的标准>
- 建议标题：<如果推荐写 ADR>
+ 满足标准：<编号>
+ 依据：<真实备选、约束和代价>
+ 建议标题：<如适用>
```
- ### 创建
-
- 用于创建 ADR。
-
- 1. 收集决策上下文：
- - 决策摘要
- - 为什么需要这个决策
- - 真正考虑过的备选方案
- - 已知取舍和接受的成本
- - 最终选择
- - 可参考的 issue、PR、计划、代码或会议记录
- 2. 检查 `docs/adr/`：
- - 不存在则创建
- - 读取已有 ADR，确定下一个编号
- - 扫描是否可能替代旧 ADR
- 3. 如果存在替代候选，只作为提示，不自动修改旧 ADR。必须先让用户确认明确目标。
- 4. 使用下面模板创建新文件。
-
- ## 文件约定
-
- - 目录：`docs/adr/`
- - 文件名：`NNNN-<slug>.md`
- - 编号：4 位数字，从现有最大编号 +1
- - slug：小写、短横线、描述决策，例如 `use-postgresql`、`event-driven-notifications`
-
- ## 模板
-
- ```markdown
- ---
- status: 已接受
- date: YYYY-MM-DD
- ---
-
- # <简短标题：说明做了什么决策>
-
- ## 背景与问题
-
- 说明为什么需要这个决策，以及让选择变得不简单的约束、风险或需求。
-
- ## 决策驱动因素
-
- - <关键约束或需求>
- - <另一个驱动因素，如有>
-
- ## 考虑过的方案
-
- - <方案 A>
- - <方案 B>
- - <方案 C>
-
- ## 决策结果
-
- 最终选择："<方案 X>"，因为 <结合决策驱动因素给出简短理由>。
-
- ### 正面影响
-
- - <这个选择带来的改进或能力>
-
- ### 负面影响
-
- - <接受的成本。本节必须有内容。>
-
- ## 各方案优缺点
-
- ### <方案 A>
-
- - 优点：<原因>
- - 缺点：<原因>
-
- ### <方案 B>
+ ## 创建流程
- - 优点：<原因>
- - 缺点：<原因>
- ```
+ 1. 收集决策背景、驱动因素、真实备选、最终选择、正负影响及 issue/PR/代码证据。
+ 2. 检查仓库现有 ADR 目录和格式；有现行约定时优先沿用。
+ 3. 默认路径为 `docs/adr/NNNN-<slug>.md`，编号取现有最大值加一，slug 使用小写短横线。
+ 4. 使用 [ADR 模板](assets/adr-template.md)，删除不适用的占位内容，不虚构备选或验证结果。
+ 5. 检查新决策是否明确替代旧 ADR。范围只是补充或局部扩展时不要标记替代。
+ 6. 创建后复读事实、状态、链接、负面影响和替代关系。
- ## 替代规则
+ ## 更新与替代
- 旧 ADR 只有在新决策明确替代它时才更新为：
+ 已接受 ADR 应保留历史。只有新决策明确反转或替换旧选择时，才把旧 ADR 状态更新为：
```yaml
status: 被 ADR-NNNN 替代
```
- 判断候选时看：
-
- - 标题、slug 或治理范围高度重叠
- - 新决策明确反转旧决策
- - 新方案替换旧方案，而不是补充或局部扩展
-
- 模糊时输出 `被替代 ADR：无`，不要擅自更新旧文件。
+ 标题相似或治理范围重叠只算候选，不足以自动替代。证据模糊时报告候选并保持旧文件不变。
- ## 写作规则
+ ## 写作约束
- 一个 ADR 只记录一个决策
- - 只写真实考虑过的备选，不补虚构选项
- - `负面影响` 必须有内容；没有代价的 ADR 像销售文案
+ - 只写真实考虑过的方案
+ - `负面影响` 必须写明接受的成本
- 语言保持事实性，不写宣传口吻
- - 信息缺失时明确写 gap，不假装已经知道
-
- ## 输出契约
+ - 信息缺失时明确记录 gap
- 创建后输出：
+ ## 输出
```text
- ADR 路径：
- 标题：
- 状态：
- 被替代 ADR：无 / ADR-NNNN
- 已知缺口：
- 验证：
+ ADR: <path / 未创建>
+ Title: <title>
+ Status: <status>
+ Supersedes: none / ADR-NNNN
+ Known gaps: <gaps>
+ Verification: <checks>
```