doc-spec

doc-spec

目的

**技術仕様書（SPEC）**を作成します。これは SDD フローのレイヤー 6 です。SPEC は、単一のソフトウェアコンポーネントを対象とする、実装可能な C4-L3（コンポーネント）レベルの契約です。インターフェース、データモデル、動作を定義し、後続のテストやコードを作成する前に記述します。

レイヤー：6 — 統合仕様書。SPEC は、以前のバージョンでコンポーネント／データ／UX／リスク／プロセス仕様書に分かれていた内容を包含します。現在は、コンポーネントごとに 1 つの SPEC 成果物を作成します。 上流：EARS、BDD、ADR（必要な上流成果物に関する契約に従います。主な情報源は ADR です。上流の PRD／BRD の系譜は、@タグの連鎖をたどることで間接的に確認できます）。 下流：TDD → IPLAN → Code。

使用するタイミング

次の場合に doc-spec を使用します。

• アーキテクチャ決定（ADR）が確定し、コンポーネントの仕様を定義する必要がある場合。
• EARS／BDD の受け入れ契約を、具体的なインターフェース、データモデル、動作ルールに落とし込む場合。
• TDD のテストケースを作成する前に、実装可能な契約が必要な場合。

BDD／ADR、プロンプト、または IPLAN からエンドツーエンドで生成するには、 ../doc-spec-autopilot/SKILL.md を使用します。

前提条件

SPEC はレイヤー 6 に位置するため、作成前に必要な上流成果物（EARS、BDD、 ADR）が存在することを確認してください。参照するのは、すでに存在するドキュメントのみです。SPEC-XXX や ADR-XXX のようなプレースホルダーを決して作成しないでください。作成前に、以下を読みます。

1. テンプレート（信頼できる唯一の情報源）： ${CLAUDE_PLUGIN_ROOT}/framework/layers/06_SPEC/SPEC-TEMPLATE.yaml
2. レイヤーの README： ${CLAUDE_PLUGIN_ROOT}/framework/layers/06_SPEC/README.md
3. ID とタグの標準： ${CLAUDE_PLUGIN_ROOT}/framework/governance/ID_NAMING_STANDARDS.md
4. 作成スタイル： ${CLAUDE_PLUGIN_ROOT}/framework/governance/AUTHORING_STYLE.md
5. **上流 ADR（主要な情報源）**と、コンポーネントが満たす必要のある BDD／EARS の受け入れ契約。

既存の上流成果物が存在し、ID が重複していないことを確認します。 ls docs/05_ADR/ docs/06_SPEC/ 2>/dev/null

レイヤーのガイダンス

C4-L3 の範囲（コンポーネントレベルを維持する）

SPEC はコンポーネントレベルです。アーキテクチャ決定（ADR）やソースコード（Code）ではなく、コンポーネントのインターフェースと契約を記述します。

この範囲内（PASS）	範囲外（FAIL）
AuthService、UserRepository、NotificationQueue	auth_service.py、async def validate_token()
インターフェースのシグネチャ、型付きデータモデル	具体的な SQL テーブル、Redis キーの形式
動作ルール、状態遷移、エラー契約	Kubernetes のポッド設定、デプロイメントマニフェスト

必須の図タグ：@diagram: c4-l3、@diagram: dfd-l3（ ../charts-flow/SKILL.md を使用）。シーケンス図には、エラーパスを示す alt/else を含めてください。C4-L4 のコード／クラス図を埋め込んではいけません。

必須の構成（8 セクション）

document_control を最初に配置します（ステータス、バージョン、日付、作成者、コンポーネント、 tdd_ready_score）。続いて、以下を記述します。

1. ドキュメント管理 · 2. コンポーネント概要（説明、@adr による決定、 言語、依存関係） · 3. インターフェース（エクスポート：シグネチャ、型、エラー） ·
2. データモデル（型付きフィールド、SQL／ORM は使用しない） · 5. 動作（検証ルール、 状態遷移、エラー処理。それぞれに @ears／@bdd の出典を明記） ·
3. 実装上の注意事項（制約、パターン、パフォーマンスに関する考慮事項） ·
4. 下流の TDD 契約（@tdd: TDD-NN、テストファイルの対応表） · 8. トレーサビリティ。

各セクションの内容については、SPEC-TEMPLATE.yaml を参照してください。形式は YAML です。

要素 ID とタグ

• SPEC は DOCUMENT レベルの成果物です — ダッシュ形式の SPEC-NN で参照します （2 桁で、余分な先頭ゼロは付けません：SPEC-01、SPEC-99、SPEC-102）。 下流の成果物では @spec: SPEC-12 のタグを付けます。SPEC 自体には、ドット区切りの SPEC.NN.SS.xxxx 要素形式はありません。
• 必須の上流タグ（必要な上流要件に基づく）：階層参照には 4 セグメントの要素形式を使います — @ears: EARS.NN.SS.xxxx、 @bdd: BDD.NN.SS.xxxx。ドキュメントレベルでは @adr: ADR-NN を使います。上流の PRD／BRD の 系譜は EARS／BDD の @ タグチェーンを通じて推移的にたどれるため、SPEC 要素に @brd:／@prd: を付けないでください。
• **しきい値：**パフォーマンス／タイムアウト／レート制限の値をハードコードせず、 @threshold: レジストリ参照を使います。
• 廃止されたパターン（使用しないでください）：STEP-XXX、IF-XXX、INT-XXX、DM-XXX、 MODEL-XXX、VR-XXX、3 桁の SPEC-NNN、数値の要素タイプコード表、および削除済みの SYS／REQ／CTR 上流レイヤー。

