architecture-decision-records

# アーキテクチャ決定記録 コーディングセッション中にアーキテクチャ決定を構造化ドキュメントとして記録します。決定がSlackスレッド、PRコメント、または誰かの記憶にのみ存在する代わりに、このスキルはコードと並行して存在する構造化ADRドキュメントを生成します。 ## アクティベーション時期 - ユーザーが明示的に「この決定を記録しよう」または「このADRを作成しよう」と言う - 重要な代替案の選択（フレームワーク、ライブラリ、パターン、データベース、API設計） - ユーザーが「私たちは...を選択した」または「YではなくXをしている理由は...です」と言う - ユーザーが「なぜXを選んだのか」と尋ねる（既存のADRを読む） - アーキテクチャ上のトレードオフが検討される計画段階 ## ADR形式 Michael Nygardによって提案されたADR形式を、AI支援開発向けに調整したものを使用します： ```markdown # ADR-NNNN: [決定タイトル] **Date**: YYYY-MM-DD **Status**: proposed | accepted | deprecated | superseded by ADR-NNNN **Deciders**: [関係者] ## Context この決定または変更を促すどのような問題や状況が見られるのか？ [2～5文で状況、制約条件、作用する力について説明] ## Decision 提案または実施する変更は何か？ [決定を明確に述べる1～3文] ## Alternatives Considered（検討された代替案） ### Alternative 1: [名前] - **Pros**: [利点] - **Cons**: [欠点] - **Why not**: [この選択肢が拒否された特定の理由] ### Alternative 2: [名前] - **Pros**: [利点] - **Cons**: [欠点] - **Why not**: [この選択肢が拒否された特定の理由] ## Consequences（結果） この変更により、何がより簡単になり、何がより難しくなるか？ ### Positive - [利点1] - [利点2] ### Negative - [トレードオフ1] - [トレードオフ2] ### Risks - [リスクと軽減策] ``` ## ワークフロー ### 新しいADRをキャプチャする 決定の瞬間が検出されたとき： 1. **初期化（初回のみ）** — `docs/adr/`が存在しない場合、ユーザーの確認を得た上でディレクトリ、インデックステーブルヘッダーでシードされた`README.md`（下記のADRインデックス形式を参照）、手動使用用の空白の`template.md`を作成します。明示的な同意なしにファイルを作成しないでください。 2. **決定を特定する** — 行われている中核的なアーキテクチャの選択を抽出する 3. **コンテキストを収集する** — この問題を起こした背景は？存在する制約条件は？ 4. **代替案をドキュメント化する** — どの他のオプションが検討されたか？ なぜ拒否されたか？ 5. **結果を述べる** — トレードオフは何か？何がより簡単/難しくなるか？ 6. **番号を割り当てる** — `docs/adr/`内の既存のADRをスキャンして増分する 7. **確認して書き込む** — レビュー用のドラフトADRをユーザーに提示します。明示的な承認後にのみ`docs/adr/NNNN-decision-title.md`に書き込みます。ユーザーが辞退した場合、ファイルを書き込まずにドラフトを破棄します。 8. **インデックスを更新する** — `docs/adr/README.md`に追記する ### 既存のADRを読む ユーザーが「なぜXを選んだのか」と尋ねたとき： 1. `docs/adr/`が存在するかチェック — 存在しない場合、「このプロジェクトでADRが見つかりません。アーキテクチャ決定の記録を始めたいですか？」と応答 2. 存在する場合、関連エントリの`docs/adr/README.md`インデックスをスキャン 3. 一致するADRファイルを読み、ContextとDecisionセクションを表示 4. 一致が見つからない場合、「その決定についてのADRが見つかりません。今すぐ記録しますか？」と応答 ### ADRディレクトリ構造 ``` docs/ └── adr/ ├── README.md ← すべてのADRのインデックス ├── 0001-use-nextjs.md ├── 0002-postgres-over-mongo.md ├── 0003-rest-over-graphql.md └── template.md ← 手動使用用の空白テンプレート ``` ### ADRインデックス形式 ```markdown # Architecture Decision Records | ADR | Title | Status | Date | |-----|-------|--------|------| | [0001](0001-use-nextjs.md) | Use Next.js as frontend framework | accepted | 2026-01-15 | | [0002](0002-postgres-over-mongo.md) | PostgreSQL over MongoDB for primary datastore | accepted | 2026-01-20 | | [0003](0003-rest-over-graphql.md) | REST API over GraphQL | accepted | 2026-02-01 | ``` ## 決定検出シグナル 会話の中でアーキテクチャ決定を示すこれらのパターンに注意： **明示的なシグナル** - 「Xにしよう」 - 「YではなくXを使うべき」 - 「トレードオフは...だから価値がある」 - 「このをADRとして記録して」 **暗黙的なシグナル**（ADRの記録を提案する — ユーザーの確認なしに自動作成しない） - 2つのフレームワークまたはライブラリを比較して結論に達する - 述べられた根拠を持つデータベーススキーマ設計の選択をする - アーキテクチャパターン（モノリス対マイクロサービス、REST対GraphQL）の間で選択する - 認証/認可戦略を決定する - 代替案を評価した後、デプロイインフラストラクチャを選択する ## 良いADRとは ### すること - **具体的に** — 「ORMを使う」ではなく「Prisma ORMを使う」 - **根拠を記録する** — 根拠は何よりも重要です - **拒否された代替案を含める** — 将来の開発者は何が検討されたかを知る必要があります - **結果を正直に述べる** — すべての決定にはトレードオフがあります - **短く保つ** — ADRは2分で読めるべき - **現在時制を使う** — 「Xを使う」ではなく「私たちはXを使う」 ### しないこと - 些細な決定を記録する — 変数名またはフォーマット選択はADRを必要としません - エッセイを書く — contextセクションが10行を超える場合は長すぎます - 代替案を省略する — 「単に選んだ」は有効な根拠ではありません - マーキングなしでバックフィルする — 過去の決定を記録する場合は元の日付を注記 - ADRを古い状態にする — 置き換えられた決定は置き換えを参照する必要があります ## ADRライフサイクル ``` proposed → accepted → [deprecated | superseded by ADR-NNNN] ``` - **proposed**: 決定が検討中であり、まだコミットされていない - **accepted**: 決定が有効であり、フォローされている - **deprecated**: 決定は関連性がなくなった（例：機能が削除された） - **superseded**: 新しいADRがこれを置き換える（常に置き換えをリンク） ## 記録する価値のある決定カテゴリ | Category | Examples | |----------|---------| | **Technology choices** | フレームワーク、言語、データベース、クラウドプロバイダ | | **Architecture patterns** | モノリス対マイクロサービス、イベント駆動、CQRS | | **API design** | REST対GraphQL、バージョニング戦略、auth機構 | | **Data modeling** | スキーマ設計、正規化決定、キャッシング戦略 | | **Infrastructure** | デプロイメントモデル、CI/CDパイプライン、監視スタック | | **Security** | Auth戦略、暗号化アプローチ、シークレット管理 | | **Testing** | テストフレームワーク、カバレッジ対象、E2E対統合のバランス | | **Process** | ブランチング戦略、レビュープロセス、リリースケーデンス | ## 他のスキルとの統合 - **Planner エージェント**: プランナーがアーキテクチャ変更を提案するとき、ADRの作成を提案 - **Code reviewer エージェント**: 対応するADRなしでアーキテクチャ変更を導入するPRにフラグを立てる