feature-docs

Codex 互換性に関する注意：

• Codex では $skill-name を使ってリポジトリのスキルを呼び出します。このミラー版では、従来の Claude の /skill-name 参照を書き換えています。
• タスクトラッカーの必須事項：ワークフローまたはスキルの手順を実行する前に、すべての手順のタスク追跡を作成または更新し、進捗に応じて同期を保ってください。
• ユーザーへの質問を促すプロンプトは、Codex でユーザーに直接質問することを意味します。
• Claude 固有のモード切り替え指示がある場合は無視してください。
• 厳格な実行契約：ユーザーがスキルを明示的に呼び出した場合は、記載どおりにそのスキルのプロトコルを実行してください。
• サブエージェントの使用許可：スキルがユーザーによって呼び出された場合、または AI がスキルの適用を判断した場合に、そのプロトコルでサブエージェントが必要とされていれば、そのスキルの有効化により、該当タスクで必要な spawn_agent サブエージェントを使用する権限が付与されます。
• ユーザーが事前に逸脱を明示的に承認しない限り、プロトコルの手順を省略、入れ替え、統合しないでください。
• ワークフロー用スキルでは、列挙された子スキルの各手順を明示的に実行し、手順ごとの証拠を報告してください。
• 必須の手順またはツールをこの環境で実行できない場合は、対応を変更する前に作業を止め、ユーザーに確認してください。

Codex のプロジェクト参照資料の読み込み（フックなし）

Codex では、Claude のフックによるドキュメントの自動注入は行われません。 コーディング、計画、デバッグ、テスト、レビューを行う際は、以下の参照先に従ってプロジェクトのドキュメントを明示的に開いてください。

必ず読む資料：

• docs/project-config.json（プロジェクト固有のパス、コマンド、モジュール、ワークフロー、テスト設定）
• docs/project-reference/docs-index-reference.md（docs/project-reference/* の全資料一覧への案内）
• docs/project-reference/lessons.md（常に適用されるガードレールとアンチパターン）

状況に応じて読む資料：

• バックエンド／CQRS／API／ドメイン／エンティティの変更：backend-patterns-reference.md、domain-entities-reference.md、project-structure-reference.md
• フロントエンド／UI／スタイリング／デザインシステム：frontend-patterns-reference.md、scss-styling-guide.md、design-system/README.md
• 仕様／テストケースの計画、または TC マッピング：feature-docs-reference.md
• 統合テストの実装／レビュー：integration-test-reference.md
• E2E テストの実装／レビュー：e2e-test-reference.md
• コードレビュー／監査：code-review-rules.md と、変更対象ファイルに応じたドメイン資料

すべての資料をむやみに読まないでください。docs-index-reference.md から始め、タスクに関連するファイルだけを開いてください。

クイックサマリー

[IMPORTANT] タスクの追跡 — 作業を始める前に、すべての作業を小さなタスクに分割してください。単純なタスクの場合は、省略するかどうかをユーザーに確認してください。

目標： すべてのテストケースに必須のコードエビデンスを含む、包括的な17セクションのビジネス機能ドキュメントを生成します。

モード：

モード	トリガー	入力	出力
init	docs/business-features/{Module}/ が存在しない	ソースコード全体	17セクションのドキュメントを一から作成
update	ドキュメントが存在し、コードが変更されている	Git の差分／明示的なモジュール	セクションへの影響を対応付けた更新
audit	--audit フラグ、またはユーザーからの依頼	ソースコード＋既存ドキュメント	セクションごとの陳腐化レポート

ワークフロー：

1. 検出と収集 — Git の変更またはユーザー指定のモジュールからモジュールを自動検出し、既存のドキュメントを読み込みます
2. コードの調査 — grep/glob でコードベースを検索し、すべてのテストケースのエビデンスを追跡します。[Source: namespace/service/id] という抽象アンカーとして記録します（物理的な file:line は出典情報のサイドカーに記録します）
3. ドキュメントの作成 — 17セクションの厳密な構成に従い、docs/business-features/{Module}/ に配置します
4. 検証 — 4段階の検証システム：エビデンス監査、ドメインモデル、相互参照、AI 実装可能性

主なルール：

• [BLOCKING] docs/project-reference/spec-principles.md を読みます — 仕様の品質基準、AI 実装可能性の基準、技術に依存しないルール（§3 の対象範囲＋§3.2 の禁止されている文章トークン一覧）を確認します（フェーズ3.5の検証前にセクション4の完全性チェックリストを読みます）
• [BLOCKING] 例外なく、すべてのテストケースに検証可能なコードエビデンス（FilePath:LineNumber）を付ける必要があります
• 出力は、マスターテンプレートに一致する17セクションちょうどでなければなりません
• ドキュメントを変更する際は、必ず CHANGELOG.md と変更履歴（セクション17）を更新します
• セクション15の TC：IntegrationTest フィールドはエビデンスを保持するフィールドです（**Evidence** のような実装識別子はここに記載します）→ IntegrationTest: Orders/OrderCommandIntegrationTests.cs::{MethodName}。TC の動作に関する文章は技術に依存しない表現にします（spec-principles.md §3）。テストパスはこのエビデンスフィールドにのみ記載します。テストがまだない場合→Status: Untested
• すべての TC-{FEATURE}-{NNN} に対し、統合テストに [Trait("TestSpec", "TC-{FEATURE}-{NNN}")] があることを確認します。ない場合→Status: Untested
• 3回目の検証で問題が5件を超えた場合は停止し、検証を再実行します

docs/project-reference/domain-entities-reference.md — ドメインエンティティのカタログ、関連性、サービス間の同期（該当する場合は直接読み、フックによって会話に挿入されたテキストに依存しないでください）

M1-M6 準拠チェックリスト（ブロッキング — 違反が1つでもあればドキュメントは不合格）

ブロッキング基準については、.claude/skills/shared/sdd-artifact-contract.md →「AI-SDD Mandates (M1-M6)」を参照してください。出力前に、すべての機能ドキュメントが以下のすべてを満たす必要があります。違反が1つでもあればドキュメントは不合格となり、修正が必要です。

• M1 — 技術に依存しない文章： §1-14 の説明文、見出し、表、用語集では、ビジネス機能のみを記述してください。説明文にフレームワーク、製品、言語、永続化、メッセージング、認証の名称や、プロジェクト内部のフレームワーク型名を含めないでください（禁止トークンの一覧：spec-principles.md §3.2）。これらの用語が許可されるのは、証拠を示すフィールド（**Evidence**、IntegrationTest、[Source:]）、YAML フロントマター、```mermaid ``` ブロック内のみです。
• M2 — 説明文にソースコードを含めない： 説明文にクラス名、メソッド名、ファイルパス、名前空間を含めないでください。ビジネス操作名を使用し、ソース識別子は証拠を示すフィールド内にのみ記載してください。
• M3 — 論理 ID を優先したトレーサビリティ： すべての FR／BR／操作には、主軸となる論理 ID（FR-/BR-/OP-/TC-）と、これとは別の [Source: namespace/service/id] 形式のスタック移植可能な抽象アンカー証拠フィールドを付けてください（物理的な file:line／src/ パスは不可。これらはプロヴェナンスのサイドカーにのみ記載します。分類体系：docs/specs/MIGRATION.md）。論理 ID はルールの記述に残し、ソースリンクは説明文に含めないでください — [Source:] を削除してはいけません。
• M4 — AI による実装が可能： 各要件は解釈が一意で、成功／失敗の結果を観測可能にし、失敗モードに名前を付けてください。「適切に処理する」といった曖昧な表現は避けてください。
• M5 — ゼロから再構築可能： コードベースの知識がまったくないチームでも、ドキュメントだけを使い、任意のスタック上で同一のビジネス動作を再実装できるようにしてください。

プロジェクトパターンの調査

実装前に、コードベース内でプロジェクト固有のパターンを検索してください。

• 検索対象：business-features、detailed-features、feature-docs-template
• 確認事項：既存の機能ドキュメントフォルダー、17 セクションのテンプレート

[BLOCKING] プロジェクト固有のパターンを確認するため、feature-docs-reference.md を読んでください。見つからない場合は、検索による調査を行ってください。

機能ドキュメントの生成と検証

プロジェクトの規約に従って、機能ドキュメントを生成してください。

GOLD STANDARD： 既存の機能ドキュメントを検索してください：find docs/business-features -name "README.*.md" -type f | head -5

テンプレート： docs/templates/detailed-feature-docs-template.md

---

[CRITICAL] 必須のコード証拠ルール

すべてのテストケースには、検証可能なコード証拠が必須です。これは絶対条件です。

証拠の形式

証拠はスタック移植可能な抽象アンカーです。ドナーの file:line、.cs、src/ パスは使用しないでください。

**Evidence**: `[Source: {namespace}/{service}/{id}]`

Namespace ∈ operation | event | component | schema | requirement | rule | constraint | test。Service は所有モジュール（小文字）。Id はコード接尾辞を取り除いた成果物の概念です。物理座標はプロヴェナンスのサイドカーを通じてのみ確認できます。完全な規約については docs/specs/MIGRATION.md を参照してください。

有効な証拠と無効な証拠

有効	無効
[Source: operation/orders/CreateOrder]	ErrorMessage.cs:83（物理的な file:line）
[Source: component/orders/Order]	{namespace}/{service}/{id}（テンプレート）
[Source: event/accounts/AccountUserSaved]	"CQRS パターンに基づく"（曖昧）

フィールド内のみ： 抽象アンカー（および IntegrationTest のテストリンク）は、**Evidence**／IntegrationTest フィールド内にのみ記載してください。テストケースの動作説明には含めないでください。動作説明は技術に依存しない内容にします（spec-principles.md §3）。物理的な {TestFile}::{MethodName} リンクを保持する例外は IntegrationTest のみです（運用上の QA 用接続情報。tc-format.md を参照）。

---

出力構造

すべてのドキュメントは、正しいフォルダー構造に配置してください。

docs/
├── BUSINESS-FEATURES.md              # Master index (UPDATE if new module)
├── templates/
│   └── detailed-feature-docs-template.md  # MASTER TEMPLATE
└── business-features/
    ├── {Module}/                     # One folder per service/module in your project
    │   ├── README.md                 # Complete module documentation
    │   ├── INDEX.md                  # Navigation hub
    │   ├── API-REFERENCE.md          # Endpoint documentation
    │   ├── TROUBLESHOOTING.md        # Issue resolution guide
    │   └── detailed-features/
    │       └── README.{FeatureName}.md     # Comprehensive (17-section, max 1200 lines)
    └── ...

モジュールのマッピング

コードベースを検索して、モジュールとフォルダーのマッピングを確認します。

# Find all service directories
ls -d src/Services/*/

