architecture-decision-record git:20260810.2f916d1A

Immutable. This exact content never changes and is served at /api/v1/blob/eee5709cd1920347.

---
name: architecture-decision-record
description: 在已经形成具体技术决策、需要判断是否应记录 ADR，或需要创建/更新架构决策记录时使用。适用于有真实备选方案、取舍、不可逆约束或未来维护者需要理解“为什么这么选”的场景。
---

# 架构决策记录

## 目标

判断一个技术决策是否值得写成 ADR，并在需要时创建或更新 `docs/adr/NNNN-<slug>.md`。

本 skill 不替代架构探索。它只记录已经有足够上下文的决策：为什么要选、认真考虑过哪些备选、接受了什么代价、未来维护者应该知道什么。

## 何时使用

- 用户明确要求写 ADR、decision record、架构决策记录
- `brainstorming` 或 `writing-plans` 已经比较过多个方案，并确认了一个会影响未来实现的选择
- 改动引入新的数据模型、存储、队列、缓存、权限边界、外部服务、部署方式或兼容策略
- 未来读代码的人如果只看 diff，会不知道为什么没有选另一个方案

## 何时不要使用

- 只是单点 bugfix、命名调整、样式修改或机械迁移
- 没有真实备选方案，只是采用仓库既有约定
- 决策还没有成形，还需要先做探索或方案对比
- 用户只是要实现，不希望新增文档；这时只在计划或总结里标记文档债务

## ADR 值得记录的标准

满足下面任意 2 条，默认建议写 ADR：

1. 有多个认真考虑过的备选方案
2. 有非平凡取舍：接受了真实成本，而不是单纯“X 更好”
3. 不容易回滚，或会约束未来设计
4. 如果缺少“为什么”，未来维护者会困惑

只满足 1 条时，通常不写 ADR；把理由放到 PR body、设计文档或代码注释中即可。

## 工作模式

### 评估

用于判断是否应该写 ADR。

输出：

```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>

- 优点：<原因>
- 缺点：<原因>
```

## 替代规则

旧 ADR 只有在新决策明确替代它时才更新为：

```yaml
status: 被 ADR-NNNN 替代
```

判断候选时看：

- 标题、slug 或治理范围高度重叠
- 新决策明确反转旧决策
- 新方案替换旧方案，而不是补充或局部扩展

模糊时输出 `被替代 ADR：无`，不要擅自更新旧文件。

## 写作规则

- 一个 ADR 只记录一个决策
- 只写真实考虑过的备选，不补虚构选项
- `负面影响` 必须有内容；没有代价的 ADR 像销售文案
- 语言保持事实性，不写宣传口吻
- 信息缺失时明确写 gap，不假装已经知道

## 输出契约

创建后输出：

```text
ADR 路径：
标题：
状态：
被替代 ADR：无 / ADR-NNNN
已知缺口：
验证：
```