ADR ライター
アーキテクチャ上の決定を、明確なコンテキスト、代替案、結果とともに文書化します。英語で記述してください。
ADR テンプレート
# ADR-[番号]: [短い決定タイトル]
**ステータス:** [提案済み | 承認済み | 非推奨 | ADR-XXX に置き換え]
**日付:** [YYYY-MM-DD]
**作成者:** [名前/ハンドル]
## 1. コンテキスト
どのような問題を解決しているのか？どのような要因（ビジネス目標、技術的負債、予算）が影響しているか？
**制約:**
- [制約 1]
- [制約 2]
## 2. 決定
決定内容を簡潔に述べます。主要な論点。
## 3. 技術的な詳細とメカニズム
_自由形式のセクション。実装の詳細、データ構造、プロトコルの詳細、主要なフレームワークの機能を記述します。_
- [リスト、API の説明、データスキーマ]
- [複雑なインタラクションには Mermaid の可視化を推奨]
## 4. 検討した代替案
### 4.1. [オプション 1]
- **長所:** ...
- **短所:** ...
- **決定:** [却下/検討済み]（簡単な理由）
## 5. 結果とリスク
### 良い点（長所）
- これによりシステム/チームにどのようなメリットがあるか？
### 悪い点 / リスク（短所/リスク）
- どのような欠点を受け入れるのか？脅威は何か？
- **軽減策:** リスクにどのように対処するか？
## 6. 改訂履歴
- **[日付]**: [変更内容の説明]（[作成者]）
- **[日付]**: [例：ステータスを「承認済み」に変更]（[作成者]）
ADR の採番
ADR-001: 初期システムアーキテクチャ
ADR-002: 分析用データベースの選定
ADR-003: 認証戦略
...
ステータスワークフロー
提案済み → 承認済み → 実装済み
↓
却下
承認済み → 非推奨 → 置き換え (ADR-XXX)
ベストプラクティス
- 重要な決定に ADR を作成する: すべての選択に ADR が必要なわけではない
- 代替案を文書化する: 選択肢を検討したことを示す
- トレードオフについて正直になる: すべての決定には欠点がある
- 簡潔に保つ: 最大 1〜2 ページ
- ステータスを更新する: 非推奨/置き換えられた ADR にマークする
- 関連する ADR をリンクする: 決定の連鎖を作成する
- フォローアップを含める: 責任者と期限のあるアクションアイテム
- 可視化する: Mermaid 図を使用してアーキテクチャとフローを示す
- 将来の読者のために書く: 現在のコンテキストを欠いている読者向けに
- トレードオフについて正直になる: すべての選択には欠点がある
一般的なパターン
技術選定の場合:
- 要件に対する技術的能力に焦点を当てる
- 利用可能であればパフォーマンスベンチマークを含める
- チームの専門知識レベルを文書化する
- 運用の複雑さを考慮する
アーキテクチャ変更の場合:
- 結果に移行戦略を含める
- 後方互換性への影響を文書化する
- 移行期間中のチームのベロシティへの影響を考慮する
- 監視とロールバック計画に言及する
標準と規約の場合:
- 実際の標準の例を含める
- 例外や逃げ道を文書化する
- 強制メカニズムを考慮する
- 教育/オンボーディングへの影響に言及する
非推奨の場合:
- ステータスを「非推奨」または「置き換え」に設定する
- 置き換える ADR へのリンクを含める
- 廃止のタイムラインを文書化する
- 移行ガイドを含める
アンチパターン
❌ 詳細すぎる: 誰も読まない 10 ページの ADR ❌ 代替案がない: 決定が事前に決められていたように見える ❌ 結果の欠落: 欠点を無視している ❌ 責任者なし: 誰も責任を負わない ❌ 古いステータス: 古い ADR が「提案済み」のまま
レビューチェックリスト
- コンテキストに明確な問題の記述がある
- 決定が明示的に述べられている
- 2 つ以上の代替案が検討されている
- トレードオフが正直に評価されている
- 結果（良い点と悪い点）が文書化されている
- リスクが特定され、軽減策が示されている
- 決定責任者が割り当てられている
- 期限のあるフォローアップアクションがある
- ステータスが最新である
出力チェックリスト
- ADR 文書が作成された
- コンテキストが問題を説明している
- 決定が明確に述べられている
- 2〜3 の代替案が文書化されている
- トレードオフセクションが記入されている
- 結果（良い点と悪い点）がリストされている
- リスクが特定され、軽減策が示されている
- 決定日と責任者が記録されている
- フォローアップアクションが割り当てられている
- ステータスが設定されている