Back to Details

adr-writer

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

ADR Writer

ADR编写指南

Document architecture decisions with clear context, alternatives, and consequences.
记录架构决策，包含清晰的背景、备选方案和影响结果。

ADR Template

ADR模板

markdown
undefined
markdown
undefined

ADR-001: [Title of Decision]

ADR-001: [决策标题]

Status: Proposed | Accepted | Deprecated | Superseded by ADR-XXX Date: 2024-01-15 Deciders: Alice (Tech Lead), Bob (Principal Engineer) Owner: Alice
状态: 提议中 | 已通过 | 已弃用 | 被ADR-XXX取代 日期: 2024-01-15 决策人: Alice（技术负责人）, Bob（首席工程师） 负责人: Alice

Context

背景

What is the issue we're facing? What factors are driving this decision?
We need to choose a database for our new analytics service. Current requirements:
  • 10M+ events per day
  • Complex aggregation queries
  • Real-time dashboards
  • Budget: $5k/month
  • Team familiar with SQL
我们面临什么问题？哪些因素推动了这个决策？
我们需要为新的分析服务选择数据库。当前需求：
  • 10M+ events per day
  • Complex aggregation queries
  • Real-time dashboards
  • Budget: $5k/month
  • Team familiar with SQL

Decision

决策

We will use PostgreSQL with TimescaleDB extension.
We will use PostgreSQL with TimescaleDB extension.

Alternatives Considered

备选方案评估

Option 1: PostgreSQL + TimescaleDB (CHOSEN)

Option 1: PostgreSQL + TimescaleDB (CHOSEN)

Pros:
  • Team already knows PostgreSQL
  • Time-series optimization for analytics
  • Reliable and proven
  • Good query performance
  • Reasonable cost (~$3k/month)
Cons:
  • Requires manual scaling effort
  • Not purpose-built for analytics
Pros:
  • Team already knows PostgreSQL
  • Time-series optimization for analytics
  • Reliable and proven
  • Good query performance
  • Reasonable cost (~$3k/month)
Cons:
  • Requires manual scaling effort
  • Not purpose-built for analytics

Option 2: ClickHouse

Option 2: ClickHouse

Pros:
  • Excellent query performance for analytics
  • Built for analytics workloads
  • Column-oriented storage
Cons:
  • Team unfamiliar with ClickHouse
  • Steeper learning curve
  • Different query syntax
Pros:
  • Excellent query performance for analytics
  • Built for analytics workloads
  • Column-oriented storage
Cons:
  • Team unfamiliar with ClickHouse
  • Steeper learning curve
  • Different query syntax

Option 3: BigQuery

Option 3: BigQuery

Pros:
  • Fully managed
  • Excellent for analytics
  • Scales automatically
Cons:
  • Higher cost (~$8k/month for our volume)
  • Vendor lock-in to GCP
  • Less control over optimization
Pros:
  • Fully managed
  • Excellent for analytics
  • Scales automatically
Cons:
  • Higher cost (~$8k/month for our volume)
  • Vendor lock-in to GCP
  • Less control over optimization

Tradeoffs

权衡因素

What we're optimizing for:
  • Team velocity (familiar tech)
  • Cost efficiency
  • Good enough performance
What we're sacrificing:
  • Peak analytical performance (vs ClickHouse)
  • Fully managed experience (vs BigQuery)
我们优先优化的方向:
  • Team velocity (familiar tech)
  • Cost efficiency
  • Good enough performance
我们做出的牺牲:
  • Peak analytical performance (vs ClickHouse)
  • Fully managed experience (vs BigQuery)

Consequences

影响结果

Positive

积极影响

  • Development can start immediately (no learning curve)
  • Lower operational costs
  • Can reuse existing PostgreSQL expertise
  • Easy integration with current stack
  • Development can start immediately (no learning curve)
  • Lower operational costs
  • Can reuse existing PostgreSQL expertise
  • Easy integration with current stack

Negative

负面影响

  • Will need to manually optimize queries
  • May need to revisit if we scale 10x
  • Requires more operational work than BigQuery
  • Will need to manually optimize queries
  • May need to revisit if we scale 10x
  • Requires more operational work than BigQuery

Risks

风险

  • Performance may degrade at 100M+ events/day
  • Mitigation: Monitor query performance, plan migration at 50M events/day
  • Performance may degrade at 100M+ events/day
  • Mitigation: Monitor query performance, plan migration at 50M events/day

Implementation Notes

实施说明

  • Use TimescaleDB hypertables for event storage
  • Implement continuous aggregates for common queries
  • Set up read replicas for dashboard queries
  • Document scaling runbook at 50M events/day
  • Use TimescaleDB hypertables for event storage
  • Implement continuous aggregates for common queries
  • Set up read replicas for dashboard queries
  • Document scaling runbook at 50M events/day

Follow-up Actions

后续行动

  • Provision PostgreSQL + TimescaleDB cluster (Alice, by 2024-01-20)
  • Create migration script from MySQL (Bob, by 2024-01-22)
  • Set up monitoring dashboards (Alice, by 2024-01-25)
  • Document scaling thresholds (Alice, by 2024-01-30)
  • Provision PostgreSQL + TimescaleDB cluster (Alice, by 2024-01-20)
  • Create migration script from MySQL (Bob, by 2024-01-22)
  • Set up monitoring dashboards (Alice, by 2024-01-25)
  • Document scaling thresholds (Alice, by 2024-01-30)

References

参考资料

Revision History

