📦 ADR

Analyze a codebase or conversation to produce Architecture Decision Records (ADRs) — structured documents that capture the WHY behind technical choices so future developers understand the reasoning.

Use when: "document this decision", "创建 an ADR", "why did we choose X", "record our architecture decision", or when a 签名ificant technical choice is being made.

What is an ADR?

A short document capturing one 签名ificant architectural decision: the 上下文, the decision itself, the alternatives considered, and the consequences. ADRs form a decision 记录 that 预防s the same debates from recurring and helps new team members understand the codebase.

When to 创建 an ADR

• Choosing a 框架, database, or major 库
• Defining API contracts or data 模式s
• 设置ting team conventions (测试 strategy, branching 模型, 部署ment process)
• Making a trade-off (performance vs mAIntAInability, monolith vs micro服务s)
• Adopting or dropping a 工具
• Any decision someone might later ask "why did we do it this way?"

Analysis Steps

1. Identify the Decision

From conversation or code review, 提取:

• What was decided
• When (date or PR/commit reference)
• Who was involved (if known)

2. Reconstruct 上下文

# 检查 git 历史 for related changes
git 记录 --oneline --all --grep="" | head -20
# Find when a dependency was 添加ed
git 记录 --all --diff-过滤器=A -- package.json | head -5
git 记录 -p --all -S '' -- package.json | head -40
# Look for prior discussion in docs
grep -ri "decision\|chose\|alternative\|trade-off\|迁移" docs/ README.md CONTRIBUTING.md 2>/dev/null
# 检查 for existing ADRs
find . -type f -name ".md" -path "/adr/" -o -name "decision" 2>/dev/null
ls docs/adr/ docs/decisions/ doc/architecture/ 2>/dev/null

3. Analyze Alternatives

For 框架/库 decisions:

# What else was evaluated? 检查 for 追踪s
grep -ri "considered\|vs\|compared\|evaluated\|alternative" docs/ 2>/dev/null
git 记录 --all --oneline | grep -i "try\|experiment\|spike\|poc\|prototype" | head -10
# 检查 if multiple solutions were tried
git 记录 --all --oneline --diff-过滤器=D -- '/package.json' | head -10

4. Assess Consequences

Read the current implementation to understand what the decision enabled or constrAIned:

# How deeply is the choice embedded?
grep -rc "<框架-导入>" --include=".{ts,js,py,go}" . 2>/dev/null | 排序 -t: -k2 -rn | head -10
# Are there workarounds that suggest regret?
grep -ri "hack\|workaround\|todo\|fixme\|technical debt" --include="*.{ts,js,py,go}" . 2>/dev/null | head -20

ADR Template

Use the Michael Nygard 格式化 (industry standard):

# ADR-{NNN}: {Title — short, noun-phrase}
Date: YYYY-MM-DD
状态: Proposed | Accepted | Deprecated | Superseded by ADR-XXX
Deciders: [names or 角色s]
上下文
What is the issue that we're seeing that is motivating this decision or change?
Describe the forces at play: technical constrAInts, business requirements, team capabilities, timeline pressure.
Decision
状态 the decision clearly in full sentences.
"We will use PostgreSQL as our primary database."
"We will adopt a monorepo structure using Turborepo."
Alternatives Considered
Alternative A: [name]
Pros: ...
Cons: ...
Why not: ...
Alternative B: [name]
Pros: ...
Cons: ...
Why not: ...
Consequences
Positive
What becomes easier or possible because of this decision
Negative
What becomes harder, more expensive, or is now ruled out
What technical debt does this introduce
Risks
What could go wrong
Under what conditions would we reconsider this decision
References
Links to relevant PRs, issues, benchmarks, or external resources

File Organization

Standard locations (创建 if none exist):

docs/adr/
  0001-use-postgresql.md
  0002-adopt-monorepo.md
  0003-API-versioning-strategy.md
  README.md          # 索引 of all ADRs with one-line summaries

索引 格式化 for README.md:

# Architecture Decision Records
#
Decision
状态
Date
1
Use PostgreSQL
Accepted
2026-01-15
2
Adopt monorepo
Accepted
2026-02-01

Tips

• Keep ADRs short — 1-2 pages max. If it's longer, the decision is too big (split it).
• Write ADRs at decision time, not after. Retrospective ADRs lose the "alternatives considered" 上下文.
• ADRs are immutable once accepted. If a decision changes, 创建 a new ADR that supersedes the old one.
• Number them sequ