doc-adr

doc-adr

目的

Architecture Decision Record（ADR）を作成します。これはSDDフローのレイヤー5です。 ADRでは、Context-Decision-Consequencesパターンを使用して1つのアーキテクチャ上の決定を記録します。決定が必要な理由、選択した内容、検討した代替案、受け入れる結果を記載します。

レイヤー：5 — Container（PRD）とComponent（SPEC）の間にある意思決定の橋渡しです。ADR自体はC4のレベルではありません。 上流：EARS、BDD（必要な上流成果物に関する契約に基づきます。PRD／BRDの上流の系譜は@タグの連鎖を通じて推移的にたどれます）。 下流：SPEC → TDD → IPLAN → Code。

各ADRで扱う決定は必ず1つだけです。新しいアーキテクチャ上の選択には、既存のADRを拡張するのではなく、新しいADR（ADR-02、ADR-03など）を作成し、@depends: ADR-NNで相互に関連付けます。

使用する場面

次のような場合にdoc-adrを使用します。

• BRD §8／PRD §14にあるアーキテクチャ上のトピックについて、記録された決定が必要な場合。
• 代替案を検討したうえで、テクノロジー、パターン、統合アプローチを選択する場合。
• 長期間にわたって維持するアーキテクチャ上の選択について、その根拠と結果を記録する場合。

上流成果物またはプロンプトからエンドツーエンドで生成するには、../doc-adr-autopilot/SKILL.mdを使用してください。プロジェクトに必要なADRの一式を計画するには、../adr-roadmap/SKILL.mdを参照してください。

前提条件

ADRはレイヤー5です。作成前に、必要な上流成果物（EARS＋BDD）が存在することを確認し、仕様を読んでください。

1. テンプレート（信頼できる唯一の情報源）： ${CLAUDE_PLUGIN_ROOT}/framework/layers/05_ADR/ADR-TEMPLATE.yaml
2. レイヤーのREADME： ${CLAUDE_PLUGIN_ROOT}/framework/layers/05_ADR/README.md
3. IDとタグの標準： ${CLAUDE_PLUGIN_ROOT}/framework/governance/ID_NAMING_STANDARDS.md
4. 作成スタイル： ${CLAUDE_PLUGIN_ROOT}/framework/governance/AUTHORING_STYLE.md

必要な上流成果物を確認します：ls docs/0{3,4}_*/ 2>/dev/null（EARSとBDD）。すでに存在するドキュメントのみを参照してください。ADR-XXXのようなプレースホルダーを作成したり、まだ存在しないSPEC番号を引用したりしないでください。IDが重複していないことを確認します：ls docs/05_ADR/ 2>/dev/null。PRD／BRDの上流の系譜は、EARS／BDDの@タグの連鎖を通じて推移的にたどれます。

レイヤーのガイダンス

ステータスのライフサイクル（ADRは他とは異なります）

ADRではProposed → Accepted → Deprecated → Supersededを使用します。Draft／In Review／Approvedは使用しません。ステータスはSPEC-Readyスコアを反映します。

ステータス	SPEC-Ready	意味
Proposed	70–89%	決定を評価中
Accepted	≥90%	承認済み。SPECを作成する準備が完了
Deprecated	—	関連性がなくなった（履歴として保持）
Superseded	—	新しいADRに置き換え済み（リンクする）

必須の構成（番号付き10セクション＋用語集＋付録の後付け情報）

document_controlはセクション1です（ステータス、日付、意思決定者、作成者、originating_topic → PRD §14、brd_reference、SPEC-Readyスコア、改訂履歴）。続いて、次の項目を記載します。

2. Context（問題の説明、ビジネス上の推進要因、制約、技術的背景） · 3. Decision（選択したソリューション、主要コンポーネント、MVP／次サイクルの対象範囲） ·
3. Alternatives Considered（選択肢と、却下した2～3の候補。それぞれの長所と短所を記載します。却下した候補には、却下の決め手となった具体的な要因を記載します。コストと適合性は任意です） · 5. Consequences（望ましい結果、重大度を付したトレードオフ／リスク、決定によって支出が確定する場合は費用の見積もり） · 6. Architecture Flow（図と統合ポイント） · 7. Implementation Assessment（フェーズ、ロールバック、監視の基準値） · 8. Verification（成功基準、BDDとの相互参照） · 9. Traceability · 10. Related Decisions。

