docs-update

Codex 互換性に関する注意：

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

Codex によるプロジェクト参照の読み込み（フックなし）

Codex では、実行時にプロジェクトドキュメントを挿入するのではなく、静的なプロジェクト参照を読み込みます。 コーディング、計画、デバッグ、テスト、レビューを行う際は、このルーティングに従ってプロジェクトドキュメントを明示的に開いてください。

必ず読むもの：

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

コンテキストが不足または古い場合のルート： docs/project-config.json、ドキュメントインデックス、lessons.md、CLAUDE.md、AGENTS.md、またはタスクに必要な参照ドキュメントが存在しない、あるいは古い場合は、通常のプロジェクト固有の作業に入る前に $project-init または範囲を絞ったセットアップルート（$project-config、$docs-init、$scan-all、$scan --target=<key>、$claude-md-init）を自動で実行してください。Codex ミラーまたは AGENTS.md が存在しない、あるいは古い場合は、ユーザーに $sync-codex を実行するよう依頼してください。自動で実行してはいけません。

状況に応じて読むドキュメント：

• プロジェクト構造、アーキテクチャ、技術スタック、デプロイ、セットアップ（バックエンド、フロントエンド、インフラのいずれのレイヤーでも）：project-structure-reference.md
• バックエンド、CQRS、API、ドメイン、エンティティの変更：backend-patterns-reference.md、domain-entities-reference.md
• フロントエンド、UI、スタイル、デザインシステム：frontend-patterns-reference.md、scss-styling-guide.md、design-system/README.md
• 仕様書の作成、docs/specs/ のパス、TC 形式：feature-spec-reference.md、spec-system-reference.md、spec-principles.md
• 動作やパブリックコントラクトの変更、または仕様書・テスト・コード間の同期：上記の仕様書関連ドキュメントに加え、workflow-spec-test-code-cycle-reference.md
• 派生仕様インデックス、ERD、再実装ガイド：spec-system-reference.md と docs/specs/ 内の元となる Feature Specs
• 統合テストの実装・レビュー：integration-test-reference.md
• E2E テストの実装・レビュー：e2e-test-reference.md
• コードレビューや監査：code-review-rules.md と、変更されたファイルに応じたドメイン関連ドキュメント

ドキュメントを一律にすべて読むことは避けてください。まず docs-index-reference.md を確認してから、関連するファイルだけを開いてください。

[BLOCKING] スキルの手順は定められた順序で実行してください。ユーザーが明示的に承認しない限り、手順の省略、並べ替え、統合は絶対に行わないでください。 [BLOCKING] 各手順またはサブスキルを呼び出す前に、タスクの追跡を更新してください。手順の開始時に in_progress、終了時に completed に設定してください。 [BLOCKING] 完了またはスキップした手順には、すべて簡潔な証拠または明示的なスキップ理由を記載してください。 [BLOCKING] Task ツールを利用できない場合は、同じステータス遷移を適用しながら、同等の手順別プランのトラッカーを作成して維持してください。

クイックサマリー

目標： コード変更の影響を受けるドキュメントを検出し、すべてのドキュメント種別にわたる更新を調整して、コード／仕様／テストの変更があれば必ずドキュメントとの整合性が保たれるようにします。影響を受けたプロジェクトリファレンスドキュメント、project-config.json のセクション、Feature Spec、§8 の TC、テストコードへのリンク、派生インデックスがすべてリリース済みの動作を反映し、未検出の乖離が残らないようにします。

概要：

