adr-writer

ADR 编写器

通过清晰的背景、备选方案和后果来记录架构决策。

ADR 模板

# ADR-001: [Title of Decision]

**Status:** Proposed | Accepted | Deprecated | Superseded by ADR-XXX
**Date:** 2024-01-15
**Deciders:** Alice (Tech Lead), Bob (Principal Engineer)
**Owner:** 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

## Decision

We will use PostgreSQL with TimescaleDB extension.

## Alternatives Considered

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

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

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

## 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)

## Consequences

### Positive

- 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

### Risks

- 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

## 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)

## References

- [TimescaleDB Benchmarks](https://example.com)
- [Cost Analysis Spreadsheet](https://docs.google.com/...)
- [Team Survey Results](https://example.com)

## Revision History

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

ADR 编号

ADR-001: Initial System Architecture
ADR-002: Database Selection for Analytics
ADR-003: Authentication Strategy
...

状态工作流

Proposed → Accepted → Implemented
    ↓
Rejected

Accepted → Deprecated → Superseded by ADR-XXX

常见决策类型

技术选型：

• 数据库选择
• 框架选择
• 云服务提供商
• 编程语言

架构模式：

• 微服务与单体架构
• 事件驱动与请求-响应
• 同步与异步通信

基础设施：

• 部署策略
• 监控方案
• 扩展策略

安全：

• 身份验证方式
• 数据加密方案
• 访问控制模型

快速入门指南

# 1. Create new ADR
cp templates/adr-template.md docs/adr/ADR-042-title.md

# 2. Fill in sections
# - 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
# - Share in architecture channel
# - Get feedback from stakeholders
# - Iterate on alternatives

# 4. Update status to "Accepted"
# 5. Link from main architecture docs

最佳实践

1. 为重要决策编写 ADR：并非每个选择都需要 ADR
2. 记录备选方案：展示你考虑过哪些选项
3. 如实说明权衡：每项决策都有缺点
4. 保持简洁：最多 1-2 页
5. 更新状态：将已弃用或被取代的 ADR 标记出来
6. 关联相关 ADR：建立决策脉络
7. 包含后续事项：列出带负责人的行动项

反模式

❌ 过于详尽：长达 10 页、无人阅读的 ADR ❌ 没有备选方案：看起来决策早已预先确定 ❌ 缺少后果：忽略缺点 ❌ 没有负责人：无人负责 ❌ 状态过时：旧 ADR 仍标记为“提议中”

审核清单

• 背景部分清楚说明问题
• 明确陈述决策
• 考虑了 2 个以上的备选方案
• 如实评估权衡
• 记录后果（正面和负面）
• 识别风险并制定缓解措施
• 指定决策负责人
• 后续行动列明截止日期
• 状态为最新

输出清单

• 已创建 ADR 文档
• 背景部分说明问题
• 清楚陈述决策
• 记录了 2-3 个备选方案
• 已填写权衡部分
• 列出后果（正面和负面）
• 识别风险并制定缓解措施
• 记录决策日期和负责人
• 已分配后续行动
• 已设置状态