Back to Details

writing-adrs

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Writing Architecture Decision Records

撰写架构决策记录（ADR）

What is an ADR?

什么是ADR？

An Architecture Decision Record captures an important architectural decision along with its context and consequences.
架构决策记录（ADR）用于记录重要的架构决策，以及其背景和产生的影响。

When to Write an ADR

何时撰写ADR

  • Choosing a framework or library
  • Selecting a database or storage solution
  • Defining API patterns
  • Establishing coding conventions
  • Making infrastructure decisions
  • Any decision that affects multiple components
  • 选择框架或库
  • 挑选数据库或存储方案
  • 定义API模式
  • 确立编码规范
  • 制定基础设施决策
  • 任何会影响多个组件的决策

ADR Structure

ADR结构

Title

标题

Short phrase describing the decision.
描述决策的简短短语。

Status

状态

  • Proposed: Under discussion
  • Accepted: Decision made
  • Rejected: Considered but not adopted
  • Deprecated: No longer valid
  • Superseded: Replaced by another ADR
  • 提议中：正在讨论
  • 已接受：已做出决策
  • 已拒绝：已考虑但未采纳
  • 已弃用：不再有效
  • 已取代：被其他ADR替代

Context

背景

What is the situation? What forces are at play?
当前的情况是什么？有哪些因素在起作用？

Decision

决策

What is the change we're making?
我们要做出什么改变？

Rationale

理由

Why is this the best choice?
为什么这是最佳选择？

Consequences

影响

What are the trade-offs? Both positive and negative.
有哪些权衡？包括正面和负面的影响。

Example ADR

ADR示例

markdown
undefined
markdown
undefined

ADR: Use PostgreSQL for Primary Database

ADR: Use PostgreSQL for Primary Database

Status

Status

Accepted
Accepted

Context

Context

We need a database for our new service. Requirements:
  • ACID transactions
  • JSON support
  • Strong ecosystem
  • Team familiarity
We need a database for our new service. Requirements:
  • ACID transactions
  • JSON support
  • Strong ecosystem
  • Team familiarity

Decision

Decision

We will use PostgreSQL 15+ as our primary database.
We will use PostgreSQL 15+ as our primary database.

Rationale

Rationale

  • Mature, reliable RDBMS
  • Excellent JSON support with JSONB
  • Strong extension ecosystem (pgvector, PostGIS)
  • Team has deep PostgreSQL experience
  • Well-supported by all cloud providers
  • Mature, reliable RDBMS
  • Excellent JSON support with JSONB
  • Strong extension ecosystem (pgvector, PostGIS)
  • Team has deep PostgreSQL experience
  • Well-supported by all cloud providers

Consequences

Consequences

Positive

Positive

  • Reliable, battle-tested technology
  • Rich feature set
  • Easy to find developers
  • Reliable, battle-tested technology
  • Rich feature set
  • Easy to find developers

Negative

Negative

  • Vertical scaling has limits
  • Requires careful connection management
  • More operational overhead than managed NoSQL
undefined
  • Vertical scaling has limits
  • Requires careful connection management
  • More operational overhead than managed NoSQL
undefined

Best Practices

最佳实践

  1. Keep them short: 1-2 pages max
  2. Write when deciding: Not after the fact
  3. Include alternatives: Show what was considered
  4. Update status: Mark deprecated/superseded ADRs
  5. Number sequentially: 
    ADR-001
    , 
    ADR-002
    , etc.
  1. 保持简短：最多1-2页
  2. 及时撰写：不要事后补写
  3. 包含备选方案：说明曾考虑过的选项
  4. 更新状态：标记已弃用/已取代的ADR
  5. 按顺序编号：
    ADR-001
    、
    ADR-002
    等