architecture-decision-record git:20260812.c55b6baA

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

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

# 架构决策记录

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

## 是否值得记录

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

1. 有多个认真考虑过的备选方案
2. 接受了真实且非平凡的成本
3. 决策不容易回滚或会约束未来设计
4. 只看代码无法理解为什么没有选择另一个方案

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

## 评估模式

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