必須の後付け情報（番号なし）として、用語集（glossary:キー）と付録（appendix:キー）も追加します。セクション番号と識別子は、ADR-TEMPLATE.yaml内の# Section N:による番号付けに従います。テンプレートが信頼できる唯一の情報源です。

セクションごとの内容と作成時の_antipatternsについては、ADR-TEMPLATE.yamlを参照してください。

要素 ID とタグ

• 要素 ID（ADR 内）： ADR.{doc_id}.{section_id}.{hash}（例： ADR.01.03.e5b1）。各要素に、セクション内で重複しない安定した 4 桁の 16 進数識別子を割り当てます（HASH01）。衝突した場合は 8 桁に拡張します。このプロンプトでは SHA-256 を計算しないでください。ハッシュ形式は、決定論的なツールパスで生成される正規化の TARGET であり、バイト単位で正確なフィールド抽出が定義されているのは BRD §7 のみです（ADR は Phase 2 以降）。基準文書：framework/governance/ID_NAMING_STANDARDS.md。 数値の型コードはありません。要素の種類は、その要素が属するセクションで示されます。
• ADR はドキュメントレベルの成果物です。 参照時はドット形式の要素 ID ではなく、ハイフン形式の ADR-NN を使用します。セルフタグは @adr: ADR-NN（例：@adr: ADR-033）、相互リンクには @depends: ADR-NN と @discoverability: ADR-NN (rationale) を使用します。
• 必須の上流タグ（Layer 5）： @ears @bdd の両方が必須です（必須上流契約に基づく）。各上流要素の ID 形式を使用します（@ears: EARS.01.03.5e2a、@bdd: BDD.01.03.8f4c）。上流の PRD／BRD の系譜は EARS／BDD の @タグチェーンを介して推移的にたどれます。ADR 要素に @brd:／@prd: は出力しないでください。
• 削除された形式（使用禁止）：DEC-XXX、ALT-XXX、CON-XXX、従来の 3 セグメント形式 ADR.NN.xxxx、数値の型コードセグメント、3 桁の ADR-NNN。

作成プロセス

1. トピックを確認する — 1 つの決定を、起点となる PRD §14 のトピックおよび BRD §8 のドライバーまでたどります。
2. ID を予約する — 次に空いている ADR-NN（2 桁。必要な場合のみ桁数を増やします：ADR-01、ADR-99、ADR-102）。 レイヤーごとの独立性（CLEANUP-PR-F item 18）： 自分のレイヤーのインデックスで、次に空いている番号を選びます。上流の番号は自分の番号ではありません（ドキュメント番号はレイヤーごとに独立して連番で付与されます。framework/governance/ID_NAMING_STANDARDS.md §Cross-layer cardinality を参照）。
3. ネストされたフォルダーを作成する — すべての ADR を docs/05_ADR/ADR-NN_{slug}/ に配置します。モノリシック形式の場合は、その中に ADR-NN_{slug}.md を配置します。セクション分割形式（>25 KB）の場合は、${CLAUDE_PLUGIN_ROOT}/framework/layers/05_ADR/ADR-00_index.TEMPLATE.md を基に、ADR-NN.S_{section}.md とインデックスを作成します。
4. まず Document Control（Section 1） を記入し、その後、テンプレートにある §2～§10、用語集、付録のバックマターを完成させます。
5. 選択した案と並べて 2～3 個の代替案を評価します（これにより options: には 3～4 件が含まれます）。却下する各案には、具体的な不採用要因を示した却下理由を記載します。各案の estimated_cost／fit は任意です。より詳細な調査がすでにある場合は、内容を繰り返す代わりに prior_analysis で引用します。根拠を示し、決定を明確に述べます。
6. 必須の上流タグ @ears @bdd を追加し、セルフタグ @adr: ADR-NN と、必要な @depends: 相互リンクを追加します。
7. 同じ変更内で ADR インデックス docs/05_ADR/ADR-00_index.md を更新します。
8. 検証（以下を参照）を行い、ADR とインデックスをまとめてコミットします。

検証

