---
id: 0001
title: 记录架构决策（Record architecture decisions）
status: accepted
date: <YYYY-MM-DD>
tags: [foundational, governance]
---

# ADR-0001: 记录架构决策

## Context

我们需要一种方式记录项目演进过程中的架构决策。随着代码与团队规模增长，"为什么这么设计"的知识若只存在于个别成员脑中或散落的 chat / commit 里，会出现：

- 新成员无法理解既有设计意图
- 同一决策被反复讨论 / 推翻 / 再立
- 历史包袱无法被识别（"这块为什么不能动？"）

## Decision

我们采用 ADR (Architecture Decision Record) 流程：

- 每个非平凡决策一个 `wiki/decisions/NNNN-<slug>.md`
- 永不删，只能 supersede
- 编号永不复用
- 推翻必须写新 ADR 并 `koala-core adr supersede <old> <new>`

## Consequences

### 好处

- 决策有迹可循
- 防止反复重做同一决策
- 新成员能快速理解"为什么这么设计"

### 坏处

- 写 ADR 是额外工作
- 早期可能频繁 supersede

### 已知风险与缓解

- 风险：ADR 数量爆炸 → 缓解：季度 pruning sprint 评审无引用的 ADR
- 风险：ADR 内容过时 → 缓解：drift detector 检测代码与 ADR 一致性

## Alternatives considered

### A. Wiki 散文记录决策

**拒绝原因**：无强制结构，易腐烂。

### B. Commit message 详细描述决策

**拒绝原因**：散落在 git log 中难检索。

### C. ADR 流程（采纳）

来自 Michael Nygard 2011 提出，AWS / ThoughtWorks 10+ 年实践。

## References

- Michael Nygard (2011): ["Documenting Architecture Decisions"](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions)
- ThoughtWorks Technology Radar: ADRs

---

> 此文件由 koala-core init 创建为样例。
> 后缀 `.md.example` 让 koala-core adr 工具忽略它。
> 用 `koala-core adr new "<标题>"` 创建你自己的 0001。