# Find all existing feature doc modules
ls -d docs/business-features/*/

各モジュールコードをフォルダー名とサービスパスにマッピングします。例：

モジュールコード	フォルダー名	サービスパス
{Module1}	{Module1}	src/Services/{Module1}/
{Module2}	{Module2}	src/Services/{Module2}/

---

必須の17セクション構成

すべての機能ドキュメントは、以下の順序でセクションを構成する必要があります。

#	セクション	対象読者
1	ヘッダー + メタデータ（YAML frontmatter）	全員
2	用語集	全員
3	エグゼクティブサマリー	PO、BA
4	ビジネス要件	BA、開発者
5	ドメインモデル	開発者、アーキテクト
6	ビジネスルール	BA、開発者
7	プロセスフロー	BA、開発者
8	コマンドと操作	開発者
9	イベントとバックグラウンドジョブ	開発者
10	UI ページ	開発者、UX
11	API リファレンス（簡易版）	開発者
12	サービス間連携	アーキテクト
13	セキュリティと権限	開発者、アーキテクト
14	パフォーマンスに関する考慮事項	開発者、アーキテクト
15	テスト仕様	QA、開発者
16	トラブルシューティング	開発者、QA
17	バージョン履歴	全員

ステークホルダー向けクイックナビゲーション

対象者	セクション
プロダクトオーナー	エグゼクティブサマリー、ビジネス要件
ビジネスアナリスト	ビジネス要件、ビジネスルール、プロセスフロー、ドメインモデル
開発者	ドメインモデル、コマンドと操作、API リファレンス、イベント、UI ページ
テクニカルアーキテクト	ドメインモデル、サービス間連携、セキュリティ、パフォーマンス
QA/QC	テスト仕様、ビジネスルール、トラブルシューティング
UX デザイナー	UI ページ、プロセスフロー

---

ステップ 0 — モード検出（必ず最初に実施）

抽出を開始する前に、モードを検出します。

1. docs/business-features/{Module}/ が存在するか確認します（または --audit フラグを確認します）。
2. モジュールが自動検出された場合は、docs/business-features/ ツリー全体を確認します。
3. 続行する前に、検出したモードを直接ユーザーに質問して確認します。自動的に開始してはいけません。

モードの振り分け：

条件	モード	次のステップ
docs/business-features/{Module}/ が見つからない	INIT	→ モード：INIT
docs/business-features/{Module}/ が存在する	UPDATE	→ フェーズ 1.5（既存ドキュメントの更新モード）
--audit フラグがある、またはユーザーが監査を要求する	AUDIT	→ モード：AUDIT

INIT モードの規模ゲート（ワークフローコンテキストのみ）： 呼び出し元が workflow-spec-driven-dev で、かつ module_count ≥ 4 の場合は、1 回のメッセージでサブエージェントを起動する必要があります（モジュールごとに 1 つ）。feature-docs が単独で単一モジュールに対して呼び出された場合、規模ゲートは適用されません。単一モジュールの初期化は常に 1 セッションで行います。

---

モード：INIT（新規機能ドキュメント）— ゼロからの完全な抽出

ドキュメントが存在しない場合は、17 セクションのドキュメントに整形する前に、spec-discovery 形式の抽出を実行します。

Step 1-INIT.1: 全体のスカウト

各ファイルの詳細を読む前に、モジュールのコードベース全体を把握します。

1. git ls-files src/Services/{Module}/（または該当するパス）を実行し、ファイルの一覧をすべて取得します
2. エンティティファイル、コマンドファイル、クエリファイル、コントローラーファイル、イベントハンドラーファイル、フロントエンドコンポーネントを特定します
3. モジュール抽出マップを作成します：
   • エンティティ層：すべてのエンティティ／集約ファイルを列挙します
   • バリデーション層：すべてのバリデーターファイルを列挙します
   • コマンド層：すべてのコマンドハンドラーファイルを列挙します
   • API 層：すべてのコントローラーファイルを列挙します
   • イベント層：すべてのイベントハンドラーとバスコンシューマーファイルを列挙します
   • フロントエンド：すべてのコンポーネント、サービス、ストアファイルを列挙します

Step 1-INIT.1.5: ユースケースの列挙［ブロッキング — Step 2 / Phase A の前に必ず完了］

目標： 抽出タスクを計画する前に、すべての操作数を数えます。この数が Section 15 の TC 数の最小値になります。

書き込み側のエントリーポイント：

# CQRS command handlers
grep -r "ICommandHandler\|CommandHandler\b" src/Services/{Module}/ --include="*.cs" -l
# REST/MVC mutating endpoints
grep -r "\[HttpPost\]\|\[HttpPut\]\|\[HttpPatch\]\|\[HttpDelete\]" src/Services/{Module}/ --include="*.cs" -l
# Event consumers / background jobs
grep -r "IConsumer\|EventHandler\|IMessageConsumer\|BackgroundJob\|IHostedService" src/Services/{Module}/ --include="*.cs" -l

読み取り側のエントリーポイント：

# CQRS query handlers
grep -r "IQueryHandler\|QueryHandler\b" src/Services/{Module}/ --include="*.cs" -l
# REST/MVC GET endpoints
grep -r "\[HttpGet\]" src/Services/{Module}/ --include="*.cs" -l

アクター／ロールの特定（Phase E と Section 13 に反映）：

# Permission attributes and role guards
grep -r "\[Authorize\]\|RequirePermission\|IsInRole\|HasPermission" src/Services/{Module}/ --include="*.cs" -l
# Role/permission enums
grep -r "enum.*Role\|enum.*Permission" src/Services/{Module}/ --include="*.cs" -n | head -20
# Frontend route guards (if applicable)
grep -r "canActivate\|AuthGuard\|RoleGuard\|PermissionGuard" src/{frontend-root}/ --include="*.ts" -l 2>/dev/null | grep -i {module} | head -5

ユースケースのインベントリー出力：

レイヤー	書き込み操作数（N）	読み取り操作数（M）	イベント駆動（K）	バックグラウンド（J）	合計	アクターロール
{Module}	N	M	K	J	N+M+K+J	[grep で見つかったロール]

［ゲート — Phase A の抽出前に必須］：

• 総数（N+M+K+J）= Section 15 の TC 数の最小値
• 総数が 20 以上の場合：抽出を操作グループ（各グループ 20 操作以下）に分割する必要があります。抽出フェーズを開始する前に、グループごとにタスクを作成して追跡します。
• アクターカタログには 1 つ以上のロールを記載するか、「ロールが見つかりません — 認証属性を手動で確認してください」と記載する必要があります

Step 1-INIT.2: ドメインモデルの抽出（Phase A）

エンティティ層の各エンティティについて：

1. エンティティファイルを読みます
2. 名前、目的（1 文）、属性（名前、必須かどうか、制約、ビジネス上の意味）、ライフサイクル状態、不変条件を抽出します
3. 関係を特定します：外部キーのフィールド、ナビゲーションプロパティ、コレクションフィールド → 多重度
4. [Source: component/{service}/{Entity}] という抽象アンカーを使ってエンティティの説明を記述します（物理座標 → プロベナンスサイドカー）
5. ERD 生成用にすべてのエンティティを収集します

ERD の生成（すべてのエンティティの抽出後に必須）：

• Mermaid の erDiagram ブロックを生成します
• 技術に依存しない型のみを使用します：string、number、boolean、date、list、map
• 集約ルートに %% [AGGREGATE: ...] のマークを付けます
• モジュールをまたぐ参照はスタブとして記載します：%% [CROSS-REF: module-name]
• Section 5 用に ERD を .ai/workspace/analysis/{Module}-erd.md に保存します

Step 1-INIT.3: ビジネスルールの抽出（Phase B）

バリデーション層の各バリデーター／コマンドハンドラーについて：

1. ファイルを読み、バリデーションルール（フィールド → ルール → エラー条件 → エラーメッセージ）を抽出します
2. 認可ルール（操作 → 実行できるユーザー → 条件）を抽出します
3. エンティティにライフサイクル状態がある場合は、状態遷移を抽出します
4. ルールグループごとに [Source: rule/{service}/{RuleName}] という抽象アンカーを付けて記述します

Step 1-INIT.4：API コントラクトの抽出（フェーズ C）

アプリケーション層の各エントリーポイントについて、次の優先順位で読み取ります。

1. CQRS コマンドハンドラー（UseCaseCommands/）— ハンドラークラスごとに 1 エントリーを作成します。抽出項目：ハンドラー名 → ビジネス操作名（技術に依存しない名称）、コマンドフィールド、参照される検証ルール、出力型。
2. CQRS クエリハンドラー（UseCaseQueries/）— ハンドラークラスごとに 1 エントリーを作成します。抽出項目：操作名、フィルターパラメーター、戻り値の形式、ページネーション。
3. イベントコンシューマー（UseCaseEvents/）— コンシューマーごとに 1 エントリーを作成します。抽出項目：消費するイベント、発生する副作用、出力状態の変更。
4. バックグラウンドジョブ — ジョブごとに 1 エントリーを作成します。抽出項目：スケジュール／トリガー、実行される操作、副作用。
5. REST コントローラー — 補足のみ（HTTP アダプター層）。抽出項目：HTTP メソッド + パス + 認証の要否 + DTO の形式。ただし、上記のハンドラーですでに扱われていない操作のみを対象とします。

操作の説明にはビジネス用語のみを使用し、C# の型名やクラス名は使用しないでください。各エントリーには、抽象アンカー [Source: operation/{service}/{Operation}] を付けてください。

必須： Use Case Inventory（Step 1-INIT.1.5）の各操作に対し、フェーズ C のエントリーを必ず 1 つだけ作成してください。フェーズ C の後にエントリー数を数えます。件数がインベントリーの Grand Total より少ない場合は、フェーズ D の前に補完タスクを作成してください。

Step 1-INIT.4.5：クロスサービス範囲のグラフトレース（セクション 12 の前）

イベントとクロスサービス連携を抽出する前に、グラフ分析を実行してすべてのコンシューマーとプロデューサーを特定します。

# Trace cross-service flow from the primary entity file
python .claude/scripts/code_graph trace src/Services/{Module}/{Module}.Domain/Entities/{PrimaryEntity}.cs --direction both --json

# Find all files connected to the primary service entry point
python .claude/scripts/code_graph connections src/Services/{Module}/{Module}.Service/Controllers/{PrimaryController}.cs --json

.code-graph/graph.db を利用できない場合： IBusMessage、IConsumer、[IntegrationEvent] パターンを grep して代替してください。

grep -rn "IBusMessage\|IConsumer\|IntegrationEvent" src/Services/{Module}/ --include="*.cs"

グラフの出力を使用して、送信イベント（生成するもの）、受信イベント（消費するもの）、クロスサービスコマンドを列挙します。すべての調査結果をセクション 12 とセクション 9 に反映してください。

Step 1-INIT.5：イベントとジョブの抽出（フェーズ D）

各イベントハンドラーとバスコンシューマーについて：

1. 抽出項目：イベント名、トリガー、ペイロードフィールド、順序保証
2. バックグラウンドジョブ：スケジュール、目的、副作用、中断条件
3. 抽象アンカー [Source: event/{service}/{Event}] を付けてください（バックグラウンドジョブには operation/{service}/{Job} を使用します）。

Step 1-INIT.6：ユーザージャーニーの作成（フェーズ E）

情報源 — 以下の 3 つすべてが必須です：

1. バックエンド操作（フェーズ C から）：書き込み操作ごとにユーザーストーリーを 1 つ、フィルターパラメーターがある読み取り／クエリごとに検索／一覧／表示のストーリーを 1 つ作成します。
2. UI ルートと画面：フロントエンドモジュール内の個別のルート／ページごとに、画面ストーリーを 1 つ作成します。
3. アクターカタログ（Step 1-INIT.1.5 から）：すべてのアクターを 1 つ以上のストーリーに必ず登場させてください。

ユーザーストーリーの形式（すべてのストーリーで必須）：

「{アクターカタログに記載されたアクター}として、{動詞 + 対象}したい。それによって、{ビジネス上の成果}を実現するためです。」

ストーリーテンプレート：

## Journey: {JourneyName}

- **User Story:** As a {actor}, I want to {action}, so that {outcome}.
- **Actor:** {exact role name from actor catalog}
- **Operation Type:** write | read | event-driven | background | ui-screen
- **Trigger:** {what starts this journey}
- **Preconditions:** {what must already exist}
- **Happy Path:** 1. {Step 1} ...
- **Alternative Paths:** {Condition A} → {what happens}
- **Outcome:** {what actor achieves}
- **Acceptance Criteria:**
    - GIVEN {precondition} WHEN {action} THEN {outcome}
      [Source: operation/{service}/{Operation}]

フェーズ E の完全性チェックリスト（Step 1-INIT.7 に進む前の必須条件）：

• ジャーニー数 ≥ フェーズ C のエントリー数（Use Case Inventory の Grand Total）
• アクターカタログのすべてのアクターが、1 つ以上のジャーニーに登場する
• 発見されたすべての UI ルートに、1 つ以上の画面ストーリーがある
• フィルターパラメーターがあるすべての GET／クエリに、検索／一覧／表示のストーリーがある
• すべてのストーリーが「As a / I want / So that」の形式を使用している
• すべてのストーリーに、抽象アンカー [Source: operation/{service}/{Operation}] がある

Step 1-INIT.7：17 セクション形式への変換

抽出が完了したら、抽出した内容を 17 セクションの構成に整形します。

抽出フェーズ	対象セクション
フェーズ A のエンティティ	セクション 5（ドメインモデル）— ERD + [Source: component/{service}/{Entity}]
フェーズ B のルール	セクション 6（ビジネスルール）+ セクション 4（ビジネス要件 FR-XX）
フェーズ C の操作	セクション 8（コマンド）+ セクション 11（API リファレンス）
フェーズ D のイベント	セクション 9（イベントとバックグラウンドジョブ）+ セクション 12（サービス間連携）
フェーズ E のジャーニー	セクション 10（UI ページ）+ セクション 15（TC-XX ID 付きテスト仕様）
認証ルール	セクション 13（セキュリティと権限）

[BLOCKING] セクション 15 の準備状況ゲート — セクション 15 を記述する前に、基盤となるセクションが完成していることを確認してください。

セクション	TC 作成に必要か？	確認事項
S4 ビジネス要件	はい — TC は FR-XX に対応します	FR-XX エントリが 1 件以上ある
S6 ビジネスルール	はい — TC は BR-XX を参照します	エラー条件を含む BR-XX が 1 件以上ある
S8 コマンド	はい — TC には操作の対象が必要です	コマンドエントリが 1 件以上ある
S13 セキュリティ	はい — TC には認証チェックが必要です	権限マトリックスがある

これらのセクションのうち 2 つ以上が欠落しているか空の場合は、プレースホルダー TC を使用して進めるか、いったん中断して基盤となるセクションを先に完成させるか、ユーザーに直接質問してください。

[BLOCKING] セクション 15 の数量ゲート（準備状況ゲートの後に実行）：

TC を作成する前に、予定している TC 数がユースケースインベントリをカバーしていることを確認してください。

確認項目	必要数	予定数	状態
CRUD／コア TC	インベントリ内の書き込み操作数 (N) 以上	{n}	PASS/FAIL
読み取り／表示 TC	フィルター付き読み取り操作数 (M) 以上	{n}	PASS/FAIL
イベント／バックグラウンド TC	イベント駆動 (K) + バックグラウンド (J) 以上	{n}	PASS/FAIL
権限 TC	アクター数 × 2 以上	{n}	PASS/FAIL
合計	総数 (N+M+K+J) 以上	{n}	PASS/FAIL

いずれかの行が FAIL になる場合、または予定数が総数を下回る場合は、TC の生成を操作グループごとのバッチ（タスク追跡あたり 20 操作以下）に分割してください。すべてのバッチタスクが計画され、合計が総数以上になるまで、TC を作成しないでください。

[REQUIRED] TC ID の重複防止：

grep -n "TC-{FEATURE}-" docs/business-features/{Module}/detailed-features/README.*.md 2>/dev/null | sort | tail -10

新しい ID を割り当てる前に、既存の最も大きい ID を確認してください。範囲のルールについては .claude/skills/shared/tc-format.md の「Decade-Based Numbering」を参照してください。

［必須］ドキュメントネットワークの手順（INIT モード — 挿入、UPDATE モード — 検証）：

INIT モード： INIT を完了する前に、機能ドキュメントに ## Related Documentation セクションを挿入してください。 フロントマターの直後（セクション 1 の内容より前）に配置します。 注：この手順は INIT ワークフローの後半に実行されます。保存する前に、ドキュメントの先頭にさかのぼって挿入してください。

UPDATE モード： このセクションがすでに存在する場合は、再度挿入しないでください。代わりに、リンクが最新であること（パスが現在のモジュール構成と一致し、参照切れがないこと）を確認してください。古いドキュメントでこのセクションが見つからない場合は、追加してください。

## Related Documentation

| Type              | Path                                                         | Description                                              |
| ----------------- | ------------------------------------------------------------ | -------------------------------------------------------- |
| Engineering Spec  | `docs/specs/{app-bucket}/{system-name}/`                     | 技術に依存しない仕様書一式（$spec-discovery で作成）   |
| QA Test Dashboard | `docs/specs/README.md` + `docs/specs/PRIORITY-INDEX.md`      | すべての TC、実行状況、統合テストのトレーサビリティ |
| Integration Tests | `src/Services/{ServiceName}/{ServiceName}.IntegrationTests/` | テストコード。[Trait("TestSpec", "TC-...")] でリンク |
| Parent Feature    | _(if sub-feature)_                                           |                                                          |
| Child Features    | _(if this doc is a parent)_                                  |                                                          |

現在のモジュールコンテキストに基づいて、{app-bucket}、{system-name}、{Module}、{ServiceName} を入力してください。 まだ存在しないパスには (not yet created) を使用してください。これはナビゲーション用の意図マーカーとして機能します。

理由： このセクションは、この機能領域に関わるすべての利用者のためのナビゲーションハブです。 これがないと、関連成果物を見つけるために、AI セッションごとに docs ツリー全体を調べる必要があります。

---

モード：AUDIT（陳腐化の検出）

監査モードが実行された場合：

1. docs/business-features/{Module}/detailed-features/README.{Feature}.md のフロントマターから last_updated を読み取ります

2. git log --since="{last_updated}" --name-only -- src/Services/{Module}/ を実行します

3. 変更されたファイルが見つかった場合は、フェーズ 1.5 の影響マッピング表を使って該当セクションにフラグを立てます

4. docs/business-features/{Module}/AUDIT-{date}.md を出力します：

   # 機能ドキュメントの監査 — {date}
   
   ## {FeatureName}
   
   | セクション                 | ステータス | 変更されたソースファイル        | 対応              |
   | -------------------------- | ---------- | ------------------------------- | ----------------- |
   | セクション 5（ドメインモデル） | ⚠️ 要更新   | EntityX.cs（2026-04-18 に変更） | エンティティを再抽出 |
   | セクション 6（ビジネスルール） | ✅ 最新     | —                               | —                   |
   

---

フェーズ 1：モジュールの検出とコンテキストの収集

ステップ 1.0：Git の変更からモジュールを自動検出する（デフォルト）

モジュールが指定されていない場合、Git の変更から自動検出します。

1. git diff --name-only HEAD（ステージ済み＋未ステージの変更）。変更がない場合は → git diff --name-only HEAD~1
2. Module Mapping テーブルを使って一意なモジュール名を抽出します
3. 各モジュールについて、docs/business-features/{Module}/ が存在するか確認します
4. ドキュメントが存在する場合 → フェーズ 1.5（更新モード）。存在しない場合 → スキップします（ユーザーからの依頼がない限り、スクラッチ作成は行いません）
5. .claude/、docs/、設定ファイルのみが変更された場合 → 「影響を受けるビジネス機能ドキュメントはありません」と報告して終了します

パスからモジュールを検出するルール：

コードベースを検索して、パスとモジュールのマッピングを作成します。一般的なパターンは次のとおりです。

変更されたファイルパスのパターン	検出されるモジュール
src/Services/{Module}/**	{Module}
{frontend-apps-dir}/{app-name}/**	{Module}（アプリ名をモジュールにマッピング）
{frontend-libs-dir}/{domain-lib}/src/{feature}/**	{Module}（機能をモジュールにマッピング）

次を調べて、プロジェクト固有のマッピングを作成します。

ls -d src/Services/*/
ls -d {frontend-apps-dir}/*/

ステップ 1.1：対象モジュールを特定する

モジュールの優先順位：（1）ユーザー指定 →（2）ドメインから推定（grep で確認）→（3）Git diff から自動検出（ステップ 1.0）

ステップ 1.2：既存のドキュメントを読む

1. docs/BUSINESS-FEATURES.md（マスターインデックス）
2. docs/business-features/{Module}/INDEX.md（存在する場合）
3. docs/business-features/{Module}/README.md（存在する場合）

ステップ 1.3：コードベースを分析する

ソースコードから grep で根拠を確認します。

• エンティティ：{Module}.Domain/Entities/
• コマンド：{Module}.Application/UseCaseCommands/
• クエリ：{Module}.Application/UseCaseQueries/
• コントローラー：{Module}.Service/Controllers/
• フロントエンド：{frontend-apps-dir}/{app}/ または {frontend-libs-dir}/{lib}/

ステップ 1.4：機能を分析する

.ai/workspace/analysis/[feature-name].md にナレッジモデルを作成します。エンティティ／列挙型、コマンド／クエリ／イベント／ジョブ、コントローラー／DTO、フロントエンドコンポーネント、サービス間のバスメッセージを特定します。

---

フェーズ 1.5：更新モード（既存ドキュメントを更新する場合）

既存の機能ドキュメントを更新する場合（スクラッチから作成する場合を除く）：

ステップ 1.5.0：エンジニアリング仕様を同期する（docs/specs/{app-bucket}/{system-name}/ が存在する場合）

1. docs/specs/{app-bucket}/{system-name}/ が存在するか確認します
2. 存在する場合：Git diff と仕様レジストリから、重複するモジュールを記録します
3. 出力に「エンジニアリング仕様の同期が必要なモジュール：{list}」と記載します。関心の分離のため、spec-discovery は直接起動しないでください

ステップ 1.5.1：差分を分析する

1. ソースを特定します（Git diff、ブランチ、コミット）
2. 変更を分類します：エンティティ、コマンド、クエリ、フロントエンド、i18n
3. 各変更を影響するセクションに対応付けます（下表）

ステップ 1.5.2：セクションへの影響を対応付ける

変更の種類	影響するセクション
新しいエンティティプロパティ	4（ビジネス要件）、5（ドメインモデル）、11（API リファレンス）
新しい API エンドポイント	11（API リファレンス）、13（セキュリティと権限）
新しいフロントエンドコンポーネント	10（UI ページ）
新しいフィルター／クエリ	4（ビジネス要件）、11（API リファレンス）
新しい機能全般	15（テスト仕様） — 必須
変更全般	3（エグゼクティブサマリー）、17（バージョン履歴）— 常に更新

ステップ 1.5.3：必須のテストカバレッジ（セクション 15）

重要：新しい機能を文書化する際は、必ず以下を更新してください。

• セクション 15（テスト仕様）：新機能のテストケース（TC-{FEATURE}-{NNN}）を追加します。

[BLOCKING] TC の形式： .claude/skills/shared/tc-format.md の標準形式を使用してください。省略したフラットな GIVEN/WHEN/THEN は絶対に使用せず、必須フィールド（Objective、Preconditions、GWT steps、Acceptance Criteria、Test Data、Edge Cases、Evidence、IntegrationTest、Status）をすべて含む完全なテンプレートを使用してください。セクション 15 の所有者は $tdd-spec のみです。feature-docs がセクション 15 を作成するのは INIT 時のみです。UPDATE モードでは、既存の TC を上書きしてはなりません。

[BLOCKING] TC ID の重複防止： 新しい TC ID を割り当てる前に、既存の最大 ID を確認してください。

grep -n "TC-{FEATURE}-" docs/business-features/{Module}/detailed-features/README.*.md | sort | tail -5

次の連番を割り当ててください。範囲のルールについては .claude/skills/shared/tc-format.md の Decade-Based Numbering セクションを参照してください。

セクション 15 を更新しない場合、品質上のブロッキング問題となります。

ステップ 1.5.4：CHANGELOG エントリ

Keep a Changelog 形式に従い、必ず [Unreleased] の下に CHANGELOG.md のエントリを作成または更新してください。

---

フェーズ 2：ドキュメントの生成

docs/business-features/{Module}/detailed-features/README.{FeatureName}.md に生成します。

主な形式の例

ビジネス要件（FR-XX）：

#### FR-{MOD}-01: {Requirement Title}

| Aspect          | Details                                |
| --------------- | -------------------------------------- |
| **Description** | {What this requirement enables}        |
| **Scope**       | {Who can use / affected entities}      |
| **Evidence**    | `[Source: {namespace}/{service}/{id}]` |

ユーザーストーリー（US-XX）：

#### US-{MOD}-01: {Story Title}

**As a** {role}
**I want** {goal/desire}
**So that** {benefit/value}

**Acceptance Criteria**:

- [ ] AC-01: {Criterion with evidence reference}
- [ ] AC-02: {Criterion with evidence reference}

**Related Requirements**: FR-{MOD}-01, FR-{MOD}-02
**Evidence**: `[Source: {namespace}/{service}/{id}]`

テスト概要テーブル（必須）：

| Category    | P0 (Critical) | P1 (High) | P2 (Medium) | P3 (Low) |  Total  |
| ----------- | :-----------: | :-------: | :---------: | :------: | :-----: |
| {Category1} |      {N}      |    {N}    |     {N}     |   {N}    |   {N}   |
| **Total**   |    **{N}**    |  **{N}**  |   **{N}**   | **{N}**  | **{N}** |

テストケースの形式（TC-XX）：

[BLOCKING] 標準 TC 形式の参照元： .claude/skills/shared/tc-format.md — 完全な TC テンプレートには必ずこちらを使用してください。以下は、機能ドキュメントのセクション 15 で最低限必要な形式です。

#### TC-{FEATURE}-001: {Test Name} [P0]

**Objective:** {One sentence: what behavior this TC verifies}

**Preconditions:**

- {Required system state}

**GIVEN** {initial context}
**WHEN** {action performed}
**THEN** {expected outcome}

**Acceptance Criteria:**

- Success: {observable outcome}
- Failure: {error condition + message}

**Test Data:** `{ "field": "value" }`

**Edge Cases:**

- {Invalid scenario} → {Expected error/behavior}

**Evidence:** `[Source: {namespace}/{service}/{id}]`
**IntegrationTest:** `{TestFile}::{MethodName}` (or `Untested`)
**Status:** Tested | Untested | Planned

トラブルシューティングの形式：

#### {Issue Title}

**Symptoms**: {Observable problem}

**Causes**:

1. {Cause 1}
2. {Cause 2}

**Resolution**:

- {Step 1}
- {Step 2}

権限マトリクス：

| Role  | View | Create | Edit | Delete | Special     |
| ----- | :--: | :----: | :--: | :----: | ----------- |
| Admin |  ✅  |   ✅   |  ✅  |   ✅   | Full access |

ドメインモデル ERD（セクション 5 で必須）

すべての機能ドキュメントのセクション 5 に Mermaid の erDiagram を含めてください。

erDiagram
    {EntityA} {
        string id PK
        string name
        string status
    }
    {EntityB} {
        string id PK
        string entityAId FK
    }
    {EntityA} ||--o{ {EntityB} : "contains"

ERD のルール（spec-discovery 標準と同じ）：

• 技術に依存しない型のみを使用します：string、number、boolean、date、list、map
• C# のクラス名や ORM の型は使用しません
• 集約ルートを明記します：%% [AGGREGATE: EntityName]
• モジュール間のスタブを明記します：%% [CROSS-REF: module-name]

ERD ブロックの後に、抽象アンカー [Source: component/{service}/{Entity}] が必要です。

ビジネスルール（セクション 6）の形式：

各ルールグループには [Source: rule/{service}/{RuleName}] を必ず含めてください。

### BR-{MOD}-01: {Rule Group Name}

| Field/Operation | Rule         | Error Condition | Error Message      |
| --------------- | ------------ | --------------- | ------------------ |
| {field}         | {constraint} | {when violated} | {message constant} |

[Source: rule/{service}/{RuleName}]

---

注：AI Companion ファイルは非推奨

.ai.md のコンパニオンファイルはありません。出力するのは README.{Feature}.md のみです。テンプレートは docs/templates/detailed-feature-docs-template.md です（正式な参照元）。

主な原則（v4.0）

• セクション 1〜14、16 にはコードの詳細を記載しません。ファイルパス、C# の型、API の形状は含めません。
• 根拠を記載するのはセクション 15 のみです。[Source: namespace/service/id] の抽象アンカー参照を使用します。
• コマンドから BR-XXX を必ず相互参照します。各コマンドには、検証対象のビジネスルールを記載します。
• ドキュメントは最大 1500 行（目標は 500〜800 行）です。上限に近づいた場合は、サブ機能に分割します。
  1. README.{FeatureName}-Part1.md と README.{FeatureName}-Part2.md を作成します。
  2. ドメインモデル（S5）とビジネスルール（S6）は Part1 に残し、副次的な操作やエッジケースは Part2 に移します。
  3. TC ID の連続性を維持します。両方のパートで TC-{FEATURE}- プレフィックスを共有し、番号を振り直してはなりません。
  4. 相互参照を追加します。各パートのヘッダーに「関連項目： README.{FeatureName}-Part{N}.md」を含めます。
  5. INDEX.md と BUSINESS-FEATURES.md を更新し、両方のパートへのリンクを追加します。
• YAML frontmatter が必要です：module、service、feature_code、entities[]、status、last_updated
• Audit モードでは AUDIT-{date}.md を生成します。既存のドキュメントは変更しません。
• Init モードでは spec-discovery の抽出フェーズを使用します。すべてのエンティティ、ルール、API をソースから読み取ってから記述してください。

フェーズ 3：マスターインデックスの更新

モジュールのドキュメントを作成または更新した後、docs/BUSINESS-FEATURES.md を更新します。

1. 現在の内容を確認します
2. 「詳細なモジュールドキュメント」テーブルにモジュールが記載されていることを確認します
3. リンクがない場合は追加します。

   | **{Module}** | [Description] | [View Details](./business-features/{Module}/README.md) |
   

ステップ 3.5：モジュールの CHANGELOG.md を更新

feature-docs を実行するたび（init または update）、docs/business-features/{Module}/CHANGELOG.md に追記します。

## [Unreleased] — {date}

### Updated

- {FeatureName}: updated sections {list of section numbers} — triggered by {git ref or user request}
- Reason: {brief description of change}

存在しない場合は、docs/business-features/{Module}/CHANGELOG.md を作成します。

---

ハルシネーション防止プロトコル

DOCUMENTATION_ACCURACY_CHECKPOINT

ドキュメントを作成する前に、以下を確認します。

• これを実装している実際のコードを読みましたか？
• 行番号の参照は正確で最新ですか？
• 根拠となるコードスニペットを確認できますか？

テストケースの根拠の検証

すべてのテストケースについて：

1. 記載された行番号にある根拠ファイルを読みます
2. 検証します：その行のコードはテストのアサーションを裏付けていますか？
3. エッジケースを確認します：ErrorMessage.cs でエラー定数を探します
4. 行番号が間違っている場合は、すぐに修正します

---

フェーズ 3.5：検証（4 回のパス）

第 1 パス — テストケースの根拠の監査（セクション 15）

すべてのテストケースについて：

1. 記載された行番号にある根拠ファイルを読みます
2. 検証します：その行のコードはテストのアサーションを裏付けていますか？
3. エッジケースを確認します：ErrorMessage.cs でエラー定数を探します
4. 行番号が間違っている場合は、すぐに修正します

第 2 パス — ドメインモデルの検証

• セクション 5 で参照されている各エンティティファイルを読みます
• プロパティ名と業務上の意味が正確であることを確認します（実装上の型は使わず、業務上の意味の列を使用します）
• 列挙型の値が実際のソースに存在することを確認します
• ソースにないプロパティの記述を削除します

第 3 パス — 相互参照の監査

• 17 のセクションが正しい順序で存在する
• テスト概要の件数がセクション 15 の実際の TC 数と一致している
• すべての内部リンクが機能する
• テンプレートのプレースホルダー（{namespace}、{service}、{id}）が残っていない
• ErrorMessage の定数がエッジケースのメッセージと一致している
• YAML フロントマターが存在し、完全である

重要：いずれかのパスでハルシネーションを含む内容が見つかった場合は、再調査して修正してから完了してください。

第 4 パス — AI による実装可能性の確認

実装上の仮定が必要な項目に印を付けます。

• S4（機能要件）： すべての FR-XX に、明示的な成功時と失敗時の結果が必要です。曖昧な FR → 不完全。
• S6（業務ルール）： すべての BR-XX に、トリガー条件、ルールの内容、エラーメッセージ、[Source: rule/{service}/{RuleName}] が必要です。項目が欠けている → 要確認。
• S8（コマンド／操作）： すべてのコマンドが、検証済みの BR-XX を 1 つ以上参照している必要があります。BR の参照がないコマンド → 要確認。
• S13（認可）： ロール × アクション × 条件の各セルが明示された権限マトリックスが必要です。空白セル → 要確認。
• 具体例： 中核となる操作ごとに、例（入力 + 期待される出力）が 1 つ以上必要です。抽象的な内容のみ → 低評価。

不完全な項目が 3 件を超える場合は、作業を中断し、完了前にユーザーへ直接質問して不足項目の一覧を提示します。

参照：docs/project-reference/spec-principles.md セクション 4（AI による実装可能性チェックリスト）。

M5 — ゼロからの再構築テスト

.claude/skills/shared/sdd-artifact-contract.md → 「AI-SDD Mandates (M1-M6)」で、作業をブロックする基準を確認してください。完了前に、ドキュメント全体について次の問いに答えます。

このコードベースについて何も知らないチームが、[Source:] の根拠を除いた §1-14 の文章だけを使って、あらゆるスタックで同一の業務動作を再実装できますか？

文章がフレームワーク／製品／言語に依存する表現、クラスまたはファイルへの参照、あるいは単一の隠れた解釈に依存していて「いいえ」となる場合、このドキュメントは M5 に不合格です（M1／M2／M4 にも不合格となる可能性が高いです）。完了とする前に、該当するセクションを技術に依存せず、解釈が一意となる業務動作の記述に書き直してください。

---

品質チェックリスト

マンデートへの準拠（M1-M6）

ブロッキング基準については、.claude/skills/shared/sdd-artifact-contract.md →「AI-SDD Mandates (M1-M6)」を参照してください。

• マンデート品質チェック： §1-14 の本文に禁止された技術用語（spec-principles.md §3.2）が一切含まれておらず、証拠キャリア（M1/M2）以外にコード識別子（クラス名／メソッド名、ファイルパス、名前空間）が含まれていない
• すべての FR / BR / 操作に論理 ID（FR-/BR-/OP-/TC-）と、それとは別の [Source: namespace/service/id] 形式の抽象アンカー証拠キャリアが付いている（物理的な file:line / src/ は不可）。[Source:] は本文に織り込まず、そのまま保持する（M3）
• すべての要件が、解釈が一意で、成功／失敗の結果が明記されており、テスト可能である（M4）
• ゼロからの再構築テストへの回答が「YES」である — §1-14 の本文のみをもとに、あらゆるスタックで文書を再実装できる（M5）

構成

• ドキュメントが正しいフォルダー構成に配置されている
• README.md がテンプレート形式（17 セクション）に従っている
• YAML フロントマターに module、service、feature_code、entities[] が含まれている
• ナビゲーションリンクを含む INDEX.md が作成されている
• マスターインデックス（BUSINESS-FEATURES.md）が更新されている
• ステークホルダー向けナビゲーションテーブルがある
• [Unreleased] の下にエントリーを追加して CHANGELOG.md が更新されている
• 合計 1500 行以内（上限に近づく場合は「Key Principles」の分割手順に従う）
• セクション 1-14、16 にコードの詳細が含まれていない（ファイルパス、C# 型などは不可）
• コマンドが、検証対象の BR-XXX ID を参照している

テストケースの証拠（必須）

• すべてのテストケースに Evidence フィールドがあり、 [Source: namespace/service/id] 形式の抽象アンカーが記載されている（file:line は不可）
• テンプレートのプレースホルダー（{namespace}、{service}、{id}）が残っていない
• 行番号が実際のソースファイルを読んで確認されている
• エッジケースのエラーが ErrorMessage.cs の定数と一致している
• テストサマリーの件数がセクション 15 の実際のテストケース数と一致している

ハルシネーション対策

• すべてのエンティティプロパティがソースコードと照合されている
• すべての列挙値が実際の列挙型定義と照合されている
• 存在しないメソッド、プロパティ、モデルが記載されていない
• すべてのコードスニペットが実際のファイルからコピーされている

セクション 5（ドメインモデル）

• すべてのエンティティを含む Mermaid erDiagram がある
• ERD では技術に依存しない型のみを使用している
• 各エンティティ定義の後、および ERD ブロックの後に [Source: component/{service}/{Entity}] 形式の抽象アンカーがある
• 集約ルートに %% [AGGREGATE: ...] が付いている

セクション 6（ビジネスルール）

• 各ルールグループのテーブルの後に [Source: rule/{service}/{RuleName}] 形式の抽象アンカーがある
• エラーメッセージが ErrorMessage.cs または同等の定数ファイルと照合されている

初期化モードのチェックリスト

• ERD の生成前にフェーズ A の抽出が完了している
• セクション 6 の記述前にフェーズ B の抽出が完了している
• セクション 8 および 11 の記述前にフェーズ C の抽出が完了している
• セクション 9 の記述前にフェーズ D の抽出が完了している
• セクション 10 および 15 の記述前にフェーズ E の抽出が完了している
• モジュール用の CHANGELOG.md が作成されている

完全性ゲート（初期化モード）

• [C-gate] フェーズ C のエントリー数 ≥ ユースケースインベントリー（Step 1-INIT.1.5）の合計
• [E-gate] フェーズ E のジャーニー数 ≥ フェーズ C のエントリー数
• [Actor-gate] アクターカタログ内のすべてのアクターが、1 つ以上のフェーズ E のジャーニーに登場する
• [TC-gate] セクション 15 の TC 数 ≥ ユースケースインベントリーの合計
• [Source-gate] すべてのフェーズ C のエントリーとフェーズ E のジャーニーに [Source: namespace/service/id] 形式の抽象アンカーがある

関連項目

• documentation
• feature-implementation

---

ワークフローの推奨

必須・重要・必ず注意してください — 例外はありません： すでにワークフローを実行中でない場合は、必ず直接ユーザーに質問して確認してください。タスクの複雑さを判断したり、「省略できるほど簡単」と決めつけたりしないでください。ワークフローを使うかどうかを決めるのは、あなたではなくユーザーです：

1. tdd-feature ワークフローを開始する（推奨） — scout → investigate → domain-analysis → tdd-spec → tdd-spec-review → plan → plan-review → plan-validate → why-review → cook → review-domain-entities → integration-test → integration-test-review → integration-test-verify → test → workflow-review-changes → sre-review → changelog → docs-update → watzup → workflow-end
2. $feature-docs を直接実行する — このスキルを単独で実行する

---

次のステップ

［ブロッキング］ 完了後、選択肢を提示するために直接ユーザーに質問してください。省略しないでください。決めるのはユーザーです：

• 「$tdd-spec（推奨）」 — ドキュメント化された機能のテスト仕様を生成／更新する
• 「$tdd-spec [direction=sync]」 — テスト仕様をダッシュボードに同期する
• 「スキップして手動で続行」 — ユーザーが決定する

---

関連スキル

スキル	関係	呼び出すタイミング
$spec-discovery	生成元 — このスキルの INIT モードに渡すエンジニアリング仕様バンドルを抽出します	初めてドキュメントを作成する場合は、先に spec-discovery を実行します。その出力を Section 12 のソースとして使用します
$tdd-spec	利用側 — Section 15 を読み取り、TC を生成／検証します	機能ドキュメントの作成／更新後に tdd-spec を呼び出し、Section 15 を作成またはレビューします
$tdd-spec-review	レビュー担当 — Section 15 の TC カバレッジを監査します	tdd-spec の後に呼び出し、TC の網羅性と GIVEN/WHEN/THEN の品質を検証します
$tdd-spec [direction=sync]	ダッシュボード — Section 15 から docs/specs/README.md と docs/specs/PRIORITY-INDEX.md を同期します	tdd-spec の更新後に呼び出し、QA ダッシュボードを最新の状態に保ちます
$integration-test	最終利用側 — Section 15 の TC からテストコードを生成します	tdd-spec の後に呼び出し、実際の統合テストファイルを作成します
$docs-update	オーケストレーター — Phase 2 としてこのスキルを呼び出します	チェーン全体の同期には $docs-update を実行します。内部で $feature-docs を呼び出します
$review-changes	トリガー — 機能ドキュメントの古さを検出します	ビジネスドキュメントがコード変更に対して古くなっている場合、$docs-update を呼び出します

単独実行時のチェーン

ワークフロー外から呼び出された場合、仕様のすべてのレイヤーを同期させるため、このチェーンに従ってください。 同じセッション内ですでに完了したステップはスキップしてください。

feature-docs (you are here)
  │
  ├─ BEFORE this skill (if doc doesn't exist yet):
  │    [REQUIRED] → $spec-discovery [init mode]
  │          Extracts engineering spec bundle. Provides basis for Sections 1-14 accuracy.
  │          Skip if: feature docs updating existing content, or small feature with no domain model.
  │
  ├─ AFTER this skill:
  │
  ├─ [REQUIRED] → $tdd-spec [CREATE or UPDATE mode]
  │     Section 15 is incomplete without explicit tdd-spec run.
  │     CREATE: new feature doc just created → write TCs from spec.
  │     UPDATE: existing doc updated → update TCs to match changed behavior.
  │
  ├─ [REQUIRED] → $tdd-spec-review
  │     Validates TC coverage, GIVEN/WHEN/THEN completeness, no duplicate TC codes.
  │
  ├─ [REQUIRED] → $tdd-spec [direction=sync]
  │     Syncs Section 15 TCs to QA dashboard indexes at docs/specs/README.md and docs/specs/PRIORITY-INDEX.md.
  │
  ├─ [RECOMMENDED] → $integration-test [from-changes or from-prompt mode]
  │     Generates/updates integration test files from changed TCs.
  │
  └─ [RECOMMENDED] → $docs-update
        If code changes triggered this doc update, run $docs-update for full chain including
        spec-discovery (Phase 2.5) and tdd-spec (Phase 3).

ドキュメントネットワークの原則

［必須］ このスキルが管理するすべての機能ドキュメントには、## Related Documentation セクションが必要です：

INIT モード： このセクションを挿入します（frontmatter の直後、Section 1 の内容の前に配置） UPDATE モード： セクションが存在し、リンクが最新であることを確認します。古いドキュメントにない場合は追加します

すでに存在する場合は再追加しないでください。このスキルの完了を報告する前に確認してください。

docs/business-features/{Module}/README.md に挿入または確認するテンプレート：

## Related Documentation

| Type              | Link                                                                                                          | Description                                                    |
| ----------------- | ------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
| Engineering Spec  | [docs/specs/{app-bucket}/{system-name}/](../../specs/{app-bucket}/{system-name}/)                             | Tech-agnostic spec bundle (domain model, rules, API contracts) |
| QA Test Dashboard | [docs/specs/README.md](../../specs/README.md) + [docs/specs/PRIORITY-INDEX.md](../../specs/PRIORITY-INDEX.md) | All TCs, execution status, integration test links              |
| Integration Tests | `src/Services/{ServiceName}/{ServiceName}.IntegrationTests/`                                                  | Test code linked to TCs via [Trait("TestSpec", "TC-...")]      |
| Related Modules   | _(list any cross-module dependencies here)_                                                                   |                                                                |

コンテキストに基づいて {app-bucket}、{system-name}、{Module}、{ServiceName} を埋めてください。 docs/specs/{app-bucket}/{system-name}/ がまだ存在しない場合は、次のように記述してください：(仕様バンドルはまだ作成されていません — $spec-discovery init を実行してください)。

このセクションでは、次のことが可能になります。

• ビジネスドキュメント → エンジニアリングの詳細 → テストエビデンスをたどる人間向けのナビゲーション
• 仕様バンドルは更新されたがビジネスドキュメントは更新されていない場合に $docs-update が検出すること
• すべてをスキャンしなくても、何が存在するかを今後の AI セッションが把握できること

[IMPORTANT] 作業を始める前に、タスク追跡を使ってすべての作業を小さなタスクに分割してください。各ファイルを読むタスクも含めてください。これにより、長いファイルによるコンテキストの喪失を防げます。単純なタスクの場合、AI はスキップしてよいかどうかをユーザーに必ず確認しなければなりません。

サービス間チェック — マイクロサービス／イベント駆動型の場合、調査、計画、仕様、機能ドキュメントを完了する前に必ず実施してください。下流のコンシューマーの見落としは、気づかれないリグレッションにつながります。

境界	検索語
イベントの発行元	Publish、Dispatch、Send、emit、EventBus、outbox、IntegrationEvent
イベントのコンシューマー	Consumer、EventHandler、Subscribe、@EventListener、inbox
Saga／オーケストレーション	Saga、ProcessManager、Choreography、Workflow、Orchestrator
同期サービス呼び出し	他のサービスとの間の HTTP／gRPC 呼び出し
共有コントラクト	OpenAPI 仕様、proto、共有 DTO — 破壊的変更があれば明示してください
データの所有権	他のサービスが同じテーブル／コレクションを読み書きしている → 共有 DB のアンチパターン

接点ごとに: 所有サービス · メッセージ名 · コンシューマー · リスク（NONE / ADDITIVE / BREAKING）。

次の項目が完了するまで作業をブロックしてください: 発行元のスキャン · コンシューマーのスキャン · Saga の確認 · コントラクトのレビュー · 破壊的変更リスクの明示

エビデンスに基づく推論 — 推測は禁止です。すべての主張に証拠が必要です。

1. すべての主張について、file:line、grep の結果、またはフレームワークのドキュメントを引用してください
2. 確信度を明示してください：>80% なら自由に対応、60-80% なら先に検証、<60% なら推奨しないでください
3. アーキテクチャ変更には、サービス間の検証が必要です
4. 「十分な証拠がありません」は妥当であり、期待される出力です

次の項目が完了するまで作業をブロックしてください: - [ ] エビデンスのファイルパス（file:line） - [ ] grep 検索の実施 - [ ] 類似パターンを 3 件以上確認 - [ ] 確信度を明示

証拠なしでの使用は禁止: 「明らかに」、「私はこう思います」、「〜のはずです」、「おそらく」、「これは〜が原因です」 未完了の場合 → 次を出力してください："Insufficient evidence. Verified: [...]. Not verified: [...]."

批判的思考の姿勢 — 批判的思考と逐次的思考を適用してください。すべての主張には追跡可能な証拠が必要であり、対応するには確信度が >80% でなければなりません。 ハルシネーション対策: 推測を事実として提示しないでください。すべての主張の出典を示し、不確実性を率直に認め、出力に誤りがないか自己確認し、独立して相互参照し、自分の確信度にも懐疑的でいてください。証拠のない確信こそが、あらゆるハルシネーションの根本原因です。

AI のミス防止 — すべてのタスクで避けるべき失敗パターン：

削除する前に、依存先の参照を確認してください。 コンポーネントを削除すると、ドキュメントやコードに古さが連鎖的に広がります。削除する前に、参照しているファイルをすべて特定してください。 AI 生成コンテンツは実際のコードと照合してください。 AI は API、クラス名、メソッドのシグネチャを幻覚します。ドキュメントに記載したり参照したりする前に、必ず grep して存在を確認してください。 編集後は依存関係を最初から最後まで追跡してください。 定義を変更しただけでは、そこから派生する下流の変数や利用箇所を見落とします。必ず依存関係全体を追跡してください。 正しさを検証する際は、すべてのコードパスを追跡してください。 コードが存在することを確認しても、実行されることの確認にはなりません。正常系だけでなく、早期終了、エラー分岐、条件によるスキップも必ず追跡してください。 デバッグする際は、修正前に「どちらの責任か」を確認してください。 バグが呼び出し元（誤ったデータ）にあるのか、呼び出し先（誤った処理）にあるのかを追跡してください。責任のある層で修正し、症状が現れた箇所には決してパッチを当てないでください。 既存の値には意図があると考え、変更前に理由を確認してください。 定数、上限、フラグ、パターンを変更する前に、コメントを読み、git blame を確認し、周辺のコードを調べてください。 最初の出力だけでなく、影響を受ける出力をすべて検証してください。 複数のスタックに関わる変更では、すべての出力を検証する必要があります。チェックが 1 つ成功しても、すべてのチェックが成功したことにはなりません。 包括的な視点を優先してデバッグし、目の前のことに注意を奪われないでください。 失敗を調査する際は、まず前提条件をすべて列挙してください（設定、環境変数、DB 名、エンドポイント、DI 登録、データの前提条件）。次に、コード層の仮説を立てる前に、それぞれを証拠に照らして検証してください。 変更は必要最小限にし、差分テストを適用してください。 バグ修正では、変更する各行がそのバグに直接関係している必要があります。隣接するコードのスタイル変更や改善はしないでください。機能強化のタスクでは、改善を実装し、その内容を明示してください。 コーディング前に曖昧さを明らかにし、黙って解釈を選ばないでください。 依頼に複数の解釈がある場合は、それぞれの工数見積もりを示して質問してください。全レコードを対象とする方法、ファイルベースの方法、より複雑な方法を想定して進めないでください。

重要・必ず注意 あらゆる主張について file:line 形式の証拠を示してください。確信度が 80% を超える場合のみ実行し、60% 未満の場合は推奨しないでください。

必ず注意 批判的思考を適用してください。すべての主張に追跡可能な証拠が必要です。確信度が 80% を超える場合のみ実行してください。幻覚を防ぐため、推測を事実として提示しないでください。

必ず注意 AI の誤りを防止してください。包括的な視点を優先したデバッグ、責任のある層での修正、コーディング前の曖昧さの明示、コンパクション後のファイルの再読を徹底してください。

終了前のリマインダー

• 重要・必ず注意［ブロッキング］ 作業を開始する前に、タスクを細分化してタスク追跡用のタスクにしてください。タスクリストなしで 1 行でも出力してはいけません。
• 重要・必ず注意［ブロッキング］ すべてのテストケースに検証可能なコードの証拠（FilePath:LineNumber）が必要です。例外はありません。
• 重要・必ず注意［ブロッキング］ 抽出を行う前に Use Case Enumeration（Step 1-INIT.1.5）を実行してください。最小 TC 数はこの一覧から導き出します。
• 重要・必ず注意［ブロッキング］ UPDATE モードでは、既存の TC を上書きしてはいけません。INIT 後の Section 15 は $tdd-spec が管理します。
• 重要・必ず注意［必須］ 17 個のセクションは、マスターテンプレートと順序まで完全に一致させてください。
• 重要・必ず注意［必須］ ドキュメントを変更した場合は、必ず CHANGELOG.md と Section 17（Version History）を更新してください。
• 重要・必ず注意［必須］ 新しいコードを作成する前に、コードベース内で類似パターンを 3 つ以上検索してください。
• 重要・必ず注意［必須］ 作業品質を検証するための最終レビュータスクを追加してください。

[TASK-PLANNING] 必ず注意：着手前にタスクの範囲を分析し、タスク追跡を通じて小さな TODO タスク／サブタスクに分割してください。

---

Hookless Prompt Protocol Mirror（自動同期）

ソース：.claude/hooks/lib/prompt-injections.cjs + .claude/.ck.json

[WORKFLOW-EXECUTION-PROTOCOL] [BLOCKING] ワークフロー実行プロトコル — 必須・重要・厳守。いかなる理由があっても省略しないでください。

汎用的な移植性の境界： 再利用可能なスキルとプロトコルのテキストはプロジェクトに依存しないものとします。プロジェクト固有の規約は、docs/project-config.json と docs/project-reference/ から確認してください。shared/sdd-artifact-contract.md の共通 AI-SDD を適用します。docs/project-config.json と docs/project-reference/docs-index-reference.md を読み、そこに記載されているプロジェクト参照ドキュメントを開いてください。この共通コンテキストとローカルドキュメントを利用できる場合は、サポートされている任意の AI ツールで実行できます。

1. 検出： プロンプトをワークフローカタログと照合します
2. 分析： 最適なワークフローを見つけ、カスタムのステップ構成のほうが適しているかどうかも評価します
3. 確認（必須形式）： ユーザーが明示的にワークフロー／スキルを呼び出し、かつローカルプロトコルで明示的な呼び出しを確認とみなす場合を除き、次の構成でユーザーに直接質問します
   • 質問："どのワークフローを有効にしますか？"
   • 選択肢 1："[最適なワークフロー] を有効にする（推奨）"
   • 選択肢 2："カスタムワークフローを有効にする：[step1 → step2 → ...]"（1 行で理由を記載）
4. 有効化（確認後）： 標準ワークフローの場合は $workflow-start <workflowId> を呼び出し、カスタムステップの場合は手動で順に実行します
5. タスクを作成： ワークフローのすべてのステップについてタスク追跡を行います
6. 実行： 各ステップを順番に実行します [CRITICAL-THINKING-MINDSET] 批判的思考と段階的思考を適用します。すべての主張には追跡可能な根拠が必要であり、確信度が 80% を超える場合にのみ行動します。 ハルシネーション防止の原則： 推測を事実として提示しないでください。すべての主張に出典を示し、不確実な点は率直に認め、出力に誤りがないか自己確認し、独立した情報源と照合し、自分の確信を疑ってください。根拠のない確信こそが、あらゆるハルシネーションの根本原因です。 AI の注意力に関する原則（初頭効果・新近効果）： 長いプロンプト／プロトコルでは、指示の順守が長いコンテキストウィンドウでも保たれるよう、最も重要な 3 つのルールを冒頭と末尾の両方に配置します。 目標主導の実行： まず成功基準を定義し、検証が完了するまで繰り返し、観察可能なチェックに合格した場合にのみ終了します。 テストで意図を検証： テストでは、現在の挙動をなぞるだけでなく、ビジネスルール／不変条件を保護し、保護対象の意図が損なわれた場合に失敗するようにします。

[LESSON-LEARNED-REMINDER] [BLOCKING] タスク計画と継続的改善 — 必須。省略しないでください。

作業を始める前に、作業を小さなタスクに分割し、タスク追跡を行います。最後のタスクとして「AI のミスと教訓を分析する」を追加します。

教訓の抽出 — 症状への対処ではなく、根本原因のみ：

1. 症状ではなく、失敗モード（推論／前提の誤り）を特定します。「誤った列挙値を使った」ではなく、「ソースを読まずに API が存在すると仮定した」とします。
2. 一般性を検証します。この失敗モードは 3 つ以上のコンテキスト／コードベースに当てはまりますか？ 当てはまらない場合は、抽象度を 1 段階上げます。
3. 普遍的なルールとして記述します。プロジェクト固有の名前／パス／クラスを除き、どのコードベースでも役立つ内容にします。
4. 統合します。同じ失敗モードを共有する複数のミスは、1 つの教訓にまとめます。
5. 再発判定：「この注意書きがなければ、今後のセッションで再発するか？」いいえの場合は $learn を省略します。
6. 自動修正判定：「$code-review／$code-simplifier／$security／$lint で検出できるか？」はいの場合は、代わりにレビュー用スキルを改善します。
7. 両方の判定を通過した場合： $learn を実行するようユーザーに依頼します。 [TASK-PLANNING] [MANDATORY] ワークフローまたはスキルのステップを実行する前に、予定されているすべてのステップのタスク追跡を作成／更新し、各ステップの開始時と完了時に内容を同期してください。