このスキルはバリデーターです（ランタイムコードはありません）。${CLAUDE_PLUGIN_ROOT}/framework/layers/05_ADR/README.md と ${CLAUDE_PLUGIN_ROOT}/framework/governance/ID_NAMING_STANDARDS.md に対して適用してください。

• Document Control が最初のセクションであり、ステータスが Proposed／Accepted／Deprecated／Superseded のいずれかであること。
• 10 個のセクションがすべて存在し、内容が空ではないこと。決定がちょうど 1 つであること。
• 選択したオプションの横に、却下した代替案が 2～3 個あり、それぞれに長所／短所と、具体的な不採用理由があること。コストと適合性は任意です。既存の調査がある場合は、内容を再記述せずに引用してください。
• 結果に、重大度を添えて、プラスの成果とトレードオフが記載されていること。コスト見積もりは、決定によって支出が確定する場合に限ります。
• 要素 ID が ADR.NN.SS.xxxx に一致し、ドキュメント参照がダッシュ形式の ADR-NN を使用しており、削除済みのパターンがないこと。
• 必須の上流タグ @ears @bdd が存在すること（necessary-upstream 契約による）。@adr: ADR-NN のセルフタグがあること。
• ステータスが Accepted の場合、SPEC-Ready スコアが 90 以上であること。
• 図の契約：Architecture-Flow セクションに、${CLAUDE_PLUGIN_ROOT}/framework/governance/DIAGRAM_STANDARDS.md に従った決定／相互作用のシーケンス図（@diagram: sequence-*）が含まれていること。ADR は決定をつなぐ文書であるため、C4 レベルは使用しません（../charts-flow/SKILL.md を使用）。インデックスが更新され、リンク切れがないこと。

コード	意味	重大度
XDOC-002	必須の上流タグがない	error
XDOC-006	タグ形式が無効	error
XDOC-008	内部リンクが切れている	error
XDOC-009	トレーサビリティセクションがない	error

品質ゲート（ブロッキング）： 次に進む前に、SPEC-Ready スコアが 90/100 以上であること。問題が見つかった場合は修正して再確認してください。修正できない場合は、手動レビュー用に記録してください。

ADR-REF ドキュメント（../doc-ref/SKILL.md 経由の ADR-REF-NN_{slug}.md）は、形式自由の参照先です。Ready スコア、必須の上流タグ、品質ゲートの対象外です。

次のスキル

../doc-spec/SKILL.md — SPEC では、この ADR（@adr: ADR-NN）を自身に必要な上流タグ @ears @bdd とともに参照し、決定をコンポーネントインターフェース、データモデル、動作契約へと展開します。

適応

.aidoc/profile.yaml を読み、このスキルの設定項目（section_toggles、glossary）のみを適用してください。不明なキーは無視します。プロファイルがない場合は、フレームワークのデフォルトを使用してください。規定元： ${CLAUDE_PLUGIN_ROOT}/framework/governance/ADAPTATION.md。

関連リソース

• テンプレート／作成ルール：${CLAUDE_PLUGIN_ROOT}/framework/layers/05_ADR/ADR-TEMPLATE.yaml
• レイヤー README：${CLAUDE_PLUGIN_ROOT}/framework/layers/05_ADR/README.md
• インデックステンプレート：${CLAUDE_PLUGIN_ROOT}/framework/layers/05_ADR/ADR-00_index.TEMPLATE.md
• ID とタグの標準：${CLAUDE_PLUGIN_ROOT}/framework/governance/ID_NAMING_STANDARDS.md
• 品質ゲート：../doc-adr-audit/SKILL.md · 修正：../doc-adr-fixer/SKILL.md
• 生成パイプライン：../doc-adr-autopilot/SKILL.md
• 決定の計画：../adr-roadmap/SKILL.md

クイックリファレンス

目的	1 つのアーキテクチャ上の決定を記録する（Context-Decision-Consequences）
レイヤー	5（決定をつなぐ層：PRD → SPEC）
上流タグ	@ears @bdd（necessary-upstream 契約による）
自己参照	ダッシュ形式の @adr: ADR-NN（ドキュメントレベル）
要素 ID	ADR.NN.SS.xxxx（内部要素のみ）
ステータス	Proposed → Accepted → Deprecated → Superseded
必須項目	Document Control（最初）、10 個のセクション、選択したオプションの横に 2～3 個の代替案
次へ	doc-spec