• このスキルは作成者ではなくルーターです。Phase 0 のトリアージ（git diff → 分類 → モジュールの重複排除 → 既存ドキュメントの確認）から開始し、各ドキュメント種別の担当に委任します（派生技術ビューは $spec、$spec [mode=tests]、$spec [mode=sync]、$spec-index、$tech-spec）。§8、docs/specs/、派生技術仕様の内容を直接記述してはいけません。理由：二重に作成すると、仕様とインデックス／ビューが乖離します。
• 主な手順（各フェーズは影響の有無に応じて実施し、スキップしたフェーズは理由とともに completed と記録）： Phase 0 のトリアージ（git diff → 分類 → モジュールの重複排除 → 既存ドキュメントの状態を記録）→ Phase 1 のプロジェクトコンテキスト同期（impact-map → 影響を受けた docs/project-reference/** ドキュメント、docs/project-config.json のセクション、README.md を並列で検証）→ Phase 2 の $spec（§1～§7 の Feature Spec。機能の動作が変更されたのに Spec が存在しない場合は、ドキュメント先行で BLOCK）→ Phase 2.5 の $spec-index（派生バケット INDEX／ERD の更新。任意）→ Phase 2.6 の $tech-spec（派生技術ビューの更新／監査。技術ツリーに影響がある場合は任意）→ Phase 3 の $spec [mode=tests]（§8 の TC）→ Phase 4 の $spec [mode=sync]（§8 ↔ テストコード）→ Phase 5 のサマリーレポート → 最終レビュー（#8 で Step 2.4 のコード↔仕様の同期検証を実施）。
• ファイルに触れる前に、タスクトラッキングで 8 件すべてのタスクを作成します。固定されたフェーズ順 0 → 1 → 2 → 2.5/2.6 → 3 → 4 → 5 → final review に従います。早期終了は判断として行うものであり、黙って省略してはいけません。
• 最終確認（Step 2.4）はワークフローの最後のゲートです。変更対象の各モジュールについて、リリース済みコードと §3 の AC、§4 の BR、§8 の TC を照合します。[HARD] BR の削除や弱体化はコードと仕様の矛盾にあたるため、完了を BLOCK します。
• 出力は技術に依存しない文章とし（証拠フィールド以外でフレームワーク名／製品名を使用しない）、トレーサビリティを優先します（文章より先に FR-／BR-／OP-／TC- の論理 ID を更新）。監査証跡として、Phase 5 のサマリーレポートを必ず作成します。

オーケストレーションモデル：

git diff → Triage → Phase 1: Project Context Sync (PARALLEL, impact-scoped)
                  │            ├─ impacted docs/project-reference/** — verify → patch → (escalate to $scan --target=X)
                  │            ├─ impacted docs/project-config.json sections — verify → merge → validate
                  │            └─ README.md / project docs (docs-manager)
                  → Phase 2: $spec (business feature docs)
                  → Phase 2.5: $spec-index (derived index/ERD refresh) [optional]
                  → Phase 2.6: $tech-spec (derived technical view refresh/audit) [optional]
                  → Phase 3: $spec [mode=tests] (§8 test specifications)
                  → Phase 4: $spec [mode=sync] (§8 ↔ test code sync)
                  → Phase 5: Summary Report

主なルール：

• ルーターのみ — サブスキルのロジックを重複させたり、Section 8／docs/specs/ の内容を記述したりしないでください
• [BLOCKING] 鮮度の確認範囲は影響箇所に限定し、前提にしません。 Phase 1 では、差分によって実際に古くなる可能性のある docs/project-reference/** のドキュメントと docs/project-config.json のセクションのみを検証します（node .claude/scripts/doc-impact-map.cjs で振り分け）。各ドキュメントについて、判定結果 FRESH | PATCHED | RESCAN REQUIRED | UNVERIFIED を報告します。誰も確認していないドキュメントは UNVERIFIED であり、FRESH ではありません。— 理由：これらのドキュメントは後続のすべての AI コンテキストに注入されるため、古い記述がひそかに残っていると、以降のすべてのエージェントに、もはや存在しないコードベースを教えることになります。
• **[BLOCKING] 影響範囲に限定した検証では、に書き込んではいけません。** そのスタンプを更新できるのは、完全な `$scan --target=X` のみです。限定的な検証では、代わりに に書き込みます。ただし、すでに Last scanned スタンプがあるドキュメントに限ります（Step 1.6）。— 理由：Last scanned は60日ごとの完全再スキャンのゲート（.claude/hooks/lib/session-init-helpers.cjs:769）を制御します。部分的な確認でリセットすると、ドキュメント全体の劣化を検出するための仕組みそのものを無効にして、作業を速めることになります。
• [BLOCKING] PATCHED の docs/project-reference/**ドキュメントは、判定を確定する前に$prompt-enhance <doc>を実行する必要があります**（Step 1.3）。 AI にとって十分に有用な状態を保ちながら、ドキュメントをできる限り簡潔にします。スタンプ／カウントのみの編集の場合に限り、省略できます。
• Phase 1／docs-manager は、docs/specs/**、test-spec、spec-index／ERD、派生技術ビューのパスを担当してはいけません。
• 除外されたすべての成果物は、子スキル（$spec、$spec-index、または $tech-spec）専用として明示的に確保し、正規の書き手を1つにします。
• docs-manager のすべてのブリーフと書き込み対象から、docs/specs/** と生成された技術ビューを除外します。
• 各フェーズは、実行前に必要性を確認し、影響がないフェーズはスキップします
• ステップからスキルへの順序は固定です。フェーズを順番に実行し、順序を入れ替えてはいけません
• 更新の必要がなかった場合も含め、確認した内容を必ず報告します
• トリアージのコンテキスト（変更されたファイル、検出されたモジュール、影響を受けるセクション）を $ARGUMENTS 経由で各サブスキルに渡します
• モジュール一覧の重複排除に必ず注意します。同じモジュールへのバックエンドとフロントエンドの変更は、1つのエントリーとして扱います
• ステップの状態をリアルタイムで必ず追跡します。in_progress → 実行 → completed（またはスキップ理由付きの completed）
• .claude のスキル／フック／ワークフロー／同期ツールに変更がある場合は、生成されたミラーの同期状態（npm run codex:sync の完了、または明示的な N/A）を明記します。docs-update はこの確認を振り分けて報告しますが、生成されたミラーを直接編集しません。
• [BLOCKING] 技術に依存しない出力： spec／specs／README／INDEX を更新するとき、本文や見出しにフレームワーク／製品／言語／デザインパターンの名前を追加してはいけません。証拠フィールドの例外（**Evidence**、CoveredBy、レガシーの IntegrationTest、[Source:]、frontmatter、Mermaid）は維持します。根拠：docs/project-reference/spec-principles.md §3。
• [BLOCKING] M3 トレーサビリティ更新： BLOCKING の基準については、.claude/skills/shared/sdd-artifact-contract.md → "AI-SDD Mandates (M1-M7)" を参照してください。コード変更後にドキュメントを同期する場合、論理 ID のマッピング（FR-／BR-／OP-／TC-）を先に更新し、その後で本文を更新します。[Source: namespace/service/id] の抽象アンカーを再解決するのは、論理成果物の名前が変更された、または分割された場合のみです。ファイルの移動やスタックの変更ではアンカーは変わりません（物理座標はプロベナンスのサイドカーにのみ記録されます）。また、変更後も論理 ID の背骨を維持します。コードの移動を理由に論理 ID を削除したり、番号を振り直したりしてはいけません。同期する本文はすべて M1／M2 に準拠させます。

懐疑的に検討してください。批判的思考と段階的思考を適用してください。すべての主張について追跡可能な証拠を確保し、確信度を80％超にしてください。

---

必須タスクの作成（許容ゼロ）

[BLOCKING] ファイルに触れる前に、タスク追跡を使って8つすべてのタスクを作成してください。統合、改名、省略は絶対にしないでください。条件付きタスクをスキップする場合は、理由を添えて直ちに completed とし、黙って省略してはいけません。 | # | タスクの内容 | 条件付き？ | | --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | | 1 | [docs-update] Phase 0 — トリアージ：git diff を収集し、ファイルを分類して、モジュールを検出し、既存のドキュメントを確認 | いいえ — 常に最初に実行 | | 2 | [docs-update] Phase 1 — プロジェクトコンテキストの同期：impact-map → 影響を受ける docs/project-reference/** + docs/project-config.json のセクション + README/プロジェクトドキュメントを並列で検証 | いいえ — 常に実行。ただし、Step 0.3 で真の早期終了（空の impact map）が宣言された場合を除きます。Phase 2〜4 がすべてスキップされる場合も実行します | | 3 | [docs-update] Phase 2 — $spec を呼び出す：ビジネス機能のドキュメントを更新 | はい — サービス／フロントエンドのファイルが変更され、かつモジュールに既存の機能ドキュメントがある場合 | | 4 | [docs-update] Phase 2.5/2.6 — $spec-index および／または $tech-spec を通じて派生ビューを更新 | はい — Feature Spec が変更され、バケットが INDEX／ERD を管理している場合、または技術ツリーが影響を受ける場合 | | 5 | [docs-update] Phase 3 — $spec [mode=tests] を呼び出す：§8 のビジネステスト仕様を更新／追加 | はい — ビジネスから見える機能が追加された場合、または既存のビジネスから見える動作が変更された場合 | | 6 | [docs-update] Phase 4 — $spec [mode=sync] を呼び出す：§8 ↔ テストコードを同期 | はい — Phase 3 で §8 の TC が変更された場合 | | 7 | [docs-update] Phase 5 — plans/reports/docs-update-{YYMMDD}-{HHMM}.md にサマリーレポートを作成 | いいえ — 常に実行 | | 8 | [docs-update] 最終レビュー — 影響を受けたすべてのドキュメントが更新されていること、正当な理由なくフェーズがスキップされていないことを確認し、さらに、変更したすべてのモジュールについて Step 2.4 のコード↔仕様の同期検証（AC／BR／TC の差異）を実行 | いいえ — 常に実行 |

実行ルール：

• 各タスクは開始時に in_progress、完了時に completed とします。同時に進行中にできるタスクは1つだけです
• 複数のモジュールがある場合 → Phase 2/3 の呼び出しでは、モジュールごとにサブタスクを1つ追加します
• 影響を受ける参照ドキュメントが複数ある場合 → Task 2 の下に、ドキュメントごと（または信頼できる情報源のクラスターごと）にサブタスクを1つ追加し、各ドキュメントの判定を個別に追跡します
• 完了をまとめて記録することは禁止です。各サブスキルの呼び出しを個別に追跡します
• Phase 0 の TRUE fast-exit（影響マップが空） → 理由を「Skipped — impact map empty」としてタスク 2～8 を completed にします
• Phase 0 の PARTIAL exit（ドキュメント／設定への影響はあるが、業務動作への影響はない場合。例：ハーネス、CI、またはマニフェストのみの変更） → Task 2 を実行し、理由を「Skipped — no business behavior changed」としてタスク 3～6 を completed にします。タスク 7～8 は引き続き実行します
• 対応するタスクのステータスが in_progress になるまで、フェーズのステップを実行してはいけません
• 各フェーズ／スキルの呼び出し後、タスクの更新に1行の根拠を記録します（「何を実行したか」「何が変わったか」「なぜスキップしたか」）
• タスクの追跡／更新ができない場合は、同じステータス遷移を使った同等の8タスク計画トラッカーを維持します

ステップとスキルの呼び出し順序（変更禁止）

| 順序 | タスク ID | ステップ／フェーズ | スキルの呼び出し | トラッキングルール | | ----- | ------- | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | | 1 | 1 | フェーズ 0：トリアージ | このスキル内のトリアージロジック | 差分スキャンの前にタスク 1 を in_progress に設定し、モジュールと影響範囲マップの記録後に completed に設定します | | 2 | 2 | フェーズ 1：プロジェクトコンテキストの同期 | doc-impact-map.cjs + PARALLEL docs-manager サブエージェント（影響を受けるドキュメント／クラスターごとに 1 つ）+ エスカレーション時のみ $scan --target=X または $project-config | 影響範囲マップの作成前にタスク 2 を in_progress に設定し、割り当てられたすべてのドキュメントと設定セクションに判定と根拠が記載された後にのみ completed に設定します | | 3 | 3 | フェーズ 2：ビジネス機能ドキュメント | $spec | 呼び出し前にタスク 3 を in_progress に設定し、出力レビュー後に completed に設定します | | 4 | 4 | フェーズ 2.5/2.6：派生ビューの更新 | $spec-index [mode=index] および／または $tech-spec [mode=generate | audit] | 呼び出し前にタスク 4 を in_progress に設定し、派生出力の更新、または理由を明記したスキップ後に completed に設定します | | 5 | 5 | フェーズ 3：§8 テスト仕様 | $spec [mode=tests] | 呼び出し前にタスク 5 を in_progress に設定し、TC レビュー後に completed に設定します | | 6 | 6 | フェーズ 4：§8 ↔ テストコードの同期 | $spec [mode=sync] | 呼び出し前にタスク 6 を in_progress に設定し、同期の検証後に completed に設定します | | 7 | 7 | フェーズ 5：サマリーレポート | インラインでレポートを作成 | レポート作成前にタスク 7 を in_progress に設定し、ファイルパスの確認後に completed に設定します | | 8 | 8 | 最終レビュー | インライン検証ゲート | 最終監査の前にタスク 8 を in_progress に設定し、すべてのフェーズの妥当性を確認した後に completed に設定します |

適用ルール： 必須のステップを実行できない場合は、順序を変更する前に停止してユーザーに確認してください。トラッキングされていないステップを続行してはいけません。

---

フェーズ 0：トリアージ — 影響を受けるドキュメントの検出

ステップ 0.1：変更ファイルを収集する

1. git diff --name-only HEAD を実行します（ステージ済み＋未ステージの変更）。
2. コミットされていない変更がない場合は、git diff --name-only HEAD~1 を実行します（直近のコミット）。
3. それでも空の場合は、git diff --name-only origin/develop...HEAD を実行します（ブランチの変更）。

ステップ 0.2：変更を分類する

変更ファイルのパターン	影響カテゴリ	実行するフェーズ
docs/project-config.json の {backend-source-paths}/**	spec + spec [mode=tests] + project-docs	1 + 2 + 3 + 4
{frontend-apps-dir}/**、{frontend-libs-dir}/{domain-lib}/**	spec + spec [mode=tests] + project-docs	1 + 2 + 3 + 4
{legacy-frontend-dir}/**Client/**	spec + spec [mode=tests] + project-docs	1 + 2 + 3 + 4
{configured-framework-source-paths}/**	project-docs のみ	1 のみ
specRoots 外の docs/**	project-docs のみ	1 のみ
.claude/**、.agents/**、.codex/**、CLAUDE.md、AGENTS.md	ハーネスのインベントリ — スキル／フック／エージェント／ワークフローの数、カタログ、モジュールレジストリ	1 のみ
依存関係マニフェスト（package.json、*.csproj、pyproject.toml、ロックファイルなど）	project-docs — 技術スタック、バージョン、実行コマンド	1 のみ
インフラ／CI／環境設定（docker-compose*、Dockerfile、.github/workflows/**、*.tf、appsettings*、.env*）	project-docs — ポート、デプロイ、環境変数キー	1 のみ
{frontend-libs-dir}/{framework-core-lib}/**、{frontend-libs-dir}/{common-lib}/**	project-docs のみ	1 のみ

この表は、業務ドキュメントへの影響（フェーズ 2〜4 のうち、どれを実行するか）を分類しています。意図的に大まかな分類になっています。docs/project-reference/** と docs/project-config.json の正確な振り分けは、ステップ 1.1 の影響マップで決定します。そこで確認し、この表から推測しないでください。

Step 0.3: 早期終了チェック — パスの直感ではなく、影響マップに基づいて判断する

今すぐ影響マップを実行し（Step 1.1 と同じコマンド）、出力から fastExit を確認します。

node .claude/scripts/doc-impact-map.cjs --text

マップの結果	処理
fastExit: true — 影響を受ける参照ドキュメントも設定セクションもなく、unrouted ファイルもない	「現在の変更によるドキュメントへの影響はありません。」と報告 → タスク 2-8 を理由「スキップ — 影響マップが空」で completed にする → 早期終了
ドキュメント／設定への影響はあるが、ビジネス動作の変更はない（ハーネス、CI、マニフェスト、ドキュメントツリー）	一部終了 — フェーズ 1 をすべて実行し、フェーズ 2-4 を理由「スキップ — ビジネス動作に変更なし」で completed にして、フェーズ 5 へ進む
ビジネス／サービス／フロントエンドのコードに変更がある	一連の手順をすべて実行
unrouted が空でない	早期終了ではありません — まず unrouted の各ファイルを手動で分類します（対象のウェーブに追加するか、ドキュメントへの影響がない理由を記録します）

[BLOCKING] .claude/** のみ（またはツールのみ）の差分は、完全な早期終了の対象ではありません。 ハーネスの編集により、CLAUDE.md、docs-index-reference.md、project-structure-reference.md が .claude/ の glob 検索で取得するスキル／フック／エージェント／ワークフローのインベントリが変わります。機能への影響がなくても、件数やカタログは古くなり、このスキルの他のゲートでは検出されません。フェーズ 2-4 が確認するのは docs/specs/** のみです。— 理由：古いドキュメントをそのまま出荷する最も手軽な方法は、変更を「ツール関連」と分類して、検出できる唯一のフェーズをスキップすることです。

Step 0.4: 影響を受けるモジュールを自動検出する

変更されたパスから一意なモジュール名を抽出します。必ず重複を除去してください： サブスキルに渡す前に unique() を適用します。同じモジュールのバックエンドとフロントエンドがある場合は、1 つのエントリにします。これにより、$spec の呼び出しが重複するのを防ぎます。

変更ファイルパスのパターン	検出されたモジュール
{backend-module-path}/{Module}/**	{Module}
{frontend-apps-dir}/{app-name}/**	{Module}（app を module に対応付け）
{frontend-libs-dir}/{domain-lib}/{configured-feature-path}/**	{Module}（feature を module に対応付け）
{legacy-frontend-dir}/{Module}Client/**	{Module}

ハードコードされたスキルのパスではなく、docs/project-config.json とプロジェクトの参照ドキュメントから、プロジェクト固有の対応関係を作成します。

node -e "const cfg=require('./docs/project-config.json'); console.log(JSON.stringify({sourcePaths: cfg.codebaseHealth?.sourcePaths, contextGroups: cfg.contextGroups?.map(g => ({name:g.name,pathRegexes:g.pathRegexes})), specRoot: 'docs/specs/'}, null, 2))"
node -e "process.stdout.write('docs/specs/')"

Step 0.5: 各モジュールの既存ドキュメントを確認する

検出された各モジュールについて、次を行います。

1. docs/specs/ の下に対応するバケットディレクトリが存在するか確認します
2. バケットに Feature Spec の README.*.md が含まれているか確認します。含まれていない場合は、プロジェクトの参照ドキュメントにある機能ドキュメントの構成を使用します
3. プロジェクトの参照ドキュメントを使用して、docs/specs/ の下に対応するバケットディレクトリが存在するか確認します
4. 次の項目を記録します：hasFeatureSpec（§1–§7 が存在）、hasTestSpecs（§8 が存在）、hasDerivedIndex（バケットの INDEX.md が存在）

Step 0.6: ドキュメント更新ウェーブを宣言する

検出は SEQ で行い、最初に実施します。以下の割り当てはすべて影響を受けるドキュメントのセットから導き出されるため、Step 0.1～0.5 でそのセットが作成されるまで、何もディスパッチしません。このセットが揃ったら、互いに無関係な N 件のドキュメントの更新は、気兼ねなく並列化できます。ドキュメントまたはドキュメントのクラスターごとに docs-manager サブエージェントを 1 つ割り当て、すべてを 1 回のメッセージで起動します。

1. ディスパッチ前に宣言する — Parallel plan: wave 1 = [docs-manager: {doc A}, docs-manager: {cluster B}, …] · SEQ = [Phase 0 triage, the Phase 2 → 2.5/2.6 → 3 → 4 spec chain, Phase 5 report] (reason)。
2. 厳密に、1 ファイルにつき書き手は 1 人。 影響を受けるドキュメントの各パスは、エージェントの担当ファイルセットとして明記したうえで、必ずちょうど 1 つのエージェントの指示に含めます。どのエージェントも担当しないドキュメントは、気づかれないまま抜け落ちます。2 つのエージェントが担当するドキュメントでは、後からの書き込みが先の書き込みを上書きし、先に得られた知見が消える更新競合が発生します。
3. [HAZARD] 同じ正規データまたは派生データを埋め込んでいる 2 つのドキュメントは、必ず同じエージェントに割り当てます。ウェーブ内で分割してはいけません。 件数、カタログ、モジュールマップ、INDEX の行、ERD のエンティティ、信頼できる情報源からコピーされたテーブルは、1 つのエージェントがその情報源を 1 回読み込んで再生成する必要があります。2 つのエージェントに分けると、単一のコミット内で内容が食い違います。各ドキュメントは単体では整合しているため、レビューでも見逃され、誤りは 2 つのドキュメントの間に残ります。ディレクトリではなく、信頼できる情報源ごとにまとめます。
4. 仕様チェーンの前にバリアを設ける。 Phase 2 → 2.5/2.6 → 3 → 4 は固定の SEQ チェーンです。$spec の出力は派生インデックスに、§8 の TCs は [mode=sync] に引き継がれます。並列化できるのは、独立したモジュール間における各フェーズの内部だけです。これらのフェーズをまたいで並列化してはいけません。
5. モジュール単位のファンアウトを PAR にできるのは、モジュール同士が互いに独立している場合だけです。検出された 2 つのモジュールが 1 つの Feature Spec に対応するなら、書き込み先を共有するため、1 つのタスクにまとめます。これは Step 0.4 でモジュールリストを重複排除する理由と同じです。
6. 各メンバーは要約と Full report: のパスを返します。すべてのメンバーからの返答が揃ってから、あなたが内容を Phase 5 のレポートに統合します。スキップされたメンバーも返答済みとして扱います。

---

Phase 1: プロジェクトコンテキストの同期 — 参照ドキュメント + project-config.json（並列、影響範囲に限定）

このフェーズを設ける理由。 docs/project-reference/** と docs/project-config.json は、後続のすべての AI コンテキストに注入され、フレームワーク内のすべてのスキルのルーティングに使われます。コードが移動してもこれらが更新されなければ、ハーネスはもう存在しないコードベースを学習させ続けます。さらに、このスキルの他の処理ではそれを検出できません。Phase 2～4 が参照するのは docs/specs/** だけだからです。$scan-all と $project-config は修復に使えますが、すべてのドキュメントを一から再導出するため、変更のたびではなく 60 日ごとに実行します。このフェーズは同じ作業を差分の範囲で行います。古い情報を残さないことを保証しつつ、変更のたびに実行できる規模に抑えます。

実行するタイミング： Step 0.3 で TRUE の早期終了が宣言された場合を除き、必ず実行します。Phase 2～4 がすべてスキップされる場合でも実行してください。

範囲の遵守： 影響マップで対象となる内容だけを検証します。限定的な修正ではドキュメントを再び正確な状態にできない場合は、完全な $scan --target=X にエスカレーションします。ドキュメントをすべて再生成してはいけません。また、ここで参照ドキュメント全体を手作業で作成してはいけません。作成を担うのは scan であり、このフェーズが担うのは検証と限定的な修正です。

Step 1.1: ドキュメント影響マップを作成する（SEQ — 以下のすべてはこれに基づきます）

node .claude/scripts/doc-impact-map.cjs --json     # machine-readable (drives the wave)
node .claude/scripts/doc-impact-map.cjs --text     # human-readable (goes in the report)
node .claude/scripts/doc-impact-map.cjs --base=origin/main   # branch-scope instead of working tree

このマップは、変更された各ファイルを、古くなる可能性のあるドキュメントと設定のセクションに振り分け、ドキュメントごとに次の情報を返します：doc、exists、lastScanned／ageDays、scanTarget（全体再スキャンへのエスカレーション先）、checks（適用する検証項目）、changedFiles／addedFiles／deletedFiles、heuristicOnly。振り分けは docs/project-config.json（contextGroups、modules、testing、e2eTesting、styling、designSystem、specRoots）と変更分類ルールから導き出します。プロジェクトのパスをハードコードしてはいけません。

マップの出力の扱い — [BLOCKING] ルール：

1. unrouted ファイルは、影響がない証拠ではありません。ルーターにルールがなかったことを示します。各ファイルを手動で分類し、検証対象のウェーブに追加するか、影響するドキュメントがない理由をレポートに記録してください。振り分けられなかったファイルを、確認せずに最新と判断してはいけません。
2. heuristicOnly のドキュメントは推測であり、証拠ではありません。他のドキュメントと同様に検証し、理由を明記した場合に限って「影響なし」と判断してください。
3. exists: false のドキュメントは、最新のドキュメントではなく、欠落しているドキュメントです。$scan --target=<scanTarget>（ドキュメント一式が存在しない場合は $docs-init）に振り分けてください。
4. スクリプトを利用できない場合（古いチェックアウト、Node 以外のホスト）は、docs/project-config.json から同じマップを手動で導き出してください。変更されたパスを contextGroups[].pathRegexes → guideDoc／patternsDoc／stylingDoc／designSystemDoc、modules[].pathRegex → プロジェクト構成＋modules、テスト／E2E／スタイル関連のパス → 対応するドキュメント、マニフェスト → 技術スタック、インフラ／CI → ポートとデプロイ、.claude/** → 項目数に照合します。マップを手動で作成したことを記録してください。

Step 1.2: 検証ウェーブを宣言する（PAR — 1 つのメッセージですべてのメンバーを指定）

Parallel plan: wave 1 = [docs-manager: {doc A}, docs-manager: {cluster B}, docs-manager: project-config.json, …] · SEQ = [Step 1.1 impact map, the Phase 2 → 2.5/2.6 → 3 → 4 spec chain, Phase 5 report] (reason)

ウェーブ構成ルール — Step 0.6 の注意事項をそのまま適用し、さらに以下を守ってください。

• ファイルごとに書き込み担当者を必ず 1 人にします。 docs/project-config.json を担当するエージェントは、常にウェーブ内でちょうど 1 人にしてください。複数のエージェントが同じファイルに JSON をマージすると、更新が失われることが確実です。
• ディレクトリではなく、信頼できる情報源ごとにグループ化します。 README.md と project-structure-reference.md はどちらもモジュール／ディレクトリのマップを記載し、CLAUDE.md、docs-index-reference.md、project-structure-reference.md はすべて .claude/ 由来の項目数を含んでいます。それぞれのグループは同じエージェントに割り当て、1 つのコミット内で数値に食い違いが生じないようにしてください。
• 振り分け対象の各ドキュメントは、ちょうど 1 つの指示に含めてください。担当者のいないドキュメントは、見落としにつながります。
• 各メンバーは判定表と Full report: のパスを返します。すべてのメンバーが返答してからマージしてください。

Step 1.3: ドキュメントごとの検証契約（各ウェーブメンバーが実行する内容）

まず検証し、その後、変更範囲を絞って修正します。各ドキュメントについて、マップに記載された checks だけを実行してください。

チェック項目	答える質問	確認方法	失敗した場合
claims	ドキュメントで引用されているパスや例は、現在も存在していますか？	node .claude/scripts/doc-impact-map.cjs claims <doc>（missing = リンク切れ、ambiguous = サフィックスで解決される短縮形式）、続いて引用された各ファイルで引用シンボルを grep	リンク切れの引用先を修正するか削除し、曖昧な引用先にはリポジトリルートからのパスを指定します（引用は根拠です。リンク切れのまま残さないでください）。reference-doc-freshness テストスイートは、リンク切れの引用が1つでもあるとビルドを失敗させます
coverage	このドキュメントの種類に該当する追加済みの成果物が、すべて記載されていますか？	マップの addedFiles とドキュメントの一覧や例を比較します	file:line を含む不足分の行や例を追加します
counts	数値に関する記述は、実際の数と一致していますか？	glob/grep で再集計します（skills、hooks、agents、workflows、services、docs、tests）	数値を更新します。件数が生成されている場合は、マーカー領域も更新します
conventions	差分でドキュメントに記載のないパターンが導入されたか、記載済みのパターンに違反していますか？	ドキュメントのルールに照らして差分を確認します	新しいパターンはドキュメントに記載します。違反は報告し、慣例として記載しないでください
commands	ドキュメントに記載された実行・テストコマンドは、現在も動作しますか？	マニフェストやスクリプト（package.json、テスト設定、integrationTestVerify）と照合します	コマンドを修正します
versions	記載された技術やフレームワークのバージョンは、マニフェストと一致していますか？	マニフェストを確認します。推測で判断しないでください	バージョンを修正します
ports	記載されたポートやエンドポイントは、インフラ設定と一致していますか？	compose/k8s/appsettings を確認します。推測で判断しないでください	ポートを修正します
links / catalog	相互リンクやカタログの行は、正しく参照先に解決されますか？	各参照先の存在を確認します	行を修正するか削除します
ドキュメントごとの判定（必ず1つ。根拠が必要）：

判定	意味	必要な根拠
FRESH	適用対象のチェックをすべて実行して合格し、編集は不要です	実行したチェックと、比較した内容
PATCHED	外科的な編集を適用した後、簡潔さを保つために $prompt-enhance <doc> を実行しました	変更したセクション＋追加した各主張の file:line による根拠＋prompt-enhance の実行確認（または実行を見送った理由）
RESCAN REQUIRED	外科的な修正の範囲を超えています。新しいサブシステム／パターンファミリーが追加された、影響を受けたセクションの例の大半が使われていない、またはドキュメントの構成がコードに合わなくなっています	実行する scanTarget（$scan --target=X）と、今回のセッションで実行したか、実行待ちか
UNVERIFIED	チェックできませんでした（ツール不足、読み取りがブロックされた、予算不足）	理由と、次に実行すべきこと

[BLOCKING] 最新状態を捏造してはいけません。「問題なさそう」「おそらく変更されていない」「差分が小さかった」はチェック結果ではありません。検証されていないドキュメントの判定は UNVERIFIED であり、FRESH ではありません。誤った FRESH は、後でドリフトを検出するための疑いを消してしまうため、チェックを行わないよりも悪い結果です。

[BLOCKING] PATCHED と判定する docs/project-reference/** の各ドキュメントでは、判定を記録する前に必ず $prompt-enhance <doc>（デフォルトは --op=enhance）を実行してください。 これらのドキュメントは、以降のすべての AI コンテキストに挿入されます。正確な文章を追加する外科的な編集でも、再圧縮しなければドキュメントは肥大化したままです。$prompt-enhance は、AI にとって十分な価値を保ちながら内容を可能な限り簡潔にします（簡潔化圧縮＋注意喚起の固定）。これにより、完全な再スキャンで $scan --target=X の必須最終ステップ（scan/SKILL.md の Final Step）が解消するのと同じ問題を、限定的なパッチ経路でも解消できます。そのため、RESCAN REQUIRED のドキュメントが $scan にエスカレーションされれば、この処理は自動で行われ、ここで別途呼び出す必要はありません。単一のスタンプ／日付／件数のみの編集の場合に限りスキップし、その理由を記録してください。

ステップ 1.4：project-config.json のドリフトチェック（単一ライター、スキーマ検証済み）

マップで指摘されたセクションのみを検証します。各セクションについて：

1. 根拠から再導出する — 古い設定値ではなく、変更されたファイルを読みます。
2. 外科的にマージする — エントリーを追加／更新します。トップレベルのセクションの名前変更、削除、再構成は絶対に行いません（ここでも $project-config の Schema Protection Rules がそのまま適用されます）。
3. 変更したすべての pathRegex／パスが、実在するものに引き続き一致することを証明する — どのファイルにも一致しない正規表現は、下流のルーターをすべて黙って無効化する古い設定です。スキーマチェックでは検出されません。

node -e "const c=require('./docs/project-config.json');const {execSync}=require('child_process');const files=execSync('git ls-files',{encoding:'utf8'}).split('\n').filter(Boolean).map(f=>'/'+f);for(const m of c.modules||[]){const re=new RegExp(m.pathRegex,'i');const n=files.filter(f=>re.test(f)).length;console.log((n?'OK  ':'DEAD')+' modules.'+m.name+' -> '+n+' file(s)')}"

4. マージ後にスキーマを検証する：

node -e "const {validateConfig}=require('./.claude/hooks/lib/project-config-schema.cjs');console.log(JSON.stringify(validateConfig(require('./docs/project-config.json')),null,2))"

5. 即興で対処せず、エスカレーションする — 新しいトップレベルのセクション、新しいモジュールクラス、新しい技術スタック、または検証の失敗がある場合、その変更はパッチではなく再スキャンです → $project-config を実行します（今回のセッションで実行できない場合は、実行が必要であることを報告してください）。

Step 1.5: README とプロジェクトドキュメント（docs-manager）

Phase 0 の差分コンテキストを docs-manager サブエージェント（agent_type="docs-manager"）に渡し、同じウェーブ内でプロジェクトの説明文書を扱います。

• README.md — プロジェクトのスコープまたはセットアップに変更があった場合に更新します（300 行未満に保ってください）
• docs/project-reference/project-structure-reference.md — サービスアーキテクチャまたはサービス間パターンに変更があった場合に更新します（README と同じエージェントを使い、信頼できる情報源を共有します）

スタンドアロンで呼び出す場合（ワークフローステップではない場合）は、影響箇所を特定するため、まず 2～4 個の scout-external（推奨）または scout エージェントを起動してもかまいません。ワークフローステップとして実行する場合は、スカウティングを省略し、Phase 0 の差分コンテキストを使用します。

変更なしの除外事項：このエージェントは docs/specs/**、テスト仕様、spec-index/ERD、派生した技術ビューを決して担当しません。

Step 1.6: スタンプの規律（BLOCKING）

実行した内容	書き込むスタンプ
完全な $scan --target=X	``（scan が担当、ドキュメントの先頭）
Last scanned スタンプがあるドキュメントに対する、影響範囲を絞った検証／パッチ	``（そのスタンプの直後の行）
Last scanned スタンプがないドキュメントに対する、影響範囲を絞った検証／パッチ — CLAUDE.md、.claude/docs/**、その他の AI 向け指示ファイル	スタンプを一切書き込まないでください。 Step 1.7 の出力にのみ、そのドキュメントの判定を記録します。— 理由：これらのファイルは常時有効な指示として読まれ、.claude/agents/docs-manager.md:35 はこれらへの来歴メタデータの記載を禁止しています。メタデータ記録禁止ルールはスタンプルールより優先され、スタンプルールによって上書きされることはありません。

[BLOCKING] 影響範囲を絞ったパスでは、Last scanned に触れてはいけません。 このスタンプは 60 日ごとの全体再スキャンゲート（getStaleReferenceDocs → refreshScanStaleFlag、.claude/hooks/lib/session-init-helpers.cjs:769-810）への入力です。部分チェックでスタンプを動かすと、ドキュメント全体の劣化を検出する仕組みを無効にして処理を速めることになります。この 2 つの仕組みは相互補完的であり、置き換え可能ではありません。

今回の実行でドキュメントを完全に再スキャンした後は、ゲートを再評価します。

node -e "require('./.claude/hooks/lib/session-init-helpers.cjs').refreshScanStaleFlag()"

Step 1.7: Phase 1 の出力

Phase 5 のレポートに鮮度テーブルを出力します。ルーティングされたドキュメントごとに 1 行、設定セクションごとに 1 行を設け、それぞれに判定、実施したチェック、根拠を記載します。RESCAN REQUIRED または UNVERIFIED のドキュメントは Recommendations に引き継ぎ、次のセッションに負債を明示的に引き継いで、見えないままにしないようにします。

---

Phase 2: ビジネス機能のドキュメント化 — $spec を呼び出す

実行する場合： トリアージで hasFeatureDocs = true のモジュールが検出され、かつサービス／フロントエンドのファイルに変更があった場合。

スキップする場合： サービス／フロントエンドの機能ファイルに変更がない場合。次のように報告します："ビジネス機能のドキュメントへの影響はありません。"

ステップ 2.1：新規作成か更新かを判断する

シナリオ	アクション
モジュールに既存の機能ドキュメントがある	$spec を呼び出します — 自動検出によって更新フローが開始されます
モジュールに機能ドキュメントがなく、変更によって機能が追加・変更される（新しいエンドポイント、コマンド／クエリ、エンティティ、ビジネスルール、ユーザー向けの動作）	ブロック — 次のように報告します："Module {Module} has NO Feature Spec but this change introduces feature behavior. Create the tech-free 8-section Feature Spec FIRST via $spec, then re-run docs-update."。スキップしてはいけません。これがドキュメント先行のゲートです。
モジュールに機能ドキュメントがなく、変更がツール／スタイル／設定のみ（動作への影響がない）	理由 "No feature behavior changed — no Feature Spec required." を添えてスキップします（Phase 0 の高速終了条件 :113-120 に一致）。
ユーザーがドキュメントの完全な作成を明示的に依頼した	モジュール名を明示して $spec を呼び出します

ステップ 2.2：$spec を呼び出す

$spec Update feature docs for modules: {detected modules}.
Changed files: {list from triage}.
Impacted sections based on change types: {section impact from triage}.
Mode: update (existing docs only, do not create from scratch).

$spec が処理する内容（ここで重複して行わないでください）：

• 8 セクションの技術詳細を含まない構成の徹底
• 差分分析 → セクションへの影響のマッピング
• コードベース分析（エンティティ、コマンド、クエリ、コントローラー）
• 根拠に基づいた影響対象セクションの更新
• バケット INDEX.md のカタログ行の更新
• 3 パスの検証（根拠の監査、ドメインモデル、相互参照）
• 技術詳細を含まない原則（§1〜§7 に実装の詳細を記載しない。根拠を示す情報は §8 と [Source:] のみ）

ステップ 2.3：$spec の出力をレビューする

1. 更新されたセクションがトリアージによる影響セクションのマッピングと一致している
2. トリアージで影響ありと判定されたセクションに漏れがない
3. 不足が見つかった場合 → 不足したセクションについて $spec を再実行する

ステップ 2.4：コード↔仕様の同期検証（最終パス — すべてのシーケンスで docs-update が最後に実行されるため実施）

目的： feature／bugfix／big-feature では docs-update がすでに最後に実行されるため、このステップがワークフローの最終ゲートになります。これは Phase 4 のコミットフックと対になる順序上のパートナーです（このステップが案内し、フックが強制します）。ワークフローが完了する前に、SHIPPED コードがマッピング済みの技術用語を使わない 8 セクションの Feature Spec と実際に一致していることを検証します。

この実行で変更された各モジュールについて、変更されたコードとその Feature Spec を比較し、次の 3 つのセットを確認します。

仕様セット（Feature Spec のセクション）	変更されたコードとの同期チェック	差異がある場合の対応	--------
§3 受け入れ条件（AC-{FC}-NN）	変更されたユーザー向けの動作はすべて AC に対応している必要があります。AC のない新しい動作は、AC の不足です。	差異を報告し、$spec を再実行して AC を追加します。
§4 ビジネスルール（BR-{FC}-NNN、[HARD]/[SOFT]）	変更された各検証／不変条件が BR と一致している必要があります。コードパスが削除または弱体化された [HARD] ルールは、リグレッションです。	ブロック — 作成者が解決できるよう、コードと仕様の矛盾として提示します。
§8 テスト仕様（TC-{FC}-NNN ＋ CoveredBy:）	新規または変更された、ビジネス上ユーザーから見える動作にはそれぞれ TC が必要です。また、Tested の各 TC の CoveredBy: {File}::{Method} または承認済みのカバレッジ担体が、引き続き解決可能である必要があります。従来の IntegrationTest: は移行入力としてのみ使用します。	報告し、$spec [mode=sync] に回します。
派生技術ビュー（specRoots.technical.path）	技術面のみのカバレッジやコンポーネントトポロジーの変更には、派生ビューの再生成または監査が必要になる場合があります。このビューはコード／テストから生成され、手作業では作成しません。	報告し、`$tech-spec [mode=generate	audit]` に回します。

出力： docs-update のレポートに追加する、短い同期検証テーブル（モジュール · AC の差異 · BR の差異／矛盾 · TC の差異）。クリーンとは、3 つのすべてに差異がない状態です。[HARD]-BR の矛盾がある場合、解決されるか、オーナーが明示的に承認するまでワークフローの完了をブロックします。

範囲： ビジネスコードと仕様の差異のみを対象とします。技術コントラクト（API ルート／DTO、バス／ジョブの仕組み）はコードを正とし、意図的に文章との再検証は行いません。新たなシーケンスステップも verify-sync モードも追加しません。この責務は docs-update に既存の最終パス内にあります。

---

フェーズ 2.5：派生インデックス／ERD の更新（任意 — spec-index）

[SINGLE-HOME] 独立した「エンジニアリング仕様バンドル」はありません。正本となる成果物は、フェーズ 2 で更新された 8 セクションの Feature Spec です。spec-index は、これらの Feature Spec から派生バケット INDEX.md／機能横断 ERD のみを再生成するよう再利用されます。A-E ツリーを再抽出することはありません。フェーズ 2 の変更によって古くなった派生インデックス／ERD をバケットが管理している場合にのみ、このフェーズを実行してください。

実行するタイミング： フェーズ 2 で 1 つ以上の Feature Spec を変更し、バケットが古くなった派生 INDEX.md／ERD 補助資料を管理している場合。

スキップするタイミング：

• docs/、.claude/、または設定ファイルのみを変更した場合
• docs/specs/{Bucket}/ 配下の Feature Spec を変更していない場合
• フェーズ 2 をスキップした場合（機能への影響がない場合）
• バケットが派生インデックス／ERD を管理していない場合、または project-config.json に "spec_discovery_update": false が含まれている場合
• フェーズ 2 で spec がすでに INDEX.md を更新している場合（別途更新する必要はありません）

ステップ 2.5.1：バケットを特定する

• docs/project-reference/spec-system-reference.md → App Bucket Mapping の正規テーブルを使って、変更されたサービスを App Bucket に対応付けます。
• docs/specs/{Bucket}/ に更新された Feature Spec が含まれていることを確認します。

ステップ 2.5.2：spec-index を実行する（派生インデックスモード）

$spec-index mode=index bucket={Bucket} artifacts=INDEX[,ERD]
Source: the canonical Feature Specs in docs/specs/{Bucket}/.
Output: regenerated DERIVED docs/specs/{Bucket}/INDEX.md (+ {Bucket}.erd.md if maintained), each carrying the DERIVED banner.

ステップ 2.5.3：更新完了を確認する

• INDEX.md の行が現在の Feature Spec 一覧と一致していること（リンク切れや機能の欠落がないこと）を確認します。
• DERIVED バナーと再生成日が記載されていることを確認します。
• 次の内容を報告します："派生インデックスを更新しました：{Bucket} — {N} 件の機能をカタログ化"

関心の分離： docs-update が処理を統括し、バケットの範囲を spec-index に渡します。派生インデックスを手動で編集したり、M##／A-E 成果物（廃止済み）を再作成したりしてはいけません。

---

フェーズ 3：テスト仕様 — $spec [mode=tests] を実行する

実行するタイミング： ビジネス上ユーザーに見える新機能を追加した場合、または既存のビジネス上ユーザーに見える動作を変更した場合。ユーザー／QC から見える結果に変更のない技術的な変更では、ビジネス向けのセクション 8 を編集しません。技術的なテスト範囲が必要な場合は、tests と $tech-spec に振り分けて、技術的な派生ビューを作成します。

スキップするタイミング： 動作への影響がなく、変更が純粋に見た目に関するもの（スタイル、コメント、ドキュメントのみ）の場合。

ステップ 3.1：TC モードを決定する

コンテキスト	TC モード
新機能のコードがあり、既存の TC がない	implement-first
PBI／ストーリーが存在し、コードは未作成	TDD-first
既存の TC とコード変更／バグ修正	update
ユーザーが「テスト仕様を同期して」と指示	sync
注釈付きのテストは存在するが、ドキュメントがない	from-integration-tests

PBI／アイデア成果物の振り分け： 変更された成果物が、docs/project-config.json またはプロジェクト参照ドキュメントで設定された PBI／アイデア成果物のルートに一致する場合、docs-update は検出と振り分けのみを行います。影響を受けるモジュール、機能ドキュメント、TC の範囲を特定し、$spec、$spec [mode=tests]、または $spec [mode=sync] に振り分けることはできます。PBI／アイデア成果物から直接 TC の内容を生成したり、セクション 8 を編集したりしてはいけません。成果物のルートが設定されていない場合は、パスを決めつけず、まずプロジェクト設定／参照ドキュメントを初期化するようユーザーに依頼してください。

ステップ 3.2：$spec [mode=tests] を実行する

$spec [mode=tests] Mode: {detected mode}.
Modules: {detected modules}.
Changed files: {list from triage}.
Business-visible functionality detected: {new or changed user/QC-visible outcomes from diff analysis}.

$spec [mode=tests] が処理する内容（ここで重複して処理しないでください）：

• 5 つのモード：TDD-first、implement-first、update、sync、from-integration-tests
• 十進位ベースの番号付けによる TC-{FEATURE}-{NNN} 形式
• 対話形式の TC レビュー（ユーザーに直接質問）
• 横断的なカテゴリ：認可、シードデータ、パフォーマンス、データ移行
• フェーズ対応のカバレッジ（計画フェーズ → TC）
• サービス横断の影響に関するグラフコンテキスト分析
• TC ごとのエビデンス検証
• 機能ドキュメントのセクション 8 に書き込み（正本となるビジネス向け TC レジストリ）

ステップ 3.3：$spec [mode=tests] の出力をレビューする

1. 新しい TC が、トリアージで特定された新たなビジネス可視機能をすべて網羅している
2. TC ID が既存のものと重複していない
3. エビデンス欄が入力されている（テンプレートのプレースホルダーではない）

---

フェーズ 4：テスト仕様書とテストコードの同期 — $spec [mode=sync] を実行する

実行するタイミング： フェーズ 3 で、Feature Spec の §8 に新規または更新された TC がある場合。

スキップするタイミング： §8 のテスト仕様書に変更がない場合。

ステップ 4.1：$spec [mode=sync] を実行する

$spec [mode=sync] Sync test specs for capabilities: {detected features}.
Direction: forward (Feature Spec §8 Test Specifications → executing test code).
Updated TCs from Phase 3: {list of new/changed TC IDs}.

$spec [mode=sync] が処理する内容（ここで重複して実施しないこと）：

• 双方向同期：§8 のテスト仕様書と実行テストコード
• 双方向比較：Feature Spec §8 とテストコード（技術面の信頼できる情報源はコード）
• テストの相互参照（すべての実行テスト階層における設定済みテスト仕様アノテーションキー TestSpec と、TC ごとの CoveredBy: フィールド。レガシーの IntegrationTest: は移行時の入力としてのみ使用）

廃止された QA ダッシュボード（docs/specs/README.md、docs/specs/PRIORITY-INDEX.md）と、手動管理されていた A-E／M## のエンジニアリングツリーは、すでに存在しません。§8 がビジネス TC の正式なレジストリです。派生資料は、バケット INDEX.md の件数（フェーズ 2.5）と、再生成可能な specRoots.technical.path 配下の技術ビュー（フェーズ 2.6）です。

ステップ 4.2：同期結果をレビューする

1. フェーズ 3 の新しい TC がすべてテストコードに反映されている（または、理由を添えて未テストとしてフラグ付けされている）。
2. 孤立した TC がない（テストコードの TestSpec アノテーションで参照されているのに、§8 に存在しない TC）。

---

セクションの担当範囲

各ドキュメントセクションの担当スキル — docs-update は委任のみを行い、直接編集は決して行いません。

セクション	担当スキル	docs-update の役割
docs/project-reference/**（作成）	$scan --target=X	影響範囲に限定した外科的なパッチであることを確認する。パッチで要件を満たせない場合は scan にエスカレーションする。リファレンスドキュメント全体を直接作成しないこと
docs/project-config.json（構造）	$project-config	スキーマ検証を行いながら、影響を受けるセクションを確認し、外科的にマージする。セクション全体や新技術に関する変更はエスカレーションする
§1～§7（Feature Spec、技術情報を含まない）	$spec	トリアージのコンテキストを渡し、出力をレビューする
§8（テスト仕様書）	$spec [mode=tests]	TC モードと変更ファイルを渡す。ここで TC を作成しないこと
§8 とテストコードの同期	$spec [mode=sync]	機能リストと方向を渡す。直接編集しないこと
派生バケット INDEX.md／ERD	$spec-index（任意）	バケットの範囲を渡す。派生インデックスを手動編集しないこと
派生技術仕様ビュー	$tech-spec（任意）	サービス／コンポーネントの範囲を渡す。派生技術ファイルを手動編集しないこと

---

フェーズ 5：サマリーレポート

必ず、レポート全体を plans/reports/docs-update-{YYMMDD}-{HHMM}.md に書き込みます。

### Documentation Update Summary

**Triage:** {N} files changed → {categories detected}
**Modules detected:** {module list}
**Generated mirror sync:** {Completed / N/A / Required before close}

**Phase 1 — Project Context Sync (impact-scoped freshness):**

Impact map: {N} changed files → {D} docs, {S} config sections, {U} unrouted ({map source: working tree / last commit / branch})

| Reference doc | Verdict                                        | Checks run                    | Evidence / action                                         |
| ------------- | ---------------------------------------------- | ----------------------------- | --------------------------------------------------------- |
| {doc}         | FRESH / PATCHED / RESCAN REQUIRED / UNVERIFIED | {claims, coverage, counts, …} | {what was compared; sections patched; scan target queued} |

| project-config.json section | Verdict                                        | Evidence / action                                                   |
| --------------------------- | ---------------------------------------------- | ------------------------------------------------------------------- |
| {section}                   | FRESH / PATCHED / RESCAN REQUIRED / UNVERIFIED | {re-derived from …; schema validation result; dead pathRegex found} |

- Unrouted files classified: {file → why no doc impact}
- README / project docs: {Updated/Skipped}: {reason}
- Stamps: {docs given `Last verified`} · {docs fully rescanned and given `Last scanned`} · staleness flag refreshed: {yes/no}

**Phase 2 — Feature Specs ($spec):**

- {Capability X}: {Updated §1–§7 / No existing Feature Spec / Not impacted}
- {Capability Y}: {Updated §4 Business Rules, §5 Domain Model / Skipped: no Feature Spec}

**Phase 2.5 — Derived Index Refresh ($spec-index, optional):**

- {Refreshed {Bucket} INDEX.md ({N} capabilities) / Skipped: no derived index maintained / Skipped: spec_discovery_update=false}

**Phase 3 — Test Specifications §8 ($spec [mode=tests]):**

- Mode: {mode used}
- New TCs: {list of TC IDs added}
- Updated TCs: {list of TC IDs modified}
- Skipped: {reason if skipped}

**Phase 4 — Test Spec ↔ Test Code Sync ($spec [mode=sync]):**

- {Synced N TCs to test code / Skipped: no §8 changes}
- Discrepancies: {§8-vs-test-code comparison issues}

**Recommendations:**

- {New docs that should be created}
- {Stale docs flagged but not auto-fixed}
- {TCs flagged as Untested}

---

決定マトリックス：docs-update とスキルの直接使用を使い分ける基準

シナリオ	docs-update を使用するか？	スキルを直接使用するか？
実装後のドキュメント同期（コード変更があった場合）	はい — 一連のオーケストレーションを実行	—
変更後にプロジェクト参照ドキュメントと project-config.json を最新の状態に保つ	はい — フェーズ 1 で影響範囲に絞って検証	$scan --target=X または $project-config（単一のドキュメント／セクションを全面的に再構築する場合）
差分に関係なく、すべての参照ドキュメントを更新する	いいえ	$scan-all（および $project-config）
新機能のドキュメントを一から作成する	いいえ	$spec
特定の PBI 向けの TC を生成する（TDD 優先）	いいえ	$spec [mode=tests]
PBI／アイデアのアーティファクトの変更を振り分ける	はい — 検出と委任	$spec と $spec [mode=tests] の担当スキル
ダッシュボードのみを同期する（コード変更なし）	いいえ	$spec [mode=sync]
$plan-execute または $fix の後のワークフローステップ	はい — 一連のオーケストレーションを実行	—
ユーザーが「変更後にドキュメントを更新して」と依頼する場合	はい — 一連のオーケストレーションを実行	—

---

追加リクエスト

呼び出し元のコンテキストを $ARGUMENTS 経由で渡すと、冗長なトリアージを省略したり、対象範囲を絞り込んだりできます。

キー	例	効果
modules	modules=ModuleA,ModuleB	自動検出を省略し、指定されたリストを使用します
changed_files	changed_files=<configured-source-path>/ModuleA/...	git diff を省略し、指定されたファイルリストを使用します
phases	phases=2,3	指定されたフェーズのみを実行します
mode	mode=update	仕様モードの検出を上書きします
tc_mode	tc_mode=implement-first	仕様の [mode=tests] モード検出を上書きします
skip_phases	skip_phases=1,2.5	特定のフェーズをスキップします
freshness	freshness=impact（デフォルト） / full / off	impact = 指定どおりにフェーズ 1 を実行します。full = 対象となったすべてのドキュメントを $scan --target=X（および $project-config）にエスカレーションします。off = フェーズ 1 をスキップします。明示的なユーザー指示がある場合にのみ許可され、レポートでは対象となったすべてのドキュメントを UNVERIFIED として記録する必要があります
base	base=origin/main	作業ツリーではなく、ブランチ間の差分を対象にインパクトマップを作成します

<additional_requests> $ARGUMENTS </additional_requests>

---

docs-update だけでは不十分な場合のエスカレーション

状況	代わりに行うこと
Feature Spec がないが、機能は存在する	$spec [mode=init] を実行して 8 セクションの Feature Spec を作成し、その後 docs-update を実行します
派生バケットの INDEX.md／ERD がない	$spec-index mode=index bucket={Bucket} を実行して再生成します
統合テストが TC と一致しない	$integration-test-review を実行して診断し、その後 $integration-test を実行して修正します
誤った仕様が原因のバグ	$spec [mode=update] を実行して正規の仕様を修正してから、docs-update を実行します。必要に応じて $spec-index mode=index を実行し、バケットのインデックスを再生成します
参照ドキュメント 1 件に、局所的な修正を超える誤りがある	対象の $scan --target=<key>（マップの scanTarget）を実行し、その後 Phase 1 を再実行して確認します
参照ドキュメントの大半が古い、または 60 日ゲートが発動した	$scan-all を実行します。影響範囲の修正では、差分より前から存在する劣化は修復できません
参照ドキュメントが存在しない	全ドキュメントがない場合は $docs-init を、単一のドキュメントがない場合は $scan --target=<key> を実行します
project-config.json に新しいセクション、モジュールクラス、技術スタックが必要、またはスキーマ検証に失敗する	$project-config を実行します。これは再スキャンであり、マージではありません
現在の差分では触れられていない、長期間の劣化が疑われる	$scan-codebase-health を実行します（カウントのずれ、不要な設定参照、壊れた相互リンクを確認します）

---

[BLOCKING] いかなる作業を行う前にも、タスク追跡を使って 8 件すべてのタスクを作成してください。Mandatory Task Creation の表を参照してください。サブスキルを呼び出さずに、タスクを省略、まとめて完了、または完了扱いにすることは絶対にしないでください。 [BLOCKING] 固定されたステップスキルの順序に従ってください：Phase 0 -> Phase 1 -> Phase 2 -> Phase 2.5/2.6 -> Phase 3 -> Phase 4 -> Phase 5 -> Final review。ユーザーの明示的な承認なしに、順序を変更、統合、または省略することは絶対にしないでください。 [BLOCKING] ステップごとのタスクロック：各ステップの前にタスクを in_progress にし、各ステップの後に証拠または明示的なスキップ理由を添えて completed にしてください。 [BLOCKING] Task ツールを使用できない場合は、同等の 8 ステップの計画トラッカーを作成し、各ステップのステータスを同期してください。

重要な目的： コード変更後のすべてのドキュメント同期を一元的に調整します。影響をトリアージし、専門スキルに委任します。

証拠ゲート： [BLOCKING] — あらゆる主張には file:line による証明、または追跡可能な証拠が必要です。対応するには確信度が 80% を超えている必要があります。 批判的思考の姿勢 — 批判的思考と順序立てた思考を適用してください。すべての主張について、根拠をたどって確認し、確信度が80％を超えた場合にのみ行動してください。 ハルシネーション対策： 推測を事実として提示しないでください。すべての主張に出典を示し、不確実性を率直に認め、出力に誤りがないか自己確認し、独立して相互参照してください。自分の確信度にも懐疑的でいてください。根拠のない確信こそ、あらゆるハルシネーションの根源です。

サブエージェントの返却契約 — このスキルがサブエージェントを起動する場合、サブエージェントは以下の構造のみを返さなければなりません。メインエージェントはこの要約のみを読み、サブエージェントの出力全文をインラインで求めてはなりません。

## サブエージェントの結果：[skill-name]

Status: ✅ PASS | ⚠️ PARTIAL | ❌ FAIL
Confidence: [0-100]%

### Findings (Critical/High only — max 10 bullets)

- [severity] [file:line] [finding]

### Actions Taken

- [file changed] [what changed]

### Blockers (if any)

- [blocker description]

Full report: plans/reports/[skill-name]-[date]-[slug].md

メインエージェントが Full report ファイルを読むのは、（a）特定のブロッカーを解決する場合、または（b）修正計画を作成する場合のみです。 サブエージェントは、全文レポートを段階的に書き込み（SYNC:incremental-persistence に従う）、メモリ内に保持しません。

コンテキスト予算 — 返却する内容はトランスクリプトではなく要約です。指摘事項は最大10件とし、ファイルの生の内容、差分の全文、ログの逐語的な記録をインラインで含めず、ソースを再貼り付けしないでください。要約を超える内容はすべてディスク上の Full report に保存します。要約の形式を超える場合、サブエージェントは詳細をレポートに書き込み、参照先のみを返さなければなりません。オーケストレーターのコンテキストは、マップリデュース全体で保護すべき限られたリソースです。

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

境界	Grep 用語
イベントのプロデューサー	Publish, Dispatch, Send, emit, EventBus, outbox, IntegrationEvent
イベントのコンシューマー	Consumer, EventHandler, Subscribe, @EventListener, inbox
サガ／オーケストレーション	Saga, ProcessManager, Choreography, Workflow, Orchestrator
同期サービス呼び出し	他サービスとの間の HTTP/gRPC 呼び出し
共有コントラクト	OpenAPI 仕様、proto、共有 DTO — 破壊的変更に注意
データ所有権	他サービスが同じテーブル／コレクションを読み書きする場合 → 共有 DB のアンチパターン

接点ごとに確認する項目： 所有サービス · メッセージ名 · コンシューマー · リスク（NONE / ADDITIVE / BREAKING）。

以下を完了するまで作業をブロック： プロデューサーの調査 · コンシューマーの調査 · サガの確認 · コントラクトのレビュー · 破壊的変更リスクの明示 AI によるミスの防止 — すべてのタスクで避けるべき失敗パターン：

コンテキストが変わったらファイルを読み直してください。 コンテキストの圧縮、再開、長時間にわたる作業によって記憶が古くなることがあります。作業に取りかかる前に、現在のファイルを確認してください。 生成した内容をソースの根拠と照合してください。 AI は API、名前、主張、文書の事実を幻覚することがあります。文書に記載したり参照したりする前に、該当するソースを確認してください。 削除や名前変更の前に、下流の参照を確認してください。 成果物を削除すると、ドキュメント、生成されたミラー、設定、呼び出し元に古い情報が残ることがあります。まず参照関係を洗い出してください。 編集後は影響の連鎖全体をたどってください。 定義を変更すると、派生した出力や利用側を見落とすことがあります。完了を宣言する前に、影響を受ける連鎖をたどってください。 最初の出力だけでなく、影響を受けるすべての出力を検証してください。 1つのチェックが成功しても、すべてのチェックが成功したとは限りません。変更の影響を受ける可能性のある出力先をすべて検証してください。 既存の値は意図的に設定されていると考え、変更または不具合として指摘する前に、必ず理由を確認してください。 定数、制限値、フラグ、しきい値、文言、パターンを変更または報告する前に、周辺のコンテキストと履歴、呼び出し元の順序、同じ規約を使う2つ以上の兄弟呼び出し箇所を確認してください。理由を示さず WHAT だけを記載したドキュメントは、根拠が不足しているのであって、ガードが欠けている証拠ではありません。 曖昧さは作業に着手する前に明らかにし、黙って解釈を選ばないでください。 妥当な解釈が複数ある場合は、明示的に質問するか、リスクとともに前提を述べてください。 中間状態ではなく、システムが責任を持つ結果を検証してください。 非同期処理を検証する際は、最終的なビジネス状態を確認してください。共有インフラストラクチャが保持する配信や再試行の記録は、同時実行中のどのプロセスからでも書き込めるため、決して検証対象にしないでください。このようなチェックは単独実行では成功しても、インフラストラクチャをほかの処理と共有した途端に不安定になります。 共有ガイダンスは、対象となる役割に関連する内容にしてください。 汎用ガイダンスは、受け取るすべてのスキルやエージェントに役立つものでなければなりません。コード固有の要件は、コード固有のプロトコルにのみ記載してください。

ネストされたタスクの展開契約 — ワークフローのステップから呼び出す場合、[Workflow] ... の行は親コンテナにすぎません。子スキルも、可視のフェーズタスクを作成します。

1. まず現在のタスクリストを取得します。一致するアクティブな親ワークフロー行がある場合は、nested=true を設定して parentTaskId を記録します。ない場合は、単独で実行します。
2. フェーズ作業を始める前に、宣言されたフェーズごとに1つのタスクを作成します。ネストされている場合は、件名の先頭に [N.M] $skill-name — phase を付けます。
3. ネストされている場合は、TaskUpdate(parentTaskId, addBlockedBy: [childIds]) で親をリンクします。
4. オーケストレーターは、子スキルまたはサブエージェントを呼び出す前に、その子スキルのフェーズリストを事前に展開し、ワークフロー行をリンクしなければなりません。
5. 作業開始前に子タスクをちょうど1つ in_progress にし、証拠を記録した直後に completed にします。
6. すべての子タスクが完了するか、理由を明記して明示的にキャンセルされた後にのみ、親タスクを完了します。

以下が完了するまでブロック： 現在のタスクリストの取得、子フェーズの作成、ネストされている場合の親タスクとのリンク、最初の子タスクの in_progress 設定。 プロジェクト参照ドキュメントの確認ゲート — タスク追跡の初期設定後、対象ファイル／ソースファイルの読み取り、grep、編集、分析の前に実行します。プロジェクトのドキュメントは、汎用的なフレームワークの想定より優先されます。

1. 対象範囲を特定します。ファイルの種類、ドメイン領域、操作内容を確認します。
2. まず docs/project-config.json を読みます — プロジェクトの機械可読なマップです。 これはこのリポジトリの唯一の信頼できる情報源です（モジュール／パス、フレームワークと検索キーワード、テスト／E2E／統合テストの実行コマンド、デザインシステム、アーキテクチャルール、ワークフローパターン）。調査、計画、コーディングの前に、正確なパス、実行コマンド、規約の根拠として参照してください。フレームワークの既定値を決して想定しないでください（CLAUDE.md と参照ドキュメントはこれに基づいて作成されています）。これ、またはドキュメントインデックス、lessons.md、CLAUDE.md、AGENTS.md、必須の参照ドキュメントが欠落しているか古い場合は、まず $project-init または対象を絞ったルート（$project-config、$docs-init、$scan-all、$scan --target=<key>、$claude-md-init）を自動実行してください。Codex のミラーまたは AGENTS.md が古い場合は、ユーザーに $sync-codex の実行を依頼してください（自動実行は禁止です）。
3. トリガーごとの必須ドキュメント：常に docs/project-reference/lessons.md；ドキュメント検索時は docs-index-reference.md；レビュー時は code-review-rules.md；バックエンド／CQRS／API 時は backend-patterns-reference.md；ドメイン／エンティティ時は domain-entities-reference.md；フロントエンド／UI 時は frontend-patterns-reference.md；スタイル／デザイン時は scss-styling-guide.md + design-system/design-system-canonical.md；統合テスト時は integration-test-reference.md；E2E 時は e2e-test-reference.md；機能ドキュメント／仕様時は feature-spec-reference.md + spec-system-reference.md + spec-principles.md；動作／公開契約／仕様／テスト／コードの同期時は workflow-spec-test-code-cycle-reference.md；派生した仕様インデックス／ERD／再実装ガイド時は spec-system-reference.md + docs/specs/ 内のソース Feature Specs；アーキテクチャ／新領域時は project-structure-reference.md。
4. 必須ドキュメントをすべて読み、その後、対象作業を始める前に次のように記載します：Reference docs read: ... | Not applicable: ...。

準備完了の条件： 対象範囲を評価済み、docs/project-config.json を参照済み、必須ドキュメントを確認・読了済み、またはセットアップルートを完了済み、lessons.md を確認済み、参照元を明記済み。

タスク追跡と外部レポートの保存 — 実行前にこれを初期設定し、その後、対象／ソース作業の前にプロジェクト参照ドキュメントを先読みします。

1. 対象ファイルの読み取り、grep、編集、分析の前に、小規模なタスク分解を作成します。コンテキストを失った場合は、まず現在のタスクリストを確認します。
2. 作業前にタスクを1つ in_progress にし、根拠を得た直後に completed にします。状態遷移をまとめて行ってはいけません。
3. 計画／レビュー作業では、最初の発見事項を記録する前に plans/reports/{skill}-{YYMMDD}-{HHmm}-{slug}.md を作成します。
4. ファイル／セクション／判断ごとに発見事項を追記し、最後にレポートファイルを基にまとめます。
5. 最終出力には Full report: plans/reports/{filename} を記載します。

作業開始不可の条件： タスク分解が存在し、計画／レビュー作業ではレポートパスが宣言され、次の発見事項に進む前に最初の発見事項が保存されていること。

必ず注意 — 批判的かつ段階的な思考を適用してください。すべての主張には、適切な追跡可能な根拠（リポジトリ／コードに関する主張には file:line、調査、製品、コンテンツ、ドキュメントに関する主張にはソース URL または成果物のセクション）が必要です。確信度が80%を超える場合に行動し、60%未満の場合は推奨しないでください。幻覚防止：推測を事実として提示せず、不確実性は率直に認め、独立して相互参照し、自分の確信度にも懐疑的でいてください。

必ず注意 — AI の誤りを防止してください。生成した内容を根拠と照合し、削除または名前変更の前に下流の参照を追跡し、影響を受けるすべての出力を検証し、コンテキストを失った後はファイルを再読し、行動する前に曖昧さを明示してください。

• 必須 対象作業の前にタスク追跡を初期設定し、状態遷移は一度に1タスクずつ行ってください。

• 必須 計画／レビューの発見事項を plans/reports/ に逐次保存し、ディスク上の内容を基にまとめてください。

• 必須 調査、計画、コーディングを始める前に、docs/project-config.json（モジュール／パス、実行コマンド、規約、アーキテクチャ／ワークフローのルールを記載したプロジェクトマップ）と、必須のプロジェクト参照ドキュメントを読み、「参照ドキュメントを読みました：...」と明記してください。

• 必須 常に lessons.md を含めてください。プロジェクト設定と規約は、汎用フレームワークのデフォルトより優先されます。

• 必須 プロジェクト設定、ルートの指示ファイル、または必須の参照ドキュメントが見つからない、もしくは古くなっている場合は、通常のプロジェクト固有の作業に入る前に、$project-init またはより限定的な下位ルートを自動実行してください。

• 必須 親ワークフローの行で、子フェーズの追跡を代替することはできません。ネストしている場合はフェーズを展開し、親と関連付けてください。

• 必須 オーケストレーターは、呼び出し前に子スキルのフェーズを展開してください。[N.M] $skill-name — phase のプレフィックスを使用し、同時に in_progress にできるタスクは1つにしてください。

プロンプト改善の締めくくりアンカー

重要・必ず遵守 このスキルで定められたステップの順序に従ってください。ユーザーの明示的な承認なしに、ステップを省略、順序変更、統合してはいけません。 重要・必ず遵守 各ステップ／サブスキルの呼び出しでは、実行前に in_progress に設定し、実行後に completed に設定してください。 重要・必ず遵守 スキップしたステップには、すべて明確な理由を記載してください。完了したステップには、簡潔な根拠を必ず添えてください。 重要・必ず遵守 Task ツールが使用できない場合は、同期されたステータスを維持しながら、同等のステップごとの計画トラッカーを使用してください。

並列サブエージェントのディスパッチ — タスクの分解ができたら、実行に入る前に並列化を計画してください。依存関係がないことが明らかなタスクを順番に実行すると、所要時間を無駄にします。このルールは、ワークフローのステップ、計画、バッチ更新、調査、リサーチ、スキャン、レビュー、ドキュメントの同期を含む、複数ステップのすべての作業に適用されます。実行計画はメタデータに基づいて決定し、デフォルトでは並列化しません — 分岐は、計画で宣言された内容（PAR／SEQ タグとフェーズごとの書き込み対象）だけに従ってください。タグのない計画は順次実行します。理由：派生した書き込み対象だけでは、連鎖的な変更や生成される書き込みを検出できないためです。

1. すべてのタスクに PAR または SEQ のタグを付けてください。 PAR は、入力に保留中の他タスクの出力が含まれず、書き込み対象が他のすべての PAR タスクと重複しない場合に限ります。それ以外は SEQ とし、必ず依存関係上の理由を明記してください。
2. PAR タスクをウェーブにまとめてください。 ウェーブ内のタスク間に依存関係があってはいけません。同じファイルへの書き込みを行うタスクを、同一ウェーブに含めてはいけません。読み取り専用の作業（検索、調査、レビュー、リサーチ）は自由に並列化できます。
3. ディスパッチ前に宣言してください： 並列計画：ウェーブ 1 = [...] · ウェーブ 2 = [...] · SEQ = [...]（理由）。
4. 各ウェーブは1つのメッセージで起動してください — spawn_agent の呼び出しはすべて同じ応答内にまとめ、ターンごとに分けて送ってはいけません。各タスクは専門分野に応じて割り当ててください（.claude/skills/shared/sub-agent-selection-guide.md を参照）。汎用の担当者として code-reviewer を使ってはいけません。
5. 各サブエージェントには、自己完結した指示を与えてください： 目標 · 対象範囲と担当ファイル · 参照ドキュメント · 返却形式（要約と Full report: のパスを含め、SYNC:subagent-return-contract に従う） · plans/reports/ への段階的な保存（SYNC:incremental-persistence に従う）。
6. ウェーブごとにバリアを設けてください。 すべてのメンバーから返答があるまで次に進んではいけません（条件付きタスクのスキップも返答として数えます）。結果を統合し、各タスクを完了またはスキップにしてから、次のウェーブを起動してください。変更を伴うステップはバリア後に実行してください。
7. ネストは1階層までです。 ディスパッチされたサブエージェントは、自身に与えられた指示を実行します。それ以上の分岐は、そのエージェントの .claude/agents/*.md 定義で許可されていない限り、オーケストレーターが担当します。

並列化してはいけないもの： 書き込み先が重複するタスク · 保留中のタスクの出力を利用するタスク · 簡単な単一ファイルの作業（ディスパッチのオーバーヘッドが利点を上回るもの） · スキルまたはワークフローで順序が明示的に固定されているもの · ユーザーの承認待ちのゲート。

以下が満たされるまで進行禁止： すべてのタスクに PAR／SEQ のタグが付けられ、SEQ には個別の理由が明記されていること · ウェーブが宣言され、書き込み対象の重複がないことが確認されていること · 各ウェーブが1つのメッセージで起動されていること · 次のウェーブに進む前にバリアが守られていること。

• 必須 タスクを計画した後、各タスクに PAR／SEQ のタグを付け、すべての PAR ウェーブを 1 回のメッセージで並列サブエージェントとして起動してください。ワークフロー、バッチ更新、調査、リサーチ、レビューでは、デフォルトで並列化します。計画の実行では、計画で宣言された作業のみを並列化してください。
• 必須 各ウェーブの書き込み対象は互いに重複させないでください。次のウェーブに進む前に全員の完了を待ってください。専門性に応じて割り当ててください。各自のエージェント定義で許可されていない限り、サブエージェントがさらに作業を並列化することは決してありません。

プロジェクトプロトコルのオーバーレイ — このスキルを実行する前に、このスキルに適用される PROJECT オーバーレイルールを解決してください。プロジェクトのスキルプロトコルインデックス（デフォルトでは docs/project-reference/skill-protocols-reference.md。docs/project-config.json の referenceDocs エントリーでパスが上書きされる場合があります）の Target 列と、このスキル名を照合し、最も具体的に一致する階層のみを適用してください（完全一致 > glob > *）。この優先順位はオーバーレイ同士を順位付けするものであり、このスキルとの優先順位を決めるものではありません。一致した本文のみを読み、<protocols-dir>/<Name>.md として解決してください。行の Body リンクは表示用テキストであり、読み込み先のパスではありません。一致した本文が存在しないか、形式が不正な場合は、その旨を報告してスキップしてください。インデックスの Description から内容を再構成してはなりません。インデックスがない場合、または一致がない場合は、オーバーレイなしでそのまま進め、何も報告しないでください。契約全体については .claude/skills/project-skill-protocol/references/registry.md を参照してください。

オーバーレイは追加のみです。このスキル独自のプロトコルにルールを追加するものであり、既存のルールを置き換えたり、上書きしたり、無効化したり、別の意味に解釈したりすることは決してありません。すべてのオーバーレイを取り除いた場合、このスキルは文書化された動作と完全に同じでなければなりません。オーバーレイは概要であり、権限を引き上げるものではありません。ワークフローのゲート、Git の規律、レビューゲート、ユーザー確認ゲートを免除することは決してできません。オーバーレイとスキルの間に実際の矛盾がある場合、または同じ具体性のオーバーレイ同士が直接矛盾する場合は、両方をユーザーに提示してください。決して黙って解決しないでください。

必ず注意 このスキルを実行する前に、プロジェクトプロトコルのオーバーレイを解決してください。最も具体的に一致する階層のみを適用します（完全一致 > glob > *。これはオーバーレイ同士の順位付けであり、このスキルとの順位付けではありません）。一致した本文のみを <protocols-dir>/<Name>.md から読み込んでください。本文が存在しないか、形式が不正な場合は報告し、決して再構成しないでください。オーバーレイは追加のみ（このスキル独自のルールを置き換えることはありません）であり、概要にすぎず、権限を引き上げるものでは決してありません。同じ具体性のオーバーレイ同士の矛盾は、ユーザーに提示してください。

終了時の確認事項

重要・必ず注意 目標： コード／仕様／テストを変更するたびに、ドキュメントも同期させてください。影響を受ける機能仕様、§8 の TCs、テストコードへのリンク、派生インデックスのすべてに、リリースした動作を反映し、未解決のずれを残さないでください。

適用中のプロトコル（このスキルが含む SYNC／共有ブロックの簡潔な要約）— 以下の各ブロックを必ず守ってください：

• 批判的思考： 批判的かつ順序立てて考えてください。すべての主張には file:line の根拠が必要で、確信度は 80% を超えていなければなりません。
• サブエージェントからの返却： 起動したサブエージェントは要約契約のみを返し、詳細はすべてディスクに保存してください。
• サービス横断チェック： プロデューサー／コンシューマー／サーガ／契約を確認してください。コンシューマーの不足は、気づかれない回帰につながります。
• AI の誤り防止： 生成された内容を根拠と照合し、下流の参照を追跡し、影響を受けるすべての成果物を確認してください。コンテキストを失った後は読み直し、曖昧さを明示してください。
• ネストされたタスクの作成： ネストされた場合も、子フェーズのタスクを展開し、親ワークフローの行にリンクしてください。
• プロジェクト参照ドキュメント： 対象作業の前に、必須のプロジェクト参照ドキュメント（常に lessons.md を含む）を読んでください。
• タスク追跡： タスクを初期化し、アクティブなタスクは 1 つに保ち、調査結果を plans/reports/ に随時保存してください。
• 並列サブエージェントのディスパッチ： タスクに PAR／SEQ のタグを付け、PAR タスクを互いに書き込み対象が重複しないウェーブにまとめ、各ウェーブを 1 回のメッセージで起動し、次に進む前に完了を待ってください。 最重要・厳守 作業に着手する前に、タスク追跡を使って8つすべてのタスクを作成し、その後、固定順序 0 -> 1 -> 2 -> 2.5/2.6 -> 3 -> 4 -> 5 -> final review で実行してください。明示的なユーザーの承認なしに、順序の入れ替え、統合、スキップをしてはいけません。理由：フェーズの順序はドリフトを検出するゲートです。フェーズをスキップすると、気づかれない古い情報がそのままリリースされます。 最重要・厳守 docs-update はルーターのみです。$spec、$spec [mode=tests]、$spec [mode=sync]、$spec-index に委任してください。§8 の内容を記述したり、Feature Spec／派生インデックスファイルを編集したり、サブスキルのロジックを重複させたりしてはいけません。理由：二重管理は2つの情報源の不一致を招きます。 最重要・厳守 スキップはすべて、証拠に基づく判断として扱ってください。根拠を file:line で示してタスクを completed にし、フェーズを黙って省略してはいけません。理由：正当な根拠のないスキップは、更新漏れと区別できません。 厳守 ネストされたタスクの展開契約 — ワークフロー内から呼び出された場合も、タスク追跡を使って内部フェーズを展開し、[N.M] $skill-name — phase のプレフィックスを付け、TaskUpdate(parentTaskId, addBlockedBy: [childIds]) で関連付けてください。理由：ワークフローの行はコンテナであり、フェーズ追跡の代わりにはなりません。 厳守 すべてのステップで、実行前にタスクを in_progress にし、実行後に証拠またはスキップ理由を添えて completed にしてください。遷移をまとめて処理せず、常にアクティブなタスクを1つだけにしてください。 厳守 タスク管理ツールが利用できない場合は、同等の8ステップのプラン追跡を使用し、各ステップのステータスを同期させてください。 厳守 証拠ゲート — すべての主張、検出したモジュール、影響の対応付けには、file:line または git diff による証拠が必要です。行動に移すには確信度が80%を超えている必要があり、60%未満の場合は行動してはいけません。「Module unchanged」は証拠がなければ有効なスキップ理由になりません。理由：推測に基づくと、誤ったドキュメントに更新を振り分け、実際のドリフトを見逃します。 厳守 ドキュメントの形式を判断する前に、既存パターンを検索してください。対象バケットの既存の Feature Spec／INDEX のレイアウトと、プロジェクト参照ドキュメントを読み、docs/project-config.json からモジュールマップを作成してください。ハードコードされたスキルパスを使ってはいけません。理由：汎用的な想定より、各プロジェクトのドキュメント規約が優先されます。 厳守 近くのパターンを再利用する前に、適合性を評価してください。バックエンドとフロントエンドの両方に変更があるモジュールは、2件ではなく重複を除いた1件として扱います。変更が実際に動作を変えることを確認してから $spec に振り分けてください。理由：重複した呼び出しや動作に影響しない呼び出しは、処理を無駄にし、監査記録を損ないます。 厳守 あいまいな振り分けの判断は、ユーザーに直接質問して確認してください。選択肢を示し、どのフェーズを実行するかを黙って自動判断してはいけません。 厳守 技術に依存しない出力 — spec／specs／README／INDEX を更新する際、本文や見出しにフレームワーク／製品／言語／パターンの名前を含めてはいけません。まず論理 ID（FR-／BR-／OP-／TC-）を更新し、その後に本文を更新してください。証拠フィールドの例外は維持してください。理由：本文は移植可能な契約であり、証拠の記録先には物理的な座標が保持されます（spec-principles §3）。 厳守 Step 2.4 の最終コード↔仕様同期検証は、変更対象の各モジュールで実施してください。削除または弱体化された [HARD] BR がコードと仕様の矛盾を生じさせている場合、解決するかオーナーが承認するまで完了できません。AC のドリフトがあれば $spec を再実行し、TC のドリフトは $spec [mode=sync] に振り分けてください。 厳守 Phase 1 のプロジェクトコンテキスト同期は、影響マップが空でない限り必ず実行してください。マップを作成し（node .claude/scripts/doc-impact-map.cjs）、振り分けられた docs/project-reference/** のドキュメントと docs/project-config.json のセクションを並列ウェーブで確認し、振り分けられた各ドキュメントに判定（FRESH | PATCHED | RESCAN REQUIRED | UNVERIFIED）を付けてください。影響範囲に限定したパスでは、Last scanned のスタンプを更新してはいけません。理由：これらのドキュメントは、後続のあらゆる AI コンテキストに使用されます。確認されていないドキュメントは FRESH ではなく UNVERIFIED です。また、スタンプを更新すると、60日ごとの全件再スキャンのゲートが気づかれないまま無効になります。 厳守 Phase 0 のトリアージは必ず最初に実施してください（git diff → 分類 → モジュールの重複排除 → 既存ドキュメントの状態を記録）。Phase 2 の $spec は §1～§7 を更新し、変更されたモジュールに機能の動作があるのに Feature Spec がない場合は、ドキュメント先行の手順に進まずブロックしてください。理由：トリアージまたはドキュメント先行ゲートを省略すると、文書化されていない動作がリリースされます。 厳守 Phase 2.5 の $spec-index [mode=index] は、Feature Specs から派生バケット INDEX／ERD を任意で更新します（A-E ツリーを再抽出することはありません）。Phase 2.6 の $tech-spec は、派生した技術ビューを任意で更新／監査します。Phase 3 の $spec [mode=tests] は §8 の TCs を同期します。Phase 4 の $spec [mode=sync] は、§8 の TCs と実行されるテストコードを同期します（QA ダッシュボードはありません）。 厳守 .claude のスキル／フック／ワークフロー／同期ツールに変更がある場合は、生成されたミラーの同期状態（npm run codex:sync が完了した、または明示的に N/A）を記録してください。docs-update はこの確認を振り分けて報告しますが、生成されたミラーを直接編集してはいけません。 厳守 Phase 5 の要約レポートと最終レビュータスク（#8）は、必ず plans/reports/docs-update-{YYMMDD}-{HHMM}.md に作成してください。レポートは監査証跡であり、レビューでは影響を受けるすべてのドキュメントが更新され、正当な根拠のないスキップがないことを確認します。 合理化への対策：

回避策	反論
「ドキュメント／設定だけの変更だから、すべてのフェーズをスキップする」	それでもフェーズ 0 のトリアージを実行してください。早期終了は決定であり、前提ではありません。
「.claude/** だけの変更だから、ツール関連の変更だし、早期終了する」	ハーネスの編集は、CLAUDE.md／docs-index／project-structure にある glob から導出されるインベントリの件数とカタログを古くします。フェーズ 1 は必ず実行してください。スキップするのはフェーズ 2～4 だけです。
「参照ドキュメントは問題なさそうだった」	「問題なさそう」は確認ではありません。そのドキュメントに割り当てられたチェックを実行するか、UNVERIFIED と報告してください。
「ドキュメントを更新したので、Last scanned も更新しておく」	このスタンプを更新できるのは、完全な $scan --target=X だけです。影響範囲を限定したパッチでは Last verified を記録し、既存の Last scanned スタンプがある場合に限って更新してください。
「project-config.json は十分近い内容になっている」	根拠に基づいて、指摘されたセクションを再導出してください。変更したすべての pathRegex が実在するファイルに一致することを証明し、スキーマ検証を実行してください。
「マッパーが割り当てなしのファイルを返した。何もすることはない」	割り当てなしとは、ルーターにルールがなかったという意味であり、ドキュメントが最新だという意味ではありません。それぞれを手作業で分類してください。
「機能ドキュメントがないから、フェーズ 2 はスキップする」	理由を記載してタスクを完了済みにしてください。決して黙って省略しないでください。
「モジュールに変更がないから、サブスキルはスキップする」	file:line の根拠を示してください。証明がなければスキップできません。
「何が変わったかはすでに分かっている」	それでも git diff を実行してください。部分的な把握では更新を見落とします。
「フェーズ 5 のレポートは不要」	必ずサマリーレポートを作成してください。これは監査証跡です。
「タスクはあとで更新する」	無効です。各ステップの前後に、リアルタイムでタスクのステータスを変更してください。
「先にスキルを実行してからタスクを作成する」	無効です。まずタスクを作成して追跡し、その後にステップスキルの呼び出しを実行してください。
「§8 の TC は自分で書く。そちらのほうが速い」	無効です。ルーターのみを使用してください。$spec [mode=tests] に委任してください。複数の作成者がいると内容が食い違います。
「[HARD] BR は弱められたが、テストは通る」	ブロックしてください。コードと仕様の矛盾です。解決するか、オーナーの承認を得てください。決してそのまま通さないでください。
重要：必ず注意してください：何らかの作業に着手する前に、タスク追跡（または同等のトラッカー）で8件すべてのタスクを作成し、各ステップの進捗をリアルタイムで記録してください。着手前に in_progress、完了後に根拠を添えて completed にします。
重要：必ず注意してください：ルーターのみを担当してください。§8／Feature Spec／派生インデックス／派生テクニカルビューへの書き込みはすべて委任し、ここでは絶対に作成しないでください。理由：二重に作成すると、仕様と生成されたビューの内容が食い違います。
重要：必ず注意してください：スキップする場合はすべて、file:line の根拠と理由を添えて、該当タスクを completed にしてください。固定されたフェーズ順を実行し、フェーズを黙って省略しないでください。

Hookless Prompt Protocol Mirror（自動同期）

ソース：.claude/.ck.json + .claude/skills/shared/sync-inline-versions.md（:full ブロック）+ .claude/scripts/lib/hookless-prompt-protocol.cjs

[WORKFLOW-EXECUTION-PROTOCOL] [BLOCKING] ワークフロー実行プロトコル — 必須・重要・絶対遵守。理由を問わず省略しないでください。

汎用的な移植性の境界： 再利用可能なスキルとプロトコルのテキストはプロジェクトに依存しないものとします。プロジェクト固有の規約は docs/project-config.json と docs/project-reference/ から確認してください。共有の AI-SDD は shared/sdd-artifact-contract.md に従って適用します。docs/project-config.json と docs/project-reference/docs-index-reference.md を読み、そこに記載されたプロジェクト参照ドキュメントを開いてください。仕様、テストケース、動作変更、公開契約、または docs/specs/ に関する作業では、docs index で指定されたローカルの仕様ドキュメント（feature-spec-reference.md、spec-system-reference.md、spec-principles.md、および仕様／テスト／コードの同期が必要な場合は workflow-spec-test-code-cycle-reference.md）を経由してください。いずれかのファイルまたは必須の参照ドキュメントが欠落している、あるいは古い場合は、通常のプロジェクト固有の作業に着手する前に $project-init（または $project-config、$docs-init、$scan-all、$scan --target=<key> など、より範囲の狭い下位ルート）を自動実行してください。共有コンテキストとローカルドキュメントが利用可能であれば、サポート対象の AI ツールで実行できます。

1. 検出： プロンプトが明示的なスラッシュ形式のスキル／ワークフローコマンドで始まる場合は、それを直接実行してください。それ以外の場合は、ワークフローカタログとスキル一覧に照らしてプロンプトを判定してください。
2. 分析： 最適な選択肢を決定してください。直接実行、スキルの呼び出し、標準ワークフローの開始、またはカスタムステップの組み合わせです。
3. 自動選択： 最適な選択肢を自分で選んでください。直接実行、スキル、標準ワークフロー、カスタムワークフローのどれにするかをユーザーに尋ねないでください。
4. 開始： ワークフローを選んだ場合は $start-workflow <workflowId> を呼び出し、スキルを選んだ場合はそのスキルを呼び出し、カスタムワークフローの場合はカスタムステップを順に実行し、直接実行の場合はタスクに着手してください。
5. タスクの作成： 選択した経路に複数のステップがある場合は、実行前にワークフロー／スキル／カスタムステップのすべてをタスク追跡に登録してください。
6. 並列化： タスクリストを実行する前に、各タスクに PAR（独立した入力を使い、他のすべての PAR タスクと書き込み対象が重複しない）または SEQ（依存するブロック対象を明記）を付け、PAR タスクをウェーブにまとめ、ウェーブ計画を宣言してください。各ウェーブのサブエージェントは1回のメッセージで起動し、ウェーブ内のすべてのサブエージェントが戻るまで待機してください。サブエージェント自身の定義でさらに分散実行が認められている場合を除き、ファンアウトは1階層にとどめてください。独立したタスク、共有の書き込み対象があるタスク、後続の入力として出力を使うタスク、単一ファイルの簡単な作業、スキルまたはワークフローで順序が明示されているタスク、ユーザー承認が必要なタスクは並列化しないでください。デフォルトで逐次実行するのは不備です。独立したタスクは並列化してください。
7. 実行： コンテキストの指示にある ワークフローのステップ進行と並列フェーズ のルールに従ってタスクを進めてください。ステップの進行はモデルが判断します。サブエージェントの完了はインライン呼び出しと同様にステップを進めます。並列フェーズのグループは、全員の応答が揃うまで待つバリアです。すべてのメンバーが戻るまで次へ進まず、並列フェーズを逐次化しないでください。

共有 AI-SDD プロトコルマーカー

ソース：.claude/skills/shared/sync-inline-versions.md

SYNC:ai-sdd-artifact-contract

AI-SDD 成果物契約 — 共有する仕様駆動開発のルールは、移植可能な状態に保ち、ソース側で管理します。

1. 再利用可能な AI-SDD の原則は .claude に置き、リポジトリ固有のパス、コマンド、担当者、製品、形式はプロジェクト設定または参照ドキュメントに記載します。
2. サイクルを維持します：spec -> plan -> tasks -> implement -> verify -> update spec/docs。
3. すべての要件または不変条件を、判断、タスク、TC／テスト、ソースの根拠、ドキュメント／仕様の更新まで追跡します。
4. コードから仕様への抽出は、正規の仕様オーナーが承認するまでは参照専用として扱います。
5. 同期されたコンテキストがあれば、サポート対象の AI ツールで計画、実装、レビュー、検証を行えます。複数のツールを使うかどうかは任意です。
6. まず .claude のソースを更新してから、生成されたミラーを同期します。.agents、.codex、AGENTS.md を手動で編集しないでください。— 理由：ミラーは生成された成果物であり、次回の同期時に手動編集内容が上書きされます
7. docs/project-config.json、ルートの指示ファイル、または必須のプロジェクト参照ドキュメントが欠落しているか古い場合は、通常のプロジェクト固有の作業を行う前に、$project-init または適切な下位レベルの手順を自動実行します。

有効な参照先： アクティブなスキルルート内の shared/sdd-artifact-contract.md。

---

SYNC:ai-sdd-artifact-contract:reminder

• 必須 shared/sdd-artifact-contract.md を適用し、再利用可能な AI-SDD は .claude に、ローカルルールはプロジェクトのドキュメントに保持します。
• 必須 コードから仕様への抽出は、正規の承認を得るまで参照専用です。サポート対象の AI ツールであれば、同期されたコンテキストを使って実行できます。
• 必須 生成されたミラーを同期する前に .claude のソースを更新します。.agents、.codex、AGENTS.md を手動で編集しないでください。
• 必須 プロジェクト設定、ルートの指示ファイル、または必須の参照ドキュメントが欠落しているか古い場合は、プロジェクト固有の作業を $project-init または適切なセットアップ手順に自動的に振り分けます。 [TASK-PLANNING] [必須] ワークフローまたはスキルの手順を実行する前に、計画したすべての手順についてタスク追跡を作成／更新し、各手順の開始時と完了時に同期してください。

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

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

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

1. 症状ではなく、失敗モード（推論や前提の誤り）を特定します。「間違った enum 値を使った」ではなく、「ソースを読まずに API が存在すると仮定した」とします。
2. 一般性を確認します。この失敗モードは 3 つ以上の状況／コードベースに当てはまりますか？当てはまらない場合は、もう一段階抽象化します。
3. 普遍的なルールとして記述します。プロジェクト固有の名前、パス、クラスを取り除きます。どのコードベースでも役立つ内容にします。
4. 統合します。同じ失敗モードに起因する複数のミスは、1 つの教訓にまとめます。
5. 再発ゲート：「このリマインダーがなければ、今後のセッションで再発するか？」いいえ → $learn は省略します。
6. 自動修正ゲート：「$code-review／$code-simplifier／$security-review／$lint で検出できるか？」はい → 代わりにレビュー用スキルを改善します。
7. 両方のゲートを通過した場合は、ユーザーに $learn の実行を依頼します。 [CRITICAL-THINKING-MINDSET] 批判的思考と段階的思考を適用します。あらゆる主張に追跡可能な証拠を求め、行動する際は確信度を 80% 超とします。 ハルシネーション防止の原則： 推測を事実として提示しないでください。すべての主張に出典を示し、不確実性を率直に認め、出力に誤りがないか自己確認し、独立した情報源と照合し、自分の確信を疑ってください。証拠のない確信が、あらゆるハルシネーションの根本原因です。 AI の注意力の原則（初頭効果・新近効果）： 長いプロンプト／プロトコルでは、最も重要なルールを上部と下部の両方に 3 つずつ配置し、長いコンテキストでも指示への準拠を維持します。 目標主導の実行： まず成功基準を定め、検証できるまで繰り返し、観察可能なチェックに合格した場合にのみ終了します。 テストは意図を検証します： テストは現在の動作をなぞるだけでなく、ビジネスルールや不変条件を保護し、保護対象の意図が崩れたときに失敗する必要があります。

よくある AI のミスを防ぐ（システムの教訓）

• コンテキスト圧縮後はファイルを再読込してください。 編集するには、同じコンテキスト内で事前に Read している必要があります。圧縮によって読込状態は消去されます。編集前に再読込してください。
• 一括置換後は古い用語を grep してください。 AI は検索・置換の完全性を過信します。一括編集後はリポジトリ全体を grep し、ドキュメント／設定／カタログに参照漏れがないか確認してください。
• 削除前に下流の参照を確認してください。 削除の影響は、ドキュメントやコードの陳腐化へ連鎖します。削除前に参照元ファイルを洗い出してください。
• 記憶を失った後、新しく作成する前に既存の状態を確認してください。 圧縮によってこれまでの作業の記憶が消去されます。作業を再開するときは現在の状態を確認し、決してむやみに重複作成しないでください。
• AI 生成コンテンツは実際のコードと照合してください。 AI は API、クラス名、メソッドシグネチャを幻覚することがあります。ドキュメントへの記載や参照の前に、grep して実在を確認してください。
• 編集後は依存関係を最後までたどってください。 定義を変更しても、その下流の利用箇所を見落とすことがあります。依存関係をすべてたどってください。
• 名前を変更するときは、利用側の全ファイル形式を grep してください。 ファイル形式によっては、参照先が見つからなくてもエラーなしで無視されます。コード、テンプレート、設定、生成ファイルを検索してください。
• 正しさを検証するときは、すべてのコードパスをたどってください。 コードが存在することと、実行されることは同じではありません。正常系だけでなく、早期リターン、エラー分岐、条件によるスキップもたどってください。
• ソースが変わったら、正規データを埋め込んでいるドキュメントも更新してください。 派生データ（ワークフロー、スキーマ、設定など）を直接記載しているドキュメントは、気づかないうちに古くなります。ソースと合わせて、該当する埋め込みドキュメントをすべて更新してください。
• コンテキスト復旧後は、サブエージェントの結果を検証してください。 親エージェントが圧縮されている間にバックグラウンドエージェントが完了している場合があります。完了したはずだと信じず、出力を grep して確認してください。
• 対象の全一覧とサブエージェントへの割り当てを照合してください。 カテゴリごとにサブエージェントを並行実行すると、境界上の項目を見落とすことがあります。作業を進める前に、割り当ての和集合を対象一覧と照合してください。
• サブエージェントが引き継ぐ知識は、そのエージェントの .md 定義に書かれた内容だけです。組み込みの Explore ではなく、カスタムエージェント種別を使用してください。 ツールの採用には、権限＋知識＋適用（番号付きワークフロー手順）が必要です。
• サブエージェントの調査結果は最後にまとめてではなく、随時保存してください。 長時間実行されるサブエージェントは、最終書き込み前に打ち切られることがあり、調査結果が失われます。報告ファイルにセクションごとに追記するよう指示してください。
• デバッグ時は修正する前に「どちらの責任か」を確認してください。 呼び出し元（データが誤っている）と呼び出し先（処理が誤っている）をたどり、責任のある層を修正してください。症状が表れる箇所だけを修正してはいけません。
• テスト失敗時は、追跡や編集の前に暫定判定を記録してから調査してください。 次の 5 つの分類をすべて使ってください。SOURCE-WRONG（本番コードが意図に反している）、TEST-WRONG（アサーション／セットアップが古くなっている）、TEST-NOT-OPTIMAL（妥当だが脆弱、または情報量の少ないテスト）、ENVIRONMENT-BLOCKED（外部状態のため判定できない）、AMBIGUOUS（意図や証拠から安全に選べない）。その後、根本原因をたどり、適用される仕様（存在する場合は docs/specs/**）とソースの両方に照らして検証してください。成功を無理に得るために、アサーションを弱めたり、スキップを追加したり、タイムアウトを緩めたり、ソースを変更したりしてはいけません。
• 抽出／リファクタリング後は、削除した名前をすべて grep してください。 主要ファイルの作業完了は、他のファイルもクリーンであることを意味しません。完了を宣言する前に、対象範囲全体で削除したシンボルを一つずつ grep してください。
• 既存の値には意図があると考え、変更したり不具合だと指摘したりする前に、必ず理由を確認してください。 パターンマッチで「誤り」と決めつけると、背景を見落とします。定数／上限／フラグ／しきい値を変更または報告する前に、コメント、git blame、呼び出し元の処理順序（値を正しくする保証は、通常、該当行の直前に実行されるコードにあります）、同じ規約を使っている 2 つ以上の類似した呼び出し箇所を確認してください。理由なしに WHAT（何をするか）だけを記したドキュメントは、根拠が欠けているのではなく、WHY（なぜそうするか）の説明が不足しているということです。検証作業でも、正確な file:line の引用が証明するのは転記が正確であることだけであり、不具合の存在ではありません。
• 最初の出力だけでなく、影響を受けるすべての出力を検証してください。 一つのビルドが成功しても、すべてが成功したとは限りません。複数のスタックにまたがる変更（バックエンド／フロントエンド／テスト／ドキュメント）では、すべての出力を検証してください。
• 近くにあるパターンをコピーする前に、適合性を評価してください。 最も近い例が適合するとは限りません。新しいコンテキストが同じ制約、基底クラス、スコープ、ライフタイムを共有するか確認してください。
• デバッグでは全体を優先し、目についた箇所に飛びつかないでください。 最初に思いついた原因へすぐ飛びつかないでください。前提条件（設定、環境変数、パス、DB、エンドポイント、認証情報、バージョン、DI、データ）をすべて列挙し、それぞれを証拠（推論ではなく grep／クエリ）に照らして検証してください。「何があればこの仮説は否定されるか？」と問い、何も答えられないなら、それは仮説ではありません。最もコストの高い失敗は、バグが一度も疑われていない層にあるのに、「明らか」だと思い込んだ層をさらに深掘りすることです。
• 変更は最小限にし、差分テストを適用してください（コンテキストに合わせて判断）。 2 つのモードがあります。（1）バグ修正 → すべての行がバグに直接関係するようにし、スタイル変更はしないでください。不要になったインポートを削除してよいのは、あなたの変更によって不要になったものだけです。（2）レビュー／機能強化 → 改善を実装し、「主な依頼を超える機能強化：[内容]」と明示してください。黙ってスコープを拡大しないでください。差分テスト：「X を依頼されていなかったとしても、この行は存在していたか？」いいえなら、削除するか明示してください。
• 実装前に曖昧さを明らかにし、黙って解釈を選ばないでください。 複数の妥当な解釈がある場合は、それぞれの工数とともに提示してください。「[依頼] は（1）[N 時間]、（2）[N 時間]のいずれかと解釈できます。どちらが重要ですか？」まずスコープ／形式／量／制約に関する前提を列挙してください。より簡単な方法がある場合は、そのことも伝えてください。黙って選ばないでください。
• [必須の最初のアクション] 応答する前に、必ず適切なスキルまたはワークフローを有効にしてください。 ワークフローカタログとスキル一覧に照らしてタスクを確認し、スキルの呼び出し、または $start-workflow <workflowId> で実行してください。確認する前に回答やコード作成をしてはいけません。省略はプロトコル違反です。
• Why-Review の敵対的な視点は、計画、判断、設計をレビューするときに適用してください。 基本姿勢は VALIDATOR（妥当性を確認する側）ではなく SKEPTIC（懐疑的な側）です。却下された代替案の最も強い論拠を組み立て、述べられた理由を一つずつ逆転させて「何を犠牲にするのか」を問い、上位 2～3 個の前提をストレステストし、プレモーテム（「リリースしたが 3 か月後に失敗した。何が壊れたのか？」）を行い、作成者が見落とした代替案を 1～2 個提示してください。セクションがあるだけでは十分ではありません。重要なのは、因果関係に基づく推論、具体的な軽減策、証拠です。「より良い」や「注意深く監視する」だけでは不十分です。
• 大規模なレビューでは、サブエージェントへのプロンプトで報告書の書き込みを最初に行わせてください。 多数のファイルを扱うサブエージェントは、最終書き込みの前に予算を使い切り、調査結果を失うことがあります。プロンプトは、（1）報告書の書き込みを最初に明示する成果物とする、（2）まとめてではなくファイル／セクションごとに追記する、（3）読み込みで予算を使い切らないようスコープを限定する、という構成にしてください。報告ファイルを残さず文の途中で打ち切られた場合は、同じプロンプトを再試行せず、より狭いスコープで再実行してください。
• コンテキスト圧縮後は、続行する前に以前の各フェーズの結果をすべて再検証してください。 要約が示すのは意図であり、環境の状態（git のインデックス、ファイルシステム、プロセス）ではありません。再開時はまず git status を確認し、変更したファイルを再読込し、ファイルシステムを検証してください。証拠で確認されるまでは、「完了した」という主張もすべて未検証の仮説です。
• OOM／メモリ：行サイズより先に行数を確認してください。 次の順にトリアージします。（1）上限のないクエリ — 条件を設定するトリガーとなる DB フィルターがありませんか？ DB 側にフィルターを移せば、OOM を解消できます。（2）行サイズが大きいですか？ プロジェクションを使えば比例して減らせます。費用対効果では、プロジェクションより行数削減が優先です。
• システムが担う最終結果をアサートし、インフラストラクチャが担う中間状態をアサートしないでください。 非同期処理（キュー／ブローカーへの配信、再試行、バックグラウンドジョブ、キャッシュ、レプリケーション）をテストする場合は、最終的なビジネス／エンティティの状態をアサートしてください。配信の記録、つまり消費／送信ステータス、試行回数、最終エラー、ブローカー、スケジューラー、outbox／inbox テーブル内の行の有無や件数をアサートしてはいけません。この記録は共有インフラストラクチャに存在し、並行して動く任意のプロセス（別のワーカー、2 つ目のレプリカ、残っているローカルコンテナー）から書き込めるうえ、通常は決定的な共有キーが使われます。そのため、こうしたアサーションは気づかないうちにシステムではなく開発者の環境をテストします。単独実行では成功しても、同じブローカー＋データベースをほかの何かが共有した途端に不安定になります。すべてのアサーションで、次の判定の問いを使ってください。「どのプロセスが処理しても、この結果は成り立つか？」いいえなら、代わりに収束後のデータ状態をアサートしてください。系として、プロセスローカルな障害注入やプロセス内テレメトリーを、任意のプロセスが実行する処理のゲートとして使うことはできません。負荷増幅に使ってください（有効化 → 範囲を限定した時間枠 → 無効化 → 収束をアサート）。前提条件として使ってはいけません。
• ドメイン概念を汎用／共有／インフラストラクチャ層に持ち込まないでください。 再利用可能な層（共有ライブラリ、フレームワーク、インフラモジュール）は、利用側に固有のドメイン概念（テナント／顧客／製品 ID、ビジネスエンティティ、機能ルール）を一切参照してはいけません。漏れがコンパイルされ、実行されると、再利用可能なはずの層が一つの利用側と結合していても、レビューで気づかれずに通過してしまいます。共有型からドメイン情報を排除し、サブクラス化／コンポジションを通じて、ドメインフィールド／ロジックを利用側へ移してください。理由：一つの利用側のドメインに結合した層は、もはや再利用可能ではありません。