修订历史

  • 2024-01-15: Initial draft (Alice)
  • 2024-01-16: Added cost analysis (Bob)
  • 2024-01-17: Accepted by architecture review board
undefined
  • 2024-01-15: Initial draft (Alice)
  • 2024-01-16: Added cost analysis (Bob)
  • 2024-01-17: Accepted by architecture review board
undefined

ADR Numbering

ADR编号规则

ADR-001: Initial System Architecture
ADR-002: Database Selection for Analytics
ADR-003: Authentication Strategy
...
ADR-001: 初始系统架构
ADR-002: 分析服务数据库选型
ADR-003: 认证策略
...

Status Workflow

状态工作流

Proposed → Accepted → Implemented
    ↓
Rejected

Accepted → Deprecated → Superseded by ADR-XXX
提议中 → 已通过 → 已实施
    ↓
已拒绝

已通过 → 已弃用 → 被ADR-XXX取代

Common Decision Types

常见决策类型

Technology Selection:
  • Database choice
  • Framework selection
  • Cloud provider
  • Programming language
Architecture Patterns:
  • Microservices vs Monolith
  • Event-driven vs Request-response
  • Sync vs Async communication
Infrastructure:
  • Deployment strategy
  • Monitoring approach
  • Scaling strategy
Security:
  • Authentication method
  • Data encryption approach
  • Access control model
技术选型:
  • 数据库选择
  • 框架选型
  • 云服务商选择
  • 编程语言选择
架构模式:
  • 微服务 vs 单体应用
  • 事件驱动 vs 请求响应
  • 同步 vs 异步通信
基础设施:
  • 部署策略
  • 监控方案
  • 扩容策略
安全:
  • 认证方式
  • 数据加密方案
  • 访问控制模型

Quick Start Guide

快速开始指南

bash
undefined
bash
undefined

1. Create new ADR

1. 创建新的ADR文档

cp templates/adr-template.md docs/adr/ADR-042-title.md
cp templates/adr-template.md docs/adr/ADR-042-title.md

2. Fill in sections

2. 填写各章节内容

- Context: Why are we making this decision?

- 背景：我们为什么要做这个决策？

- Decision: What did we decide?

- 决策：我们的最终选择是什么？

- Alternatives: What else did we consider?

- 备选方案：我们还考虑了哪些选项？

- Consequences: What are the impacts?

- 影响结果：这个决策会带来什么影响？

3. Review with team

3. 团队评审

- Share in architecture channel

- 在架构沟通渠道分享

- Get feedback from stakeholders

- 收集相关人员的反馈

- Iterate on alternatives

- 完善备选方案内容

4. Update status to "Accepted"

4. 将状态更新为「已通过」

5. Link from main architecture docs

5. 在主架构文档中添加链接

undefined
undefined

Best Practices

最佳实践

  1. Write ADRs for significant decisions: Not every choice needs an ADR
  2. Document alternatives: Show you considered options
  3. Be honest about tradeoffs: Every decision has downsides
  4. Keep it concise: 1-2 pages maximum
  5. Update status: Mark deprecated/superseded ADRs
  6. Link related ADRs: Create decision trails
  7. Include follow-ups: Action items with owners
  1. 只为重大决策编写ADR: 并非每个技术选择都需要ADR
  2. 记录备选方案: 证明你考虑了多种选项
  3. 坦诚记录权衡因素: 每个决策都有其不足之处
  4. 保持简洁: 最多1-2页内容
  5. 更新状态: 标记已弃用/被取代的ADR
  6. 关联相关ADR: 形成决策追踪链路
  7. 包含后续行动: 明确负责人的行动项

Anti-Patterns

反模式

❌ Too detailed: 10-page ADRs nobody reads ❌ No alternatives: Looks like decision was predetermined ❌ Missing consequences: Ignoring downsides ❌ No owner: Nobody accountable ❌ Outdated status: Old ADRs marked "Proposed"
❌ 过于详细: 没人会读10页长的ADR ❌ 无备选方案: 看起来像是预先确定的决策 ❌ 缺失影响结果: 忽略决策的负面影响 ❌ 无负责人: 没人对决策负责 ❌ 状态过时: 旧ADR仍标记为「提议中」

Review Checklist

评审检查清单

  • Clear problem statement in Context
  • Decision is stated explicitly
  • 2+ alternatives considered
  • Tradeoffs honestly assessed
  • Consequences (positive and negative) documented
  • Risks identified with mitigations
  • Decision owner assigned
  • Follow-up actions with deadlines
  • Status is current
  • 背景部分有清晰的问题陈述
  • 决策内容明确表述
  • 考虑了2个及以上备选方案
  • 坦诚评估了权衡因素
  • 记录了影响结果（积极和消极）
  • 识别了风险及缓解措施
  • 指定了决策负责人
  • 包含带截止日期的后续行动
  • 状态为最新

Output Checklist

输出检查清单

  • ADR document created
  • Context explains the problem
  • Decision clearly stated
  • 2-3 alternatives documented
  • Tradeoffs section filled
  • Consequences listed (positive & negative)
  • Risks identified with mitigations
  • Decision date and owners
  • Follow-up actions assigned
  • Status is set
  • 创建了ADR文档
  • 背景部分解释了问题
  • 决策内容清晰明确
  • 记录了2-3个备选方案
  • 填写了权衡因素部分
  • 列出了影响结果（积极&消极）
  • 识别了风险及缓解措施
  • 包含决策日期和负责人
  • 分配了后续行动项
  • 设置了文档状态