adr-architecture

アーキテクチャ決定記録（ADR）

目次

• ワークフロー
  • 1. 決定内容を把握する
  • 2. ADR テンプレートを選ぶ
  • 3. 決定を記録する
  • 4. 品質を検証する
  • 5. 提出して保管する
• よくあるパターン
• ガードレール
• クイックリファレンス

各 ADR には、コンテキスト（この決定が必要となる状況）、決定（選択する内容）、代替案（検討した他の選択肢）、結果（トレードオフと影響）、ステータス（提案、承認、非推奨、置き換え済み）が記録されます。

簡単な例：

# ADR-042: Use PostgreSQL for Primary Database

**Status:** Accepted
**Date:** 2024-01-15
**Deciders:** Backend team, CTO

## Context
Need to select primary database for new microservices platform.
Requirements: ACID transactions, complex queries, 10k+ QPS at launch.

## Decision
Use PostgreSQL 15+ as primary relational database.

## Alternatives Considered
- MySQL: Weaker JSON support, less robust constraint handling
- MongoDB: No ACID across documents, eventual consistency issues
- CockroachDB: Excellent but adds operational complexity we can't support yet

## Consequences
✓ Strong consistency and data integrity
✓ Excellent JSON support for semi-structured data
✓ Team has deep PostgreSQL experience
✗ Vertical scaling limits (will need read replicas at 50k+ QPS)
✗ More complex to shard than DynamoDB if we need it

ワークフロー

このチェックリストをコピーして、進捗を記録してください。

ADR Progress:
- [ ] Step 1: Understand the decision
- [ ] Step 2: Choose ADR template
- [ ] Step 3: Document the decision
- [ ] Step 4: Validate quality
- [ ] Step 5: Deliver and file

ステップ 1：決定内容を把握する

決定に関するコンテキストを集めます。どのような決定が必要か、なぜ今なのか、誰が決定するのか、制約（予算、スケジュール、スキル、コンプライアンス）、要件（機能、非機能、ビジネス）、対象範囲（単一のサービスか、組織全体か）を確認します。これにより、ADR が適切な問題を扱うようになります。

ステップ 2：ADR テンプレートを選ぶ

テクノロジーの選定（フレームワーク、ライブラリ、データベース）には、resources/template.md を使用します。相互に依存する複数の選択肢を含む複雑なアーキテクチャ上の決定については、resources/methodology.md を確認します。例を見るには、resources/examples/（database-selection.md、microservices-migration.md、api-versioning.md）を参照します。

ステップ 3：決定を記録する

adr-{number}-{short-title}.md を作成し、明確なタイトル、メタデータ（ステータス、日付、決定者）、コンテキスト（状況と要件）、決定（具体的で実行可能な内容）、検討した代替案（長所と短所を含む）、結果（トレードオフ、リスク、メリット）、該当する場合は実装上の注意事項、関連する ADR へのリンクを記載します。決定の種類に応じたガイダンスについては、よくあるパターンを参照してください。

ステップ 4：品質を検証する

resources/evaluators/rubric_adr_architecture.json を使用して自己チェックします。コンテキストで理由が説明されていること、決定が具体的かつ実行可能であること、トレードオフを含む代替案が 2～3 件以上記載されていること、結果にメリットとデメリットの両方が含まれていること、技術的な詳細が正確であること、初めて読む人にも理解できること、欠点について正直に記載されていることを確認します。最低基準：スコア ≥ 3.5（議論の多い決定や影響の大きい決定では、4.5 以上を目指します）。

ステップ 5：提出して保管する

完成した ADR ファイルを提示し、特定した主要なトレードオフを強調します。番号が指定されていない場合は ADR の番号付けを提案し、重要な決定ではレビュー手順を推奨し、必要なフォローアップの決定があれば記載します。保管規則：ADR は docs/adr/ または architecture/decisions/ ディレクトリに連番で保存します。

よくあるパターン

テクノロジーの選定の場合：

• 技術的な能力と要件の比較に重点を置きます
• 入手できる場合は、パフォーマンスのベンチマークを含めます
• チームの専門知識のレベルを記録します
• 運用の複雑さを考慮します

アーキテクチャの変更の場合：

• 結果に移行戦略を含めます
• 後方互換性への影響を記録します
• 移行期間中のチームの開発速度への影響を考慮します
• 監視とロールバックの計画を記載します

標準や規約の場合：

• 標準を実際に適用した例を含めます
• 例外や適用を回避する方法を記録します
• 適用を徹底する仕組みを考慮します
• 教育やオンボーディングへの影響を記載します

非推奨化の場合：

• ステータスを「Deprecated」または「Superseded」に設定します
• 後継となる ADR へのリンクを記載します
• 廃止までのスケジュールを記録します
• 移行ガイドを含めます

ガードレール

推奨事項：

• トレードオフについて正直に記述します（どの選択にも欠点があります）
• 現在の背景情報を持たない将来の読者に向けて記述します
• 具体的な技術情報（バージョン、設定）を含めます
• 不確実性とリスクを明示します
• ADRは不変に保ちます（ステータスは変更できますが、内容は変更しません）
• 1つの決定につき1つのADRを作成します（対象範囲を絞ります）

禁止事項：

• 決定を実際以上に良く見せること
• 真剣に検討した代替案を省くこと
• 説明なしに専門用語を使うこと
• 曖昧な結果を記述すること（「パフォーマンスが向上する可能性があります」など）
• 古いADRを再検討・編集すること（代わりに、それに取って代わる新しいADRを作成します）
• 独立した複数の決定を1つのADRにまとめること

クイックリファレンス

• 標準テンプレート：resources/template.md
• 複雑な決定：resources/methodology.md
• 例：resources/examples/database-selection.md、resources/examples/microservices-migration.md、resources/examples/api-versioning.md
• 品質評価基準：resources/evaluators/rubric_adr_architecture.json

ADRの命名規則：adr-{number}-{short-kebab-case-title}.md

• 例：adr-042-use-postgresql-for-primary-database.md