architecture-decision-records

アーキテクチャ決定記録

重要な技術的決定の背景と根拠を記録する、アーキテクチャ決定記録（ADR）の作成、維持、管理に関する包括的なパターンです。

このスキルを使用する場面

• 重要なアーキテクチャ上の決定を行うとき
• 技術選定を記録するとき
• 設計上のトレードオフを記録するとき
• 新しいチームメンバーを受け入れるとき
• 過去の決定を確認するとき
• 意思決定プロセスを確立するとき

コアコンセプト

1. ADRとは？

アーキテクチャ決定記録には、次の内容を記載します。

• 背景：なぜ決定が必要だったのか
• 決定：何を決定したのか
• 結果：その決定によって何が起こるのか

2. ADRを作成するタイミング

ADRを作成する	ADRを省略する
新しいフレームワークの採用	マイナーバージョンのアップグレード
データベース技術の選定	バグ修正
API設計パターン	実装の詳細
セキュリティアーキテクチャ	定常的なメンテナンス
統合パターン	設定の変更

3. ADRのライフサイクル

Proposed → Accepted → Deprecated → Superseded
              ↓
           Rejected

標準、軽量、またはYステートメント形式のADRを作成する前に、決定テンプレートをお読みください。

非推奨化のADRまたはRFCを作成する前に、非推奨化とRFCのテンプレートをお読みください。

ADRの管理

ディレクトリ構成

docs/
├── adr/
│   ├── README.md           # Index and guidelines
│   ├── template.md         # Team's ADR template
│   ├── 0001-use-postgresql.md
│   ├── 0002-caching-strategy.md
│   ├── 0003-mongodb-user-profiles.md  # [DEPRECATED]
│   └── 0020-deprecate-mongodb.md      # Supersedes 0003

ADRインデックス（README.md）

# Architecture Decision Records

This directory contains Architecture Decision Records (ADRs) for [Project Name].

## Index

| ADR                                   | Title                              | Status     | Date       |
| ------------------------------------- | ---------------------------------- | ---------- | ---------- |
| [0001](0001-use-postgresql.md)        | Use PostgreSQL as Primary Database | Accepted   | 2024-01-10 |
| [0002](0002-caching-strategy.md)      | Caching Strategy with Redis        | Accepted   | 2024-01-12 |
| [0003](0003-mongodb-user-profiles.md) | MongoDB for User Profiles          | Deprecated | 2023-06-15 |
| [0020](0020-deprecate-mongodb.md)     | Deprecate MongoDB                  | Accepted   | 2024-01-15 |

## Creating a New ADR

1. Copy `template.md` to `NNNN-title-with-dashes.md`
2. Fill in the template
3. Submit PR for review
4. Update this index after approval

## ADR Status

- **Proposed**: Under discussion
- **Accepted**: Decision made, implementing
- **Deprecated**: No longer relevant
- **Superseded**: Replaced by another ADR
- **Rejected**: Considered but not adopted

自動化（adr-tools）

# Install adr-tools
brew install adr-tools

# Initialize ADR directory
adr init docs/adr

# Create new ADR
adr new "Use PostgreSQL as Primary Database"

# Supersede an ADR
adr new -s 3 "Deprecate MongoDB in Favor of PostgreSQL"

# Generate table of contents (to a separate file, so the hand-written
# index and guidelines in README.md are not overwritten)
adr generate toc > docs/adr/toc.md

# Link related ADRs
adr link 2 "Complements" 1 "Is complemented by"

レビュープロセス

## ADR Review Checklist

### Before Submission

- [ ] Context clearly explains the problem
- [ ] All viable options considered
- [ ] Pros/cons balanced and honest
- [ ] Consequences (positive and negative) documented
- [ ] Related ADRs linked

### During Review

- [ ] At least 2 senior engineers reviewed
- [ ] Affected teams consulted
- [ ] Security implications considered
- [ ] Cost implications documented
- [ ] Reversibility assessed

### After Acceptance

- [ ] ADR index updated
- [ ] Team notified
- [ ] Implementation tickets created
- [ ] Related documentation updated

ベストプラクティス

推奨事項

• ADRは早めに作成します - 実装を始める前に作成します
• 簡潔にまとめます - 最大1～2ページにします
• トレードオフを正直に記載します - 実際のデメリットを含めます
• 関連する決定をリンクします - 決定のグラフを構築します
• ステータスを更新します - 後続の決定に置き換えられたら非推奨にします

避けるべきこと

• 承認済みのADRを変更しないでください - 置き換える場合は新しいADRを作成します
• 背景を省略しないでください - 将来の読者には背景情報が必要です
• 失敗を隠さないでください - 却下された決定にも価値があります
• 曖昧な表現を避けてください - 決定と結果を具体的に記載します
• 実装を忘れないでください - 実行されないADRは無駄になります