作成プロセス

1. 上流を読む — ADR の決定事項と、コンポーネントが満たす BDD／EARS コントラクトを確認します。
2. ID を予約する — docs/06_SPEC/ で次に利用可能な SPEC-NN を使います。 レイヤーごとの独立性（CLEANUP-PR-F item 18）： 上流の番号ではなく、自分のレイヤーのインデックスで次に利用可能な 番号を選びます（ドキュメント番号はレイヤーごとに連番で独立しています。framework/governance/ID_NAMING_STANDARDS.md §Cross-layer cardinality を参照）。
3. ネストされたフォルダーを作成する — サイズにかかわらず、すべての SPEC は docs/06_SPEC/SPEC-NN_{slug}/SPEC-NN_{slug}.yaml に配置します。SPEC ファイルを docs/06_SPEC/ 直下に置かないでください。
4. まず Document Control を記述し、次にテンプレートの 8 つのセクションをすべて完成させます。
5. 型付きシグネチャで インターフェースとデータモデルを定義し、各ルールの出典を @ears／@bdd として 振る舞いを規定します。
6. 必須の上流タグ（必要な上流要件に基づく @ears @bdd @adr）と、下流の @tdd: TDD-NN コントラクトを 追加します。
7. 同じ変更内で SPEC インデックス docs/06_SPEC/SPEC-00_index.md を更新します。
8. 以下の検証を行い、SPEC とインデックスをまとめてコミットします。

検証

このスキル自体がバリデーターです（ランタイムコードはありません）。${CLAUDE_PLUGIN_ROOT}/framework/layers/06_SPEC/README.md と ${CLAUDE_PLUGIN_ROOT}/framework/governance/ID_NAMING_STANDARDS.md に照らして適用します。

• YAML をパースできること。Document Control が最初のセクションであること。
• 8 つのセクションがすべて存在し、内容が空でないこと。形式が YAML（Markdown ではない）であること。
• コンポーネントレベルのみであること（コード／SQL／デプロイの詳細を含まないこと。C4-L3 のスコープを維持すること）。
• ドキュメント ID がダッシュ形式の SPEC-NN であること。ドット区切りの SPEC 要素 ID や廃止されたパターンがないこと。
• 必須の上流タグ（必要な上流要件に基づく @ears @bdd @adr）があること。下流の @tdd: TDD-NN コントラクトがあること。
• 定量値に @threshold: 参照を使っていること（マジックナンバーがないこと）。
• 図のコントラクトとして @diagram: c4-l3 と @diagram: dfd-l3 があること（../charts-flow/SKILL.md を使用）。
• トレーサビリティマトリクス／インデックスが作成または更新されていること。リンク切れがないこと。

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

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

次のスキル

../doc-tdd/SKILL.md — TDD はこの SPEC（@spec: SPEC-NN）を参照し、独自の必須上流タグ @ears @bdd @adr とともに、SPEC コントラクトのテストケース、入力、期待される出力、しきい値を定義します。

適用

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

関連リソース

• テンプレート／作成ルール：${CLAUDE_PLUGIN_ROOT}/framework/layers/06_SPEC/SPEC-TEMPLATE.yaml
• レイヤーの README：${CLAUDE_PLUGIN_ROOT}/framework/layers/06_SPEC/README.md
• インデックステンプレート：${CLAUDE_PLUGIN_ROOT}/framework/layers/06_SPEC/SPEC-00_index.TEMPLATE.md
• ID とタグの標準：${CLAUDE_PLUGIN_ROOT}/framework/governance/ID_NAMING_STANDARDS.md
• 上流の決定事項：../doc-adr/SKILL.md · 下流のテスト：../doc-tdd/SKILL.md
• 品質ゲート：../doc-spec-audit/SKILL.md · 修正：../doc-spec-fixer/SKILL.md
• 生成パイプライン：../doc-spec-autopilot/SKILL.md

クイックリファレンス

目的	コンポーネントを仕様化します：インターフェース、データモデル、動作
レイヤー	6（C4-L3 コンポーネント）
上流タグ	@ears @bdd @adr（必要な上流の契約に従います）
ドキュメント ID	ダッシュ形式の SPEC-NN（ドキュメントレベル。ドット区切りの要素 ID はありません）
必須項目	ドキュメント管理情報（最初に記載）、8 つのセクション、数値には @threshold
形式	YAML
次のステップ	doc-tdd