architecture-decision-record · diff

git:20260812.c55b6ba to git:20260905.751659e

7 added, 7 removed. Audit A to A.

---

name: architecture-decision-record

- description: 在已经形成具体技术决策，需要判断是否记录 ADR，或创建、更新、替代架构决策记录时使用。适用于有真实备选、非平凡取舍、难以回滚约束，或未来维护者需要理解“为什么”的场景。

+ description: 已有具体技术决策，需要判断是否记录 ADR，或创建、更新、替代 ADR 时使用。

---

# 架构决策记录

记录已经有足够上下文的决策，不替代前期架构探索。

## 是否值得记录

满足以下任意两项时，默认建议写 ADR：

1. 有多个认真考虑过的备选方案

2. 接受了真实且非平凡的成本

3. 决策不容易回滚或会约束未来设计

4. 只看代码无法理解为什么没有选择另一个方案

- 单点 bugfix、机械迁移、命名样式调整、沿用既有约定，或尚未形成选择时不写 ADR。理由较轻时放进 PR body、设计文档或代码注释。

+ 单点 bugfix、机械迁移、命名样式调整、沿用既有约定，或尚未形成选择时不写 ADR。理由较轻时放进 PR 正文、设计文档或代码注释。

## 评估模式

```text

结论：建议写 ADR / 不建议写 ADR

满足标准：<编号>

依据：<真实备选、约束和代价>

建议标题：<如适用>

```

## 创建流程

1. 收集决策背景、驱动因素、真实备选、最终选择、正负影响及 issue/PR/代码证据。

2. 检查仓库现有 ADR 目录和格式；有现行约定时优先沿用。

3. 默认路径为 `docs/adr/NNNN-<slug>.md`，编号取现有最大值加一，slug 使用小写短横线。

4. 使用 [ADR 模板](assets/adr-template.md)，删除不适用的占位内容，不虚构备选或验证结果。

5. 检查新决策是否明确替代旧 ADR。范围只是补充或局部扩展时不要标记替代。

6. 创建后复读事实、状态、链接、负面影响和替代关系。

## 更新与替代

已接受 ADR 应保留历史。只有新决策明确反转或替换旧选择时，才把旧 ADR 状态更新为：

```yaml

status: 被 ADR-NNNN 替代

```

标题相似或治理范围重叠只算候选，不足以自动替代。证据模糊时报告候选并保持旧文件不变。

## 写作约束

- 一个 ADR 只记录一个决策

- 只写真实考虑过的方案

- `负面影响` 必须写明接受的成本

- 语言保持事实性，不写宣传口吻

- 信息缺失时明确记录 gap

## 输出

```text

ADR: <path / 未创建>

- Title: <title>

- Status: <status>

- Supersedes: none / ADR-NNNN

- Known gaps: <gaps>

- Verification: <checks>

+ 标题：<标题>

+ 状态：<状态>

+ 替代记录：无 / ADR-NNNN

+ 已知缺口：<缺口>

+ 验证：<检查>

```