doc-ref

doc-ref

目的

BRD または ADR を補足する、自由形式の補足ドキュメントである Reference Documents（REF） を作成します。REF ドキュメントは正式なトレーサビリティチェーンには参加しません。概要、要約、ガイドなどの背景情報を提供し、要素 ID、累積タグ、準備スコア、品質ゲートは含みません。

レイヤー：横断的なユーティリティ — REF ドキュメントで使用できる親タイプは BRD と ADR のみです。

使用するタイミング

次のような補足資料には doc-ref を使用してください。

• BRD-REF — プロジェクト概要、エグゼクティブサマリー、戦略的ビジョン、ステークホルダー向けガイド。
• ADR-REF — テクノロジースタックの要約、アーキテクチャ概要、インフラストラクチャガイド。

トレーサビリティに参加させるべきもの、コアアーティファクト（BRD/PRD/EARS/BDD/ADR/SPEC/TDD/IPLAN — それぞれの doc-* スキルを使用してください）、または BRD と ADR 以外の親タイプには使用しないでください。

動作

命名と配置場所

• ファイル名：{TYPE}-REF-NN_{slug}.md（TYPE ∈ {BRD, ADR}）；H1：# {TYPE}-REF-NN: Title。
• NN は可変長の連番（2 桁以上）で、親タイプごとに独立しています。BRD-REF-01、BRD-REF-102、ADR-REF-01 はそれぞれ別の連番です。
• 親タイプのディレクトリ内に配置します。例：docs/01_BRD/BRD-REF-01_project_overview.md、docs/05_ADR/ADR-REF-01_technology_stack_summary.md。
• 正規表現 — ファイル：^(BRD|ADR)-REF-[0-9]{2,}_[a-z0-9_]+\.md$；H1：^#\s(BRD|ADR)-REF-[0-9]{2,}:.+$。

作成プロセス

1. 親タイプを決定する — ビジネスコンテキストなら BRD-REF、アーキテクチャコンテキストなら ADR-REF です。
2. 次の番号を割り当てる — ls docs/01_BRD/*-REF-* 2>/dev/null（または 05_ADR）を実行し、次に空いている NN を割り当てます。
3. 親テンプレートから、REF に必要な内容だけを残してドラフトを作成する — ${CLAUDE_PLUGIN_ROOT}/framework/layers/01_BRD/BRD-TEMPLATE.yaml（BRD-REF）または ${CLAUDE_PLUGIN_ROOT}/framework/layers/05_ADR/ADR-TEMPLATE.yaml（ADR-REF）を元にし、必須の 4 セクションのみを残して、トレーサビリティの枠組みを削除します。
4. 配置する — 正しい H1 を設定し、ファイルを親タイプのディレクトリに配置します。

必須セクション（4 つ、必須）

1. YAML フロントマター（artifact_type: REF）。
2. ドキュメント管理情報（バージョン、日付、作成者、ステータス）。
3. ドキュメント改訂履歴。
4. はじめに（目的とスコープ）。

任意：関連ドキュメント（相互参照を推奨）と、参考資料に必要なコンテンツセクション。

検証（このスキルがバリデーターです）

ブロッキングチェックのみ：H1 が {TYPE}-REF-NN: Title と一致すること、ドキュメント管理情報、改訂履歴、はじめにの各セクションが存在すること。累積タグ、完全なトレーサビリティ、品質ゲート、準備スコアは検証対象外です。REF ドキュメントはチェーンに参加しません。要素 ID は適用されません。

関連リソース

• 親テンプレート：${CLAUDE_PLUGIN_ROOT}/framework/layers/01_BRD/BRD-TEMPLATE.yaml、${CLAUDE_PLUGIN_ROOT}/framework/layers/05_ADR/ADR-TEMPLATE.yaml
• 命名規則の管理元：${CLAUDE_PLUGIN_ROOT}/framework/governance/ID_NAMING_STANDARDS.md · ../doc-naming/SKILL.md
• ガバナンスと各レイヤーの管理元：${CLAUDE_PLUGIN_ROOT}/framework/governance/ および各 ${CLAUDE_PLUGIN_ROOT}/framework/layers/NN_<X>/README.md
• 親スキル：../doc-brd/SKILL.md · ../doc-adr/SKILL.md
• ワークフローの振り分け：../doc-flow/SKILL.md
• 図表：../charts-flow/SKILL.md