architecture-decision-record

アーキテクチャ決定記録

technical-requirements.yaml から重要なアーキテクチャ上の決定を抽出し、それぞれを独立した ADR ファイルとして正式に記録します。ADR は、システムが単に 何 を選んだかだけではなく、なぜ そのように構築されているのかを記録するものであり、オンボーディング、監査、トレードオフの再検討に不可欠です。

前提条件

• {base_directory}/requirements/technical-requirements.yaml（/technical-requirements-interview の出力）

使用方法

/architecture-decision-record [base-directory]

ディレクトリが指定されていない場合は、現在のディレクトリ内に requirements/technical-requirements.yaml があるかを調べて自動検出します。

見つからない場合は、ユーザーに「要件ドキュメントはどこにありますか？」と尋ねます。

先に進む前に、ユーザーがパスを指定するまで待ちます。指定されたパスを base_directory として保存します。

プロセス

ステップ 1：ベースディレクトリを決定し、技術要件を読み込む

ディレクトリパラメーターが指定されていない場合は、現在のディレクトリに requirements/technical-requirements.yaml があるかを確認します。

• 見つかった場合は、現在のディレクトリを base_directory として使用します
• 見つからない場合は、「要件ドキュメントはどこにありますか？」と尋ね、ユーザーの回答を待ちます

base_directory が決まったら、{base_directory}/requirements/technical-requirements.yaml を読み込み、すべての決定事項を特定します。以下のセクションを確認します。

• architecture — パターン、フレームワーク、構造上の選択
• technology_stack — 言語、ランタイム、主要なライブラリ、データベース
• data_model — ストレージエンジンの選択、スキーマ設計上の決定
• api_design — REST、GraphQL、RPC の選択、バージョニング戦略
• security — 認証メカニズム、トークン戦略、暗号化方式
• testing — テスト戦略、カバレッジ目標、ツール
• deployment — ホスティング、CI/CD パイプライン、コンテナ化
• trade_offs と open_questions — 明示的に挙げられた決定事項

各決定を ADR 候補として収集します。次のいずれかに該当する場合、その決定は ADR の対象となります。

• 選択肢の中から意味のある選択を行っている、または
• システムの将来的な柔軟性に顕著な影響を与える、または
• トレードオフまたは未解決の質問として明示的に挙げられている

ステップ 2：代替案を特定する

ADR 候補ごとに、現実的な代替案を検討します。以下の情報をもとに導き出します。

• 技術要件の trade_offs セクション（存在する場合）
• 選択された技術やパターンに対する一般的な代替案
• 要件内の「検討した選択肢」に関する記述

代替案を推測できない場合は、でっち上げずに「代替案は記録されていません」と記載します。

ステップ 3：ADR ID とタイトルを割り当てる

ADR の番号は ADR-001 から順に割り当てます。タイトルは簡潔で断定的なものにします。

• 良い例：プライマリーデータストアとして PostgreSQL を使用する
• 悪い例：データベースの決定

関連する決定は論理的にまとめます（例：すべての認証に関する決定を、すべてのデプロイに関する決定より前にまとめる）。

ステップ 4：ADR ファイルを作成する

次のディレクトリ構成を作成します。

mkdir -p {base_directory}/architecture/adrs

ADR ごとに 1 つのファイルを作成します：{base_directory}/architecture/adrs/ADR-NNN-kebab-case-title.md

各ファイルは次の形式に従います。

ADR ドキュメントには、ヘッダー（ADR-NNN: Title、Status、Date、Source）と、必須の 4 つのセクション（Context（問題の説明）、Decision（決定した選択肢）、Alternatives Considered（却下した選択肢の表）、Consequences（利点、欠点／トレードオフ、リスク））を含めます。

完全な ADR ドキュメント仕様とすべてのセクションおよび書式ルールについては、references/adr-document-spec.md を参照してください。

全体の例については、references/example-ADR-001.md および references/example-ADR-003.md を参照してください。

ステップ 5：INDEX.md を作成する

要約表として {base_directory}/architecture/adrs/INDEX.md を作成します。

インデックスには、ID（リンク）、タイトル、ステータス、日付の列を含む表を 1 つだけ記載します。

完全な INDEX 仕様については、references/adr-index-spec.md を参照してください。

全体の例については、references/example-INDEX.md を参照してください。

ステップ 6：ギャップ分析

すべてのファイルを生成した後、インラインで報告します。

## ADR Gap Analysis

**Project:** [name]
**ADRs Generated:** [n]

**Decision Areas Covered:**
[✓ / ✗] Architecture / structural patterns
[✓ / ✗] Technology stack
[✓ / ✗] Data storage
[✓ / ✗] API design
[✓ / ✗] Security / authentication
[✓ / ✗] Testing strategy
[✓ / ✗] Deployment / infrastructure

**Open Questions carried forward:** [n]
[List any open_questions from technical-requirements.yaml that could not yet be
formalized as Accepted ADRs — these are candidates for future ADRs.]

**Recommendations:** [none / list]

出力形式

{base_directory}/architecture/adrs/
  INDEX.md
  ADR-001-[title].md
  ADR-002-[title].md
  ...

出力例

サンプルの ADR ファイル（ADR-001、ADR-003）と INDEX.md については、references/ を参照してください。