code-review

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 ツールが利用できない場合は、同じステータス遷移を反映した、同等のステップごとの計画トラッカーを作成し、維持してください。

クイックサマリー

目標： レビュー済みコードが正しく、変更しやすく、規約に沿っており、受け入れや引き継ぎの前に検証済みであることを確認します。そのために、検証を伴うフィードバックを受け取り（形だけの同意ではなく）、code-reviewer サブエージェントを通じて対象を絞った体系的なレビューを依頼し、完了を主張する前に検証ゲートを適用します。

ルーティング境界： ユーザーが現在の変更、未コミットの作業、ステージ済み／未ステージの差分、またはブランチ間の差分のレビューを求めている場合は、代わりに changes-review を使用してください。

共有エンジン（同期を維持してください）： code-review と changes-review は、同じ review-protocol SYNC: ブロックを共有します。正規のソース：.claude/skills/shared/sync-inline-versions.md；ポリシー：SYNC:shared-protocol-duplication-policy。一方のスキルで共有ブロックを変更した場合は、正規ファイルともう一方のスキルも更新し、両者が決してずれないようにしてください。スキルの違いは開始意図（明示的なスコープ／フィードバック／完了ゲートと Git 差分）のみであり、レビュー品質ではありません。

必須 レビューの前に、プロジェクト固有の参考ドキュメントを検索してください。

コーディング規約 — 検索対象：code-review-rules、coding-standards、style-guide、contributing アーキテクチャ — 検索対象：patterns-reference、architecture、adr テスト規約 — 検索対象：integration-test-reference、test-guide、test-conventions デザインシステム — 検索対象：design-system、design-tokens、component-library

見つかったドキュメントは、レビューの前に読んでください。見つからない場合は、ファイル拡張子やディレクトリ構造から技術スタックの知識を活用してください。

ワークフロー：

1. レビュー報告書の作成 — plans/reports/code-review-{date}-{slug}.md を初期化します
2. フェーズ 0：影響範囲 — .code-graph/graph.db が存在する場合は、まずグラフ分析を実行します
3. フェーズ 0.1：変更コンテキストとフルパイプラインへの影響追跡（理解優先を必須とする） — 変更コンテキストを記録してから、影響を受ける主要領域のフルパイプラインを、両方の境界（クライアント↔サーバー層（FE↔BE）およびサービス／イベント／外部）にわたって全体的に追跡し、各接点／タッチポイントを NONE／ADDITIVE／BREAKING に分類します（単一層またはモノリスの場合は、該当なしであることを明記します）
4. フェーズ 0.3：リスク検出 — 依存関係、マイグレーション、バス／イベント、API、セキュリティ、設定、インフラのリスクを検出します
5. フェーズ 0.5：計画との整合性 — 有効な計画がある場合は、変更ファイルとテストを計画と照合して確認します
6. フェーズ 0.7：サーフェス検出 — 言語＋ディレクトリの意味＋変更の性質に基づいてファイルを分類し、サブエージェントに振り分けます。フロントエンド／UI ファイルがある場合は $ui-review を呼び出します
7. フェーズ 1：ファイルごとのレビュー — 各ファイルをレビューし、正確性、規約、DRY、意図、テスト、ドキュメントの確認結果で報告書を更新します
8. フェーズ 2：全体レビュー — 蓄積した報告書を読み直し、全体的なアプローチ、アーキテクチャ、重複、境界をまたぐ動作を評価します
9. フェーズ 3：最終結果 — 全体評価、重大な問題、推奨事項、古くなったドキュメント、テストの不足を報告書に反映します
10. 修正ループ：検証 → 修正 → 全面再レビュー — 指摘事項がある場合は、まず妥当性を検証し、検証済みの指摘のみを修正してから、修正サイクルの後にレビュー全体を最初からやり直します

主なルール：

• 報告書主導： 報告書を段階的に作成し、全体像をつかむために読み直します
• まず検出： 利用可能な場合はグラフによる影響範囲分析を実行し、レビューに入る前に変更の種類とファイルのサーフェスを分類します
• コードを変更しやすく： 将来の変更コストをコード品質の主要な指標として扱います。DRY、SOLID、抽象化、パターンは、変更による波及を抑える場合にのみ活用します
• 形だけの同意は禁止： 技術的な評価のみを行います（「そのとおりです！」は禁止）
• 検証ゲート： 完了を主張するには、根拠が必要です
• 現在の差分は別の場所でレビュー： 現在の変更、ステージ済み／未ステージの差分、ブランチ間の差分には changes-review を使用します
• レビューが問題なく完了したら、レビューを終了します。 検証や修正の前に、既知の指摘事項を改めてレビューするためだけに、別のコンテキストで時間を費やさないでください。対象に変更が加わった後にのみ再レビューします。

コードレビュー

3 つの実践事項：技術的な厳密さをもってフィードバックを受けること、code-reviewer サブエージェントを通じて体系的なレビューを依頼すること、完了を主張する前に検証ゲートを徹底すること。

変更した関数について python .claude/scripts/code_graph query tests_for <function> --json を実行し、カバレッジの不足を見つけます。

レビューの心構え（必須）

懐疑的であること。すべての主張には、追跡して確認できる証拠 file:line が必要です。行動に移すのは、確信度が 80% を超えてからです。

• コードが正しいと鵜呑みにしてはいけません。呼び出し経路を追跡します。
• file:line の証拠（grep の結果、読み取りによる確認）がない指摘を含めてはいけません。
• 常に「これは本当に動作するか？」と問い、追跡して確認します。「これがすべてか？」と問い、サービス横断で grep します。
• 常に副作用を検証します。承認する前に、利用側と依存先を確認します。

第一原則 — 変更しやすさ

あらゆるコーディング上の判断の成功指標は、将来の変更コスト です。 DRY、SRP、抽象化、デザインパターン、命名、レイヤー化、テストなど、 すべての手法は、次の変更をより低コストにするという 1 つの目標のためにあります。

コード、リファクタリング、テスト、抽象化を評価するときは、次のように問いかけます。 これは次の変更のコストを下げるか、それとも上げるか？

• 変更コストを上げる「ベストプラクティス」は退けます（時期尚早な抽象化、 憶測に基づく汎用化、漏れのある間接化、見返りのない形式主義）。
• 指摘では、真の敵を明示します。結合、隠れた状態、重複した知識、 不明瞭な意図、早すぎる段階で露出する取り消し不能な判断です。
• 将来のライブラリ変更の影響範囲を局所化できる場合は、たとえば コンポーネント／サービスの入出力契約など、プロジェクトが所有する境界を優先します。 変更コストを下げずに形式主義を増やすだけのパススルーラッパーは退けます。
• 変更しやすいシンプルな設計は、変更しにくい洗練された設計に勝ります。

以下の個別ルール、パターン、チェックリストを適用する前に、この観点を当てはめます。 後続のルールが変更コストを上げる場合は、この原則を優先します。

---

基本原則（すべて徹底）

原則	ルール
YAGNI	仮定上の問題を解決するコード（未使用のパラメーター、憶測に基づくインターフェース）を指摘します。
KISS	不必要な複雑さを指摘します。「もっとシンプルな方法はないか？」
DRY	類似コードや重複コードを grep します。類似パターンが 3 つ以上あれば、抽出を指摘します。
Clean Code	巧妙さより読みやすさを優先します。名前で意図を明らかにします。関数は 1 つのことだけを行います。ネストは 3 階層以下、メソッドは 30 行未満です。
Convention	違反を指摘する前に、既存の例を 3 つ以上 grep して確認する必要があります。教科書的な規則より、コードベースの規約を優先します。
No Bugs	ロジックの経路を追跡します。エッジケース（null、空、境界）を検証します。エラー処理を確認します。
Proof Required	すべての主張に file:line の証拠を添えます。推測は禁止です。
Doc Staleness	変更したファイルを関連ドキュメントと照合します。古くなった更新や不足している更新を指摘します。

社会的な配慮より技術的な正しさを優先します。 実装する前に検証します。主張する前に証拠を示します。

グラフを活用したレビュー（graph.db が存在する場合に推奨）

1. python .claude/scripts/code_graph graph-blast-radius --json — 影響度の高いファイルから優先します（依存先が多いものを先にします）
2. python .claude/scripts/code_graph query tests_for <function_name> --json — 変更された関数のうち、テストされていないものを特定します
3. python .claude/scripts/code_graph trace <file> --direction downstream --json — 下流への影響を確認します（イベント、バス、サービス間の連携）
4. python .claude/scripts/code_graph trace <file> --direction both --json — コントローラー／コマンド／ハンドラーの処理フロー全体を確認します
5. 影響範囲が広い（影響を受けるノードが 20 超）場合は高リスクです。レポートに記載してください。

レビュープロセス（レポート主導の 2 段階方式 — 重要）

最初に必ず実施：Todo タスクの作成

Task	Status
[Review] Create report file	in_progress
[Review Phase 0] Run graph blast-radius if available	pending
[Review Phase 0.1] Note change context + holistic full-pipeline trace across BOTH boundaries — client↔server tier (FE↔BE) AND service/event/external — classify each seam/touchpoint NONE/ADDITIVE/BREAKING (MANDATORY comprehension-first; N/A for single-tier/monolith)	pending
[Review Phase 0.3] Detect high-risk change types	pending
[Review Phase 0.5] Plan compliance check (skip if no active plan)	pending
[Review Phase 0.7] Detect categories + route sub-agents	pending
[Review Phase 0.7b] $ui-review sub-review — skip if no frontend/UI files in changeset	pending
[Review Phase 1] File-by-file review + update report	pending
[Review Phase 2] Holistic assessment	pending
[Review Phase 3] Final findings, docs triage, and test sync findings	pending
[Review Fix Loop] Validate findings, fix validated issues, and full re-review if fixes are applied	pending
[Review Final] Consolidate all rounds	pending

ステップ 0：レポートファイルの作成

plans/reports/code-review-{date}-{slug}.md を作成し、「スコープ」と「レビュー対象ファイル」のセクションを設けます。

フェーズ 0：グラフによる影響範囲の分析（利用可能な場合は最初に実施）

.code-graph/graph.db が存在する場合は、レビュー前にグラフの影響分析を実行します。

• python .claude/scripts/code_graph graph-blast-radius --json またはプロジェクトに相当するコマンドを実行します
• 影響を受けるファイル数、テストされていない変更済み関数、リスクレベルをレポートに記録します
• フェーズ 1 では影響の大きいファイルを優先します

グラフデータを利用できない場合は、「グラフデータなし — 影響範囲の分析をスキップ」と記録し、フェーズ 0.1 に進みます。

フェーズ 0.1：変更コンテキストの理解とパイプライン全体への影響追跡（必須 — 理解を優先）

重要・必須・要注意： 最初に行うのは、変更を 理解する ステップです。ファイル単位または観点別のレビューに先立って実施します。影響範囲の分析（フェーズ 0）では影響データを収集します。ここでは変更を全体的に理解し、影響を受ける主な領域のパイプライン全体を、変更がまたぐすべての境界にわたって追跡します。クロススタック影響追跡とクロスサービスチェックのプロトコル（本文は下記の SYNC セクション）を両方適用します。この最初の全体マップは、後続のフェーズ 0.3 における変更種別のリスクタスクと、フェーズ 2 の境界横断的な全体評価に役立ちますが、それらに取って代わるものではありません。

1 段落の変更コンテキストのメモ（変更内容・意図・変更元の階層・影響を受ける主な機能／フロー）を記述し、クロススタック影響追跡およびクロスサービスチェックのプロトコル（下記の SYNC ブロック）に従って両方の追跡を実施します。

フェーズ 0.3：高リスクの変更種別を検出

ファイルをレビューする前に、対象の差分または明示的なファイル一覧を確認し、次を調べます。

• バグ修正、検証失敗、古い／誤った最終出力、リグレッション、または動作を変更する修正 — Debugger Trace: End -> Start、すべての入力経路、仮説マトリクス、修正を担当するレイヤー、前方収束の証明が必要です。トレースの証拠が欠けている場合は、重大度「高」または「致命的」のレビュー指摘とします
• 依存関係のアップグレード — セマンティックバージョニング、破壊的変更、セキュリティ勧告、ピア互換性
• 移行またはスキーマの変更 — ロールバック、ロック／ボリュームへの影響、ゼロダウンタイムデプロイ、冪等なバックフィル
• バスイベント／メッセージ — コンシューマーの存在、冪等性、再試行、処理不能メッセージ／デッドレターへの対応
• API コントラクトの変更 — 後方互換性、呼び出し元との整合性、認証、必須レスポンスフィールド
• セキュリティの変更 — 強制適用範囲、権限昇格、否定テスト、重複した権限文字列
• 設定／環境変数の変更 — すべての環境が対象であること、シークレットが含まれていないこと、フェイルファスト動作、セットアップドキュメント
• インフラの変更 — 開発環境と本番環境の同等性、バージョンの固定、CI/CD 権限、再現可能なビルド

真に該当するシグナルごとに焦点を絞ったレビュータスクを作成し、観点別レビューの前に完了します。

フェーズ 0.5：計画への準拠チェック（条件付き）

有効な計画コンテキストがある場合は、ファイルのレビュー前に、計画に照らしてスコープ、テストの証拠、成功基準を確認します。ない場合は、スキップする理由を記録します。

ゴールコントラクトとの照合（条件付き — 有効なゴールがある場合）： goal-contract-satisfaction-loop プロトコルに従って、有効なゴールコントラクトを特定します（有効な計画の goal.md → plans/goals/{YYMMDD-HHmm}-{slug}/goal.md）。見つかった場合は、レビュー対象の変更を保存済みの成功基準に照らしてレポートにマッピングします。この変更セットが進める基準（file:line の証拠を添える）、変更の対象外となる基準、保存済みの基準にまったく寄与しない変更（正当な理由がなければスコープ逸脱として指摘）を記録します。該当するゴールがない場合は No active goal — mapping skipped. と記録します。レビュー中にゴールファイルを作成してはいけません。

フェーズ 0.7：レビューカテゴリの検出

レビューを開始する前に、変更セットを分類し、サブエージェントに振り分けます。

変更されたファイル内のシグナル	振り分け先
認証／権限／トークン／暗号化関連のファイル	security-auditor
クエリ関連のファイル、キャッシュ、バッチ処理	performance-optimizer
ソースコード（ロジック、ハンドラー、サービス）	code-reviewer
フロントエンド／UI ファイル（コンポーネント、テンプレート、.html／.scss／.css、デザインシステム）	$ui-review スキル（Phase 0.7b を参照）
ドキュメント、計画、仕様、Markdown	general-purpose
セキュリティ／パフォーマンス関連ファイルを含む複合変更	先に特化型サブエージェントを起動し、その後 code-reviewer に振り分ける

Phase 0.7b：フロントエンド／UI サブレビュー（条件付き — $ui-review）

変更セットに、プロジェクトで設定された UI パターン（コンポーネント、テンプレート、.html／.scss／.css、デザインシステムのトークン）に一致するフロントエンド／UI ファイルが含まれる場合は、UI 固有の懸念事項（長いコンテンツのオーバーフロー（折り返しと省略記号＋ツールチップ）、複数画面でのレスポンシブな flex、固定 px よりも flex-grow と min/max を優先すること、セマンティックな z-index の運用（生の数値や !important を使わない）、すべてのテンプレート要素への BEM クラスの適用）を網羅するため、サブレビューとして $ui-review スキルを呼び出してください。その指摘事項を、このレポートの Phase 3 の結果にまとめてください。

スキップ（理由を記録）：変更セットにフロントエンド／UI ファイルがない場合は、ログに「Skipped Phase 0.7b — no frontend/UI files in changeset」と記録してください。

Phase 0.8：レビューカテゴリの導出

変更されたファイルを、ファイル言語（拡張子）、ディレクトリの意味（パス）、変更の性質（新しいエンティティ、スキーマ、設定、UI、テスト）ごとにグループ化します。

各カテゴリについて、名前を付け、サブタスクを作成し、SYNC:category-review-thinking を使って懸念事項を導出してください（第一原理に基づき、固定チェックリストは使いません）。

カテゴリ一覧 ＝ Phase 1 の作業内訳です。各カテゴリは、レポート内の独立したセクションになります。

Phase 1：ファイルごとのレビュー（レポートの作成）

各ファイルについて、直ちにレポートを更新してください。

• ファイルパス、変更の概要、目的、検出された問題
• 規約チェック： 類似パターンを 3 件以上 grep し、新しいコードが既存の規約に従っているか確認します。
• 正確性チェック： ロジックを追跡し、null、空、境界、エラーの各ケースが処理されているか確認します。
• DRY チェック： 類似コードや重複コードを grep し、このロジックが他の場所に存在しないか確認します。
• 意図チェック： 変更が明示された目的に沿っているか確認し、無関係な変更があれば指摘します。
• テストチェック： 変更された動作に対応するテスト／仕様のカバレッジがあるか、またはカバレッジの不足が文書化されているか確認します。
• ドキュメントチェック： 関連するドキュメント／仕様／README が、変更後の動作と一致しているか確認します。

Phase 2：全体レビュー（レポートの再読）

すべてのファイルのレビュー後、蓄積されたレポートを読み直します。

• 技術的な解決策：全体的なアプローチが統一された計画として一貫していますか？
• 責務：ロジックは最下層にありますか？ビジネスロジックがコントローラーに含まれていませんか？
• データの所有権：定数や設定はコントローラーやコンポーネントではなく、モデルやエンティティにありますか？
• 重複：grep で検証してください。変更箇所の間でロジックが重複していませんか？
• アーキテクチャ：クリーンアーキテクチャになっていますか？サービスの境界は守られていますか？
• 計画への準拠：有効な計画がある場合は、## Plan Context を確認してください。実装は要件に合致していますか？TC にコード上の根拠があり、「TBD」になっていませんか？未対応の要件はありませんか？
• デザインパターン：パターンを適用できる箇所（switch→Strategy）はありますか？アンチパターン（God Object、コピー＆ペースト、循環依存）はありますか？基底クラスを使って DRY にできていますか？
• 境界をまたぐ動作：呼び出し元と呼び出し先は整合していますか？API／イベントのコントラクトに一貫性がありますか？新しい配線から到達できますか？
• テストの同期：ビジネスロジックの変更に対応するテスト、またはユーザーに明示されたギャップがありますか？
• 翻訳の同期：多言語対応の UI テキストの変更に翻訳の更新が伴っていますか？またはリスクの受容が明示されていますか？
• バグ修正の追跡可能性：差分がバグ修正または動作を変更する修正の場合、レビュー報告に、最終状態のトレース、上流経路、仮説マトリクス、修正を担うレイヤー、順方向の収束の証明、テスト／証明の対応付けが完全かどうかを記載してください。

必須の注意事項 — Spec-Loop のテスト規律（コアロジックの変更時）：上記の正常系／異常系のトレースに加えて、変更されたコアロジックには、偽装しにくい厳格な基準を適用してください。ミューテーションスコアの基準を適用してください。生き残ったミュータントは、不足している不変条件を示すため、それを殺すテストを要求してください。また、行カバレッジ率をテストの強さの証明として認めないでください。[HARD]／§5 の不変条件が、全称量化されたプロパティ TC（境界の反例を含む）のない例示テストだけでカバーされている場合は、高優先度の指摘事項として報告してください。動作を変更する指摘事項にはすべて、仕様への反映とテストへの反映の有無を示す Dual-Feedback の行が必要です。片方の軸が空欄なら、未完了として報告に記録してください。仕様との不一致は SYNC:spec-drift-adjudication に従って判定してください（CODE-WRONG／SPEC-STALE／AMBIGUOUS／SPEC-SILENT）。SPEC-SILENT の指摘事項（コードでは正しく不変条件を適用しているものの、どの仕様成果物にも記載がない場合）では、両方の軸を N/A 以外にしてください。仕様への反映＝不足している §4 BR／§3 AC（該当する場合は §5 の不変条件も）と §8 TC を $spec [update] ＋ $spec [mode=tests] で追加。テストへの反映＝新たに記述した不変条件を保護するプロパティ／回帰テスト。発見した不変条件をコードだけ、またはテストだけに残してはいけません。差分だけでなくパッケージ全体（仕様＋テスト＋コード）をレビューし、仕様を単にパッチするのではなく充実させてください。

必須の注意事項 — クリーンコード：YAGNI（未使用のパラメーター、先走ったインターフェース）は守られていますか？KISS（より単純な方法はありませんか？）は守られていますか？30 行を超えるメソッドや、3 段を超えるネストはありませんか？

必須の注意事項 — 正確性：null／空／境界ケースに対処していますか？エラー経路を捕捉していますか？非同期の競合状態はありませんか？正常系と異常系の両方をトレースしてください。

ドキュメントの陳腐化チェック：

変更された各ファイルについて、docs/ と AI ツール用ディレクトリ全体から、ファイル名／モジュール名を grep してください。動作が変更されている場合は、古くなったドキュメントを指摘してください（該当するセクションと変更内容を明記）。陳腐化の指摘だけを行い、ここでドキュメントを自動修正してはいけません。

陳腐化のよくあるパターン：件数／上限の変更 → その数値を記載したドキュメント | API／コントラクトの変更 → API の使用方法を説明するドキュメント | フック／スキルの追加・削除 → カタログ／README | スキーマの変更 → エンティティ参照ドキュメント。

フェーズ 3：最終レビュー結果

レポートを更新してください：全体評価、重大な問題、優先度の高い問題、アーキテクチャに関する推奨事項、境界をまたぐ影響（フェーズ 0.1 の内容。クライアント↔サーバーの接続箇所ごと、およびサービス／イベント／外部との接点ごとに NONE／ADDITIVE／BREAKING と修正の振り分けを記載するか、「単一階層／モノリス — 該当なし」と明記）、ドキュメントの陳腐化、肯定的な所見。

ドキュメントの陳腐化が検出された場合は、docs-update を推奨し、古くなったセクションを正確に列挙してください。古いドキュメントを指摘せずに見過ごしてはいけません。

検証済みの修正と完全な再レビュー（指摘事項を修正した場合は必須）

フェーズ 3 の後、同じ指摘事項を再レビューするだけの目的で、新しいレビュアーを起動しないでください。まず指摘事項を検証し、検証済みの指摘事項のみ修正してください。修正によってレビュー対象が変わるため、修正サイクル後に完全なレビューを再開してください。再開したプロトコルでサブエージェントを使用する場合は、各 Agent 呼び出しを SYNC:review-protocol-injection の正規テンプレートで構成してください。

1. SYNC:review-protocol-injection から Agent 呼び出しの形式をそのままコピーします
2. 11 個すべての SYNC ブロックの本文を完全にそのまま埋め込みます：SYNC:spec-tests-code-triangulation、SYNC:evidence-based-reasoning、SYNC:bug-detection、SYNC:design-patterns-quality、SYNC:complexity-prevention、SYNC:logic-and-intention-review、SYNC:test-spec-verification、SYNC:fix-layer-accountability、SYNC:rationalization-prevention、SYNC:graph-assisted-investigation、SYNC:understand-code-first
3. タスク："検証済みの修正を適用した後、現在割り当てられている範囲を対象に、コードレビューを最初から完全に実施してください。重点項目：横断的な懸念事項、相互作用による不具合、規約からの逸脱、不足箇所、微妙なエッジケース、ロジックエラー、テスト仕様の不足、修正によるリグレッション。"
4. 対象ファイル："明示されたファイル、計画の対象範囲、またはレビュアーが提示した対象範囲を使用"
5. レポート：plans/reports/code-review-rerun{N}-{date}.md

サブエージェントから結果が返された後：

1. plans/reports/code-review-rerun{N}-{date}.md のレポートを読みます
2. 指摘事項を ## 再レビュー {N} の指摘事項 として統合します — 除外したり、覆したりしないでください
3. 指摘事項が残っている場合： 追加の修正を行う前に、新たな指摘事項を検証します
4. 別の修正サイクル後にのみ繰り返します： 検証済みの修正を適用した後、再び完全なレビューを再開します。同じブロッカーが進展のないまま 2 回の完全な実行で繰り返される場合は、ユーザーに直接確認してください

クリーンコードのルール（必ず確認）

#	ルール	詳細
1	マジック値の禁止	すべてのリテラル → 名前付き定数
2	型アノテーション	すべての関数に、パラメーター型と戻り値型を明示的に指定します
3	単一責任	メソッド／クラスごとに責務は 1 つにします。イベントハンドラー／コンシューマーも、1 つのハンドラーにつき責務は 1 つです。決してまとめないでください — フレームワークのイベントディスパッチャーは、ハンドラーの例外を黙って握りつぶすことがあります
4	DRY	重複をなくし、共通ロジックを抽出します
5	命名	具体的な名前を使います（data ではなく orderRecords）。メソッド名は動詞＋名詞、真偽値は is／has／can／should を使い、略語は使いません
6	パフォーマンス	O(n²) を避けます（ディクショナリを使用）。クエリ内でプロジェクションします（すべて読み込んでから処理しない）。必ずページネーションします。N+1 ではなく、ID 単位で一括処理します
7	エンティティのインデックス	コレクション：インデックス管理メソッドを用意します。EF Core：複合インデックスを使用します。式フィールドをインデックスの順序に合わせます。テキスト検索 → テキストインデックス

データライフサイクルのルール（必ず注意して確認）

判断基準： 「DB を削除して最初からやり直す場合、このデータは引き続き必要ですか？」 はい → シーダー／フィクスチャ。いいえ → マイグレーション。

種類	含まれるもの	絶対に含めないもの
シーダー／フィクスチャ	デフォルトレコード、システム設定、参照データ（べき等性があり、起動ごとに安全に実行可能）	スキーマの変更
マイグレーション	スキーマの変更、カラムの追加／削除、データ変換、インデックスの変更	デフォルトレコード、権限のシード、システム設定

プロジェクトの言語／フレームワークの規約を適用してください。この原則は普遍的ですが、実装はプロジェクト固有です。

レガシーパターンへの準拠

レガシーパターンと最新パターンが混在するファイルをレビューする場合：

1. レガシーの兆候を検出する — project-config.json、package.json、または同等のファイルで "legacy"、バージョンフラグ、機能アノテーションを検索する
2. 「レガシー」の意味を確認する — レガシーなファイルを 3 つ以上 grep し、最新のファイルとのパターン上の制約の違いを理解する
3. 準拠ルールを導き出す — この技術スタックでは、レガシーと最新の実装でライフサイクル／メモリ管理にどのような違いがあるかを確認する
4. 技術スタックに関する知識を適用する — アンチパターンを指摘する

特定のフレームワークのライフサイクルを決めつけないでください。コードベースの証拠から導き出してください。

このスキルを使うタイミング

プラクティス	トリガー	必ず確認するもの
フィードバックの受領	レビューコメントを受け取ったとき、フィードバックが不明確／疑わしいとき、既存の決定と矛盾するとき	references/code-review-reception.md
レビューの依頼	各サブエージェントのタスク後、主要機能の完了後、対象を絞ったレビューの依頼時、複雑なバグ修正後	references/requesting-code-review.md
検証ゲート	完了を宣言する前、コミット、プッシュ、PR の前。成功／満足を示すすべての発言の前	references/verification-before-completion.md

クイック判断ツリー

SITUATION?
│
├─ Received feedback
│  ├─ Unclear items? → STOP, ask for clarification first
│  ├─ From human partner? → Understand, then implement
│  └─ From external reviewer? → Verify technically before implementing
│
├─ Completed work
│  ├─ Major feature/task? → Request code-reviewer subagent review
│  └─ Before merge? → Request code-reviewer subagent review
│
└─ About to claim status
   ├─ Have fresh verification? → State claim WITH evidence
   └─ No fresh verification? → RUN verification command first

フィードバック受領プロトコル

パターン： 読む → 理解する → 検証する → 評価する → 応答する → 実装する

• 形だけの同意（「そのとおりです！」「よい指摘です！」「ありがとうございます……」など）を絶対にしない
• 検証する前に絶対に実装しない
• 要件を言い換える、質問する、または技術的な根拠を示して異議を唱えることを必ず行う
• 不明確な項目はすべて、着手前に説明を求める
• 提案された「適切な」機能を実装する前に、使用箇所を grep する（YAGNI の確認）

情報源への対応： 人間のパートナー → 理解したうえで実装する。外部レビュー担当者 → 技術的に検証し、誤りがあれば異議を唱える。

完全なプロトコル： references/code-review-reception.md

レビュー依頼プロトコル

1. Git の SHA を取得する：BASE_SHA=$(git rev-parse HEAD~1) および HEAD_SHA=$(git rev-parse HEAD)
2. 次の情報を添えてコードレビュアーのサブエージェントを起動する：WHAT_WAS_IMPLEMENTED、PLAN_OR_REQUIREMENTS、BASE_SHA、HEAD_SHA、DESCRIPTION
3. フィードバックに対応する：重大 → 直ちに修正する。重要 → 次に進む前に修正する。軽微 → 後で対応できるよう記録する。

完全なプロトコル： references/requesting-code-review.md

検証ゲートプロトコル

鉄則：最新の検証エビデンスなしに、完了を主張しないでください

ゲート： コマンドを特定 → 実行 → 出力を読む → 主張を裏付けていることを検証 → その後に主張。どれか1つでも省略すれば、嘘をつくことになります。

主張	必要なエビデンス
テストが成功	テスト出力で失敗が0件と確認できる
ビルドが成功	ビルドコマンドの終了コードが0
バグを修正	元の症状を確認するテストが成功する
要件を満たした	1行ずつチェックリストで確認済み

危険信号 — 作業を止めてください： 「はず」「おそらく」「〜のようです」、検証前に満足すること、検証なしでコミットすること、エージェントの報告を鵜呑みにすること。

プロトコル全文： references/verification-before-completion.md

関連項目

• code-simplifier
• debug-investigate
• refactoring

---

系統的レビューのプロトコル（変更ファイル10個以上）

フェーズ1で変更ファイルが10個以上見つかった場合は、以下に定義する系統的レビューバッチ処理プロトコル（マップ・リデュース：サイズ上限付きバッチ＋階層的統合）を適用してください。

---

ワークフローの推奨

必須 — 例外なし： まだワークフロー内にいない場合は、ユーザーに直接尋ねてください。

1. workflow-review-changes ワークフローを有効にする（推奨）— 完全なレビュー → 検証済みの修正サイクル → 問題がなくなるまで再レビュー
2. $code-review を直接実行する — 単独で実行

---

アーキテクチャ境界チェック

変更した各ファイルについて、禁止されたレイヤーのインポートがないことを確認してください。

1. docs/project-config.json → architectureRules.layerBoundaries からルールを読み取る
2. レイヤーを特定する — ファイルパスを各ルールの paths glob パターンと照合する
3. インポートをスキャンする — 設定された言語の import/include 文を grep する
4. 違反を確認する — インポートパスに禁止されたレイヤー名が含まれている場合は違反
5. フレームワークを除外する — architectureRules.excludePatterns に一致するファイルはスキップする
6. 違反があればブロックする — "BLOCKED: {layer} layer file {filePath} imports from {forbiddenLayer} ({importStatement})"

project-config.json に architectureRules がない場合は、何も記録せずスキップしてください。

---

フェーズ4：Why-Review 自己検証ゲート（指摘がある場合は必須）

目的： 引き継ぎ前に、自分の指摘を敵対的に検証します。過剰に指摘された High、誤検知、重大度の水増しを、後続工程に伝播させるのではなく、発生源で検出します。

トリガー： 指摘が1件でもある場合（Critical、High、Medium、またはLow）。レポートの判定が無条件の PASS で、指摘が文字どおり0件の場合に限りスキップします。

プロトコル：

1. plans/reports/{skill}-{date}-{slug}.md から確定済みの自分のレポートを読む
2. $why-review スキルを次の引数で呼び出す：plans/reports/{skill}-{date}-{slug}.md の指摘を検証 — 各指摘に file:line の根拠があることを確認し、却下された解釈それぞれの最も有力な論拠を立て、重大度の分類に対するストレステストを行う
3. why-review が返した検証結果のパスを読む。想定されるパスは plans/reports/why-review-validate-{date}.md
4. why-review が指摘の重大度を下げた、または削除した場合： 重大度を修正し、誤検知を削除したうえで、何を変更したか、なぜ変更したかを記載した ## Why-Review Validation Notes セクションを追加して、自分の確定済みレポートを更新する
5. why-review がすべての指摘を確認した場合： 自分のレポートに ## Why-Review Validation の行を追加し、「すべての N 件の指摘を実際のコードと照合して再検証し、重大度の変更はありません。」と記載する

スキップ条件（スキップする場合は理由を明記する）：

• 判定が無条件の PASS で指摘が0件 → 「スキップ — 検証する指摘がありません」と記録する
• why-review スキル自体が現在のコンテキストである（再帰を避ける）

この手順が必要な理由： AI サブエージェントの報告には確証バイアスが引き継がれます。オーケストレーターは重大度の主張を事実として受け入れてしまいます。2026-05-09 のレビューでは High が5件報告され、敵対的検証によってそのうち3件の重大度が下げられました。これを標準的な手順として定めます。

次のステップ

必須 — 例外なし 完了後、必ずユーザーに直接確認してください：

• "$fix (Recommended)" — レビューで修正が必要な問題が見つかった場合
• "$watzup" — レビューで問題が見つからず、セッションを終了する場合
• "Skip, continue manually" — ユーザーが判断する場合

AI エージェントの整合性ゲート（必須）

完了 ≠ 正確性。 作業の完了を報告する前に、必ず次を実施してください。

1. 削除した名前をすべて grep で検索する。 抽出・名前変更・削除の後、すべてのファイル形式を対象に grep を実行し、参照漏れが 0 件であることを確認します。
2. 変更する前に理由を確認する。 既存の値は、意図的でないと証明されるまでは意図されたものとして扱います。
3. すべての出力を検証する。 1 つのビルドが成功しても、すべてのビルドが成功したことにはなりません。
4. パターンとの適合性を評価する。 近くにあるコードをコピーする場合、前提条件（スコープ、ライフタイム、基底クラス、制約）が一致していることを確認します。
5. 新しい成果物は接続された成果物にする。 何かを作成した場合、それが登録され、インポートされ、すべての利用側からアクセスできることを証明します。

---

[IMPORTANT] タスクトラッキングを使って、作業を開始する前に、ファイルを読むタスクも含め、すべての作業を小さなタスクに分割してください。長いファイルによるコンテキストの喪失を防げます。単純なタスクの場合、AI はスキップするかどうかを必ずユーザーに尋ねてください。

重要な目的： 品質を確保し、欠陥、バグ、更新漏れ、古い内容をなくします。コードとドキュメントの両方を検証してください。

外部メモリ： 複雑な作業では、plans/reports/ に調査結果を段階的に書き出してください。コンテキストの喪失を防ぎ、成果物としても役立ちます。

エビデンスゲート： 必須 — すべての主張、調査結果、推奨事項に file:line の証拠と信頼度（%）を添えてください（80% 超なら実行、80% 未満なら先に検証）。

OOP と DRY： 必須 — 基底クラス／ジェネリック／ヘルパーに抽出できるパターンを指摘してください。同じ接尾辞／ライフサイクル／責務を持つクラスは、共通の基底クラスを共有します。プロジェクトの言語に適した慣用的な抽象化（基底クラス、ミックスイン、トレイト、プロトコル）を適用してください。リンティング／アナライザーが設定済みであることを確認してください。 クロススタック影響の追跡 — 最初のレビューアクション：変更を全体として理解してから、ファイルを評価します。レビュー対象のすべての差分について、変更の背景を記録し、主な影響範囲のパイプライン全体をクライアント↔サーバー間の境界をまたいでエンドツーエンドで追跡し、一方の層への変更がもう一方の層を気付かないうちに壊すことがないようにします。（SYNC:cross-service-check とは異なり、そちらがサービス間／イベント境界を担当するのに対し、こちらは1つのアプリ内のクライアント↔サーバー層の境界を担当します。パイプライン全体を網羅するには両方を組み合わせてください。）

1. まず変更の背景を理解する — ファイルごとのレビューに入る前に、短い 変更の背景 を記述します。変更内容、意図（理由）、変更の起点となる層（フロントエンド／バックエンド／共有／インフラ）、主な影響を受ける機能／フローを記載します。問題点を指摘する前に行ってください。
2. クロススタックの境界を特定する — 主な影響範囲について、クライアントとサーバー間の契約境界を特定します。API ルート／エンドポイントと HTTP メソッド、リクエスト／レスポンス DTO またはペイロードの形状、共有型／スキーマ、イベント／メッセージ契約、クエリ／ルートパラメーターなどです。docs/project-config.json とプロジェクトの規約から層の構成を推測します。
3. 変更の方向に沿ってパイプライン全体をエンドツーエンドで追跡する：
   • バックエンドの変更 → すべてのフロントエンドの利用箇所まで順方向に追跡： ハンドラー／コントローラー → レスポンス DTO／シリアライザー → API クライアント／サービス → ストア／状態 → コンポーネント／テンプレートでの表示または送信。
   • フロントエンドの変更 → バックエンド契約まで逆方向に追跡： コンポーネント／フォーム → API クライアント呼び出し → ルート／エンドポイント → リクエスト DTO／検証 → ハンドラー／ドメイン。
   • .code-graph/graph.db がある場合は、$graph-connect-api と python .claude/scripts/code_graph trace <file> --direction both --json を使って接続関係を把握します。ない場合は、両方の層でルートパス、DTO／型名、各フィールド名を grep します。
4. 両側の整合性を確認する — 変更された境界ごとに、もう一方の層との整合性を確認します。ルートパスと HTTP メソッド、フィールド名と型、null 許容性／省略可能性、必須／省略可能なパラメーター、列挙値、認証／権限、エラー／ステータスの形式を確認してください。不整合はすべて 破壊的変更 として指摘します（バックエンドの変更がフロントエンドの利用箇所を壊す場合、またはフロントエンドがバックエンドで拒否される値を送るようになった場合）。
5. 境界を分類する： NONE（契約変更なし）／ADDITIVE（後方互換性あり）／BREAKING（もう一方の層の利用側も変更が必要）。もう一方の層の利用側が同じ差分で更新されていない BREAKING な境界は、少なくとも HIGH の重要度とします（認証／金銭／データ整合性に関わる経路では CRITICAL）。

スキップできるのは、クロスレイヤーの境界がない変更に限ります。純粋なドキュメント、データ契約を伴わない純粋なスタイル変更、または単一層のツールが該当します。次のように明記してください：Single-tier change — no cross-stack seam。バックエンドのみのリポジトリ、または単一層のリポジトリでも、内部の利用箇所を追跡します（サービス／イベント境界には SYNC:cross-service-check を使用）。

次の条件を満たすまで BLOCKED： 変更の背景を記録済み · 境界を特定済み、または明示的に N/A と記載済み · 変更の方向に沿ってパイプライン全体を追跡済み · 変更されたすべての境界を NONE／ADDITIVE／BREAKING に分類済み。 サービス間チェック — マイクロサービス／イベント駆動型：調査、計画、仕様書、機能ドキュメントを完了とする前に必ず実施してください。下流のコンシューマーを見落とすと、気づかれないままリグレッションが発生します。

境界	検索語
イベントの生成元	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 の確認 · コントラクトのレビュー · 破壊的変更リスクへのフラグ付け 体系的なレビューのバッチ処理（map-reduce） — 変更セットが大きい場合、ファイルを1つずつレビューしてはいけません。サイズ上限付きのバッチに分割し、バッチごとに専用のサブエージェントを並列で起動してから、結果を統合します。これにより、ファイル数が増えても網羅性を保ちながら、各コンテキスト（各バッチエージェントとオーケストレーター）の負荷を制限できます。

段階的なトリガー（競合するしきい値ではなく、順序に沿ってエスカレーションします）：

1. 変更ファイルが10件未満 → ファイルごとに順次レビューします（デフォルト。バッチ処理なし）。
2. 変更ファイルが10件以上 → 体系的な並列モードに切り替えます。"Detected {N} changed files. Switching to systematic parallel review protocol." と通知します。その後、分類 → サイズ上限付きバッチ処理 → フラットな統合を行います。
3. カテゴリが6を超える、またはファイルが40件を超える → さらに階層型の統合レイヤー（以下を参照）を追加します。段階2の内容はすべて適用されます。

ステップ1 — 分類。 変更ファイルを、プロジェクトの実際の構造に基づく論理カテゴリにグループ化します（無理に分類しません）。カテゴリは 関心軸 です。以下の例を参考にしつつ、リポジトリに合う分類を導き出します。

カテゴリタイプ	グループ化の例
エージェント／ツール	AI スクリプト、フック、スキル定義、ワークフロー設定、リンティングルール
ルート設定／ドキュメント	ルート README、プロジェクト設定、CI/CD パイプライン設定
リファレンスドキュメント	アーキテクチャドキュメント、パターンのリファレンス、セットアップガイド
機能／ドメインドキュメント	ビジネス機能のドキュメント、仕様ファイル、ADR
バックエンドロジック	サービス／ハンドラー／コントローラーのソース（プロジェクト構造から推測）
フロントエンドロジック	UI コンポーネント／状態管理／API のソース（プロジェクト構造から推測）
データ／スキーマ	マイグレーション、スキーマファイル、シードデータ
テスト	単体テスト、統合テスト、E2E テストのファイル
インフラストラクチャ	Docker、k8s、CI/CD、クラウドのマニフェスト

ステップ2 — サイズ上限付きバッチ処理。 8ファイル以下、または差分行数2,000行以下のいずれかに達するまでを1バッチとし、バッチごとにサブエージェントを1つ割り当てます。カテゴリは引き続き関心軸として扱いますが、上限を超えるカテゴリは複数のサイズ上限付きバッチに分割します（バックエンドファイルが30件なら4バッチ）。「多数のファイル」に安全に対応するのはカテゴリ上限ではなくサイズ上限です。カテゴリだけに上限を設けると、巨大なカテゴリによって1つのエージェントのコンテキストがあふれる可能性があります。

ステップ2a — バッチごとのサブエージェントの種類（バッチの主要な関心事に合わせます）：

• コードロジック（あらゆるスタック） → code-reviewer
• セキュリティに関わる変更 → security-auditor
• パフォーマンスが重要な処理経路 → performance-optimizer
• ドキュメント、計画、仕様、設定、インフラ → general-purpose

各バッチサブエージェントには、ファイルの全リスト、主要な思考モデルとしての SYNC:category-review-thinking（固定のチェックリストではなく、第一原理から各カテゴリの懸念事項を導き出します。利用するスキルにそのブロックが含まれていない場合は、カテゴリ優先の思考を直接適用します）、関心事に関連するプロジェクトのリファレンスドキュメント（*patterns*、*conventions*、*style-guide* を使って検索）、相互参照の検証指示（件数、表、リンク）を渡します。すべてのバッチエージェントは並列に実行し、調査結果を plans/reports/ に書き込みます（SYNC:task-tracking-external-report に従います）。統合担当はメモリではなく、ディスクから報告書を読み込みます。

ステップ3 — 統合。

• フラットな統合（段階2、カテゴリが6以下、かつファイルが40件以下）： オーケストレーターは各バッチの報告書を収集し、バッチ間で件数／表／契約を相互参照し、カテゴリをまたいだ場合にのみ見つかる欠落（コードには機能があるのにドキュメントに記載がない、新しい API エンドポイントにクライアント側の呼び出しがないなど）を検出し、分類された包括的な報告書1つに統合します。
• 階層型の統合（段階3、カテゴリが6を超える、またはファイルが40件を超える）： 中間レイヤーを挿入します。各関心事に統合担当エージェントを1つ割り当て、その関心事に属するバッチ報告書だけを読み込ませ、関心事ごとの統合結果を1つ作成します。オーケストレーターは、生のバッチ報告書ではなく、**関心事ごとの統合結果（約5件）**を読み込みます。これにより、統合担当のコンテキストはファイル数ではなく関心事の数に比例します。
  • 関心事間の相互作用の確認（段階3では必須 — 統合レイヤーの死角を補います）： 関心事ごとに分離した統合では、2つの関心事と2つのバッチにまたがる相互作用（データレイヤー／バッチ7の汚染されたソース → API／バッチ3のシンクなど）が抜け落ちる可能性があります。そのため、(a) 各関心事の統合担当は、別の関心事と結びつく可能性のある、触れたエンティティ／シンボル／契約（共有 DTO、イベント名、テーブル名／コレクション名、エクスポートされたシンボルなど）を明記した 「関心事間の相互作用候補」 リストを必ず出力します。(b) オーケストレーターは結論を出す前に、バッチ内だけでなく、すべての関心事ごとの統合結果に含まれる候補リストを対象として、ステップ3の相互参照／欠落確認を必ず実施します。この確認を行わない場合、このレイヤーは対象とする大規模な差分で、コンテキストを制限する代わりに網羅性を犠牲にしてしまいます。

ステップ4 — 全体評価。 すべての調査結果を統合したうえで、統一された意図としての全体的な一貫性、カテゴリ間の同期（ドキュメントはコードと一致しているか、契約は呼び出し元と一致しているか）、カテゴリ間の相互作用に伴うリスク領域、変更された成果物に必要なドキュメント／仕様の更新漏れを評価します。

黙って省略しないでください。 上限によってサンプリングが必要になった場合、または予算の都合でバッチを除外する場合は、除外／サンプリングした範囲を必ず明示してください。網羅範囲に制限があるのに、網羅的に確認したかのように見せてはいけません。 終点から始めるデバッガートレース — 複雑なバグ、検証の失敗、リグレッション修正、動作を変えるコード、または不明瞭なコードフローの場合は、修正を提案する前に、観測された最終状態から逆方向にたどってください。

1. フレーム 0：観測された最終状態 — ユーザーに表示される正確な出力、失敗したアサーション、ログ行、永続化された値、API レスポンス、レンダリングされた UI、または集計バケットを明記してください。それを生成したリーダー／クエリ／レンダラーを、file:line の証拠とともに記録してください。
2. 1 ホップずつ逆方向にたどる — 最終リーダー → プロジェクション／キャッシュ／ストレージ → ライター → コンシューマー／ハンドラー／ジョブ → プロデューサー／呼び出し元 → 元のトリガーの順に追跡してください。各ホップで、入力、変換、出力、担当箇所、証拠を記録してください。
3. すべての流入経路を列挙する — リトライ、非同期処理、キャッシュ、バックグラウンド処理、代替の UI／API 経路を含め、最終経路に書き込める上流のプロデューサー／呼び出し元／イベント／ジョブをすべて見つけてください。各経路に、検証済み、除外、または未確認の印を付けてください。
4. 仮説マトリクスを作成する — 考えられる原因ごとに、裏付ける証拠、反証する証拠、再現／検証方法、影響範囲、ステータス（primary、contributing、ruled out、latent）を列挙してください。競合する原因を明示的に解決するか、範囲を限定するまでは修正しないでください。
5. 修正を担うレイヤーを選ぶ — 不変条件を担う箇所と、下流のすべてのコンシューマーを保護する最も低い共通箇所を特定してください。不変条件を担っていない限り、症状が現れる箇所での修正は認められません。
6. 前方向への収束を証明する — 修正を選んだ後、開始点から終点まで再度たどり、修正後の状態がどのように観測された最終出力に到達するかを示してください。各根本原因を修正内容に、各修正内容をテスト／証明に対応付けてください。

以下が完了するまで作業はブロックされます： 最終状態を明記 · 逆方向のトレースを記述 · すべての流入経路を列挙 · 仮説マトリクスを完成 · 修正を担うレイヤーの妥当性を説明 · 前方向への収束の証明をテストに対応付け。

禁止事項： 最初に疑わしいコード経路から調査を始めること。複数のプロデューサーを 1 つの「フロー」にまとめること。読み取りモデルを証明せずに、重複した症状を重複レコードとして扱うこと。除外した仮説を省略すること。

グラフを活用した調査 — .code-graph/graph.db が存在する場合は必須です。

必須ゲート： 調査を終える前に、主要なファイルに対して少なくとも 1 つのグラフコマンドを実行する必要があります。

パターン： Grep でファイルを見つける → trace --direction both でシステム全体のフローを明らかにする → Grep で詳細を確認する

タスク	最低限必要なグラフ操作
調査／偵察	2～3 個のエントリーファイルに対して trace --direction both を実行
修正／デバッグ	不具合のある関数に対して callers_of と tests_for を実行
機能／機能強化	変更対象ファイルに対して connections を実行
コードレビュー	変更した関数に対して tests_for を実行
影響範囲	trace --direction downstream を実行

CLI： python .claude/scripts/code_graph {command} --json。まず --node-mode file を使用してください（ノイズが 10～30 倍少なくなります）。次に詳細を確認するには --node-mode function を使用してください。 カテゴリレビューの思考法 — 変更されたファイルのあらゆるカテゴリをレビューするための思考フレームワークです。固定チェックリストではありません。ドメイン知識から懸念事項を導き出してください。以下の例は出発点にすぎません。このカテゴリに関するあなたの知識は、どのリストよりも豊富です。それを信頼してください。

ステップ 1 — カテゴリの役割を理解する。 システム全体において、このカテゴリはどのような責任を担っていますか？維持すべき不変条件は何ですか？利用側との契約（何が依存し、何を期待しているか）は何ですか？

ステップ 2 — このカテゴリに関するプロジェクトの規約を読む。 この領域に特化したリファレンスドキュメント、スタイルガイド、ADR、README を検索します。類似した既存ファイルを 3 つ以上 Grep し、命名規則、構造パターン、共通の基底クラスを抽出します。ドキュメントがない場合は、既存コードから経験的に規約を導き出します。

ステップ 3 — 第一原理から懸念事項を導き出す。 該当するものをすべて適用し、実際のカテゴリに応じてこのリストを拡張してください。

• 正確性： ロジックは意図に沿っていますか？正常系とエラー系の両方を追跡してください。
• 境界の契約： インターフェース／API／イベント／プロトコルを遵守していますか？暗黙の結合が導入されていませんか？
• プロジェクトの規約： 新しいコードはステップ 2 で確認したパターンに従っていますか？思い込みではなく、証拠に基づいていますか？
• セキュリティ： すべてのエントリーポイントで認証が強制されていますか？境界で入力が検証されていますか？差分にシークレットが含まれていませんか？
• パフォーマンス： 上限のない処理はありませんか？N+1 パターンはありませんか？非同期コンテキスト内でブロッキング呼び出しをしていませんか？インデックスのないクエリはありませんか？
• 保守性： DRY ですか？単一責任を守っていますか？複雑さは妥当な範囲内ですか？名前から意図がわかりますか？
• テストカバレッジ： 変更された経路はテストでカバーされていますか？変更後も既存のテストは有効ですか？
• ドキュメント： 関連するドキュメント、仕様、README に変更が反映されていますか？

ステップ 4 — サブタスクを作成して実行する。 特定した懸念事項ごとに、追跡用のサブタスクを作成し、file:line の証拠を確認しながら対応し、完了としてマークします。証拠のない指摘はしないでください。

カテゴリの種類ごとの懸念事項の例（網羅的な一覧ではありません。ここにないことも、あなたの知識を信頼してください）。

• サーバー側ロジック： ハンドラー／サービスの構造規約、検証レイヤーの配置、副作用の分離、サービス間境界の適用、データアクセスレイヤーの分離、エラー伝播の方針
• クライアント側ロジック： コンポーネントのライフサイクル管理、リソースのクリーンアップ（サブスクリプション、リスナー、タイマー）、状態管理パターン、API 統合レイヤーの分離、リアクティブストリームの合成
• データ／スキーマ： マイグレーションの可逆性（ロールバックスクリプト）、テーブル規模に対するロックの影響、バックフィルの冪等性、クエリパターンに対するインデックスの網羅性、デプロイ順序
• 設定： すべての環境に存在していますか？差分にシークレットが含まれていませんか？設定がない場合、アプリケーションは即座に失敗しますか（null のまま黙って処理しませんか）？セットアップガイドに記載されていますか？
• インフラストラクチャ： 開発環境と本番環境の構成に差はありませんか？開発用の値（localhost、デバッグフラグ）がハードコードされていませんか？イメージ／依存関係のバージョンは固定されていますか？CI/CD のシークレット要件は文書化されていますか？
• スタイル／アセット： プロジェクトの命名規則に従っていますか？デザイン変数／トークンを使用していますか（マジック値をハードコードしていませんか）？適切なスコープになっていますか（コンポーネントのスタイルからグローバルな副作用が生じませんか）？
• ドキュメント： 正確ですか？リンクは有効ですか？例は現在のコード／動作に合っていますか？新しいシナリオを扱っていますか？
• テスト： アサーションは具体的な結果を検証していますか（単に「例外が発生しない」だけではありませんか）？冪等ですか（N 回繰り返しても結果が変わりませんか）？正常系だけでなく、エッジケースもカバーしていますか？
• セキュリティ関連成果物： すべてのコード経路がゲートに到達しますか？否定テスト（未認証の場合に拒否されるテスト）はありますか？適用制御と表示制御の両方が更新されていますか？
• ビルド／ツール： ルールの変更は一貫して適用されますか？違反を黙って握りつぶす例外はありませんか？CI 実行時間への影響は文書化されていますか？ サブエージェントの返却契約 — このスキルがサブエージェントを起動する場合、サブエージェントは必ずこの構造のみを返します。メインエージェントが読み取るのはこの要約のみです。サブエージェントの出力全体をインラインで要求してはなりません。

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

状態：✅ PASS | ⚠️ PARTIAL | ❌ FAIL
確信度：[0-100]%

### 調査結果（Critical／High のみ — 最大 10 項目）

- [重大度] [ファイル:行] [調査結果]

### 実施した対応

- [変更したファイル] [変更内容]

### ブロッカー（該当する場合）

- [ブロッカーの説明]

全レポート：plans/reports/[skill-name]-[date]-[slug].md

メインエージェントが全レポートファイルを読むのは、（a）特定のブロッカーを解決する場合、または（b）修正計画を立てる場合のみです。 サブエージェントは、全レポートをメモリに保持せず、（SYNC:incremental-persistence に従って）逐次書き込みます。

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

ネストされたタスク展開契約 — ワークフローステップの呼び出しでは、[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} を記載します。

作業開始をブロックする条件： タスク分解の作成、計画／レビュー作業におけるレポートパスの宣言、次の所見に進む前の最初の所見の記録が完了していること。

批判的思考の姿勢 — 批判的思考と順序立てた思考を適用します。すべての主張には追跡可能な根拠が必要です。行動に移すには確信度が 80% を超えている必要があります。 ハルシネーション対策： 推測を事実として述べてはいけません。すべての主張に出典を示し、不確実性は率直に認め、出力に誤りがないか自己確認し、独立して相互参照し、自分の確信を疑ってください。根拠のない確信は、あらゆるハルシネーションの根源です。 逐次思考プロトコル — 複雑または曖昧な作業のための、構造化された多段階の推論です。一度の推論では安全に対応できない、計画、レビュー、デバッグ、アイデアの改善に使用します。

次の場合に適用： 複雑な問題の分解 · 修正が必要な適応型の計画 · 軌道修正を伴う分析 · 不明確、または作業中に明らかになるスコープ · 多段階の解決策 · 仮説主導のデバッグ · 分野横断的なトレードオフの評価。

形式（明示モード — 思考の経過を可視化）：

1. Thought N/M: [aspect] — 1つの思考につき1つの観点を扱い、前提や不確実性を明示します
2. Thought N/M [REVISION of Thought K]: ... — 以前の推論が無効になった場合に使用します。Original / Why revised / Impact を明示します
3. Thought N/M [BRANCH A from Thought K]: ... — 代替案を検討し、判断の根拠を示して結論を出します
4. Thought N/M [HYPOTHESIS]: ... の後に [VERIFICATION]: ... — 実行前に検証します
5. Thought N/N [FINAL] — 検証済みで、重要な観点をすべて扱い、確信度が80%を超える場合に限ります

必須の締めくくり： 確信度（%）を明示 · 前提を列挙 · 未解決の疑問を提示 · 次の具体的なアクションを示す。

停止条件： 重要な判断の確信度が80%未満 → ユーザーに直接質問して確認する · 同じ思考に対する修正が3回以上 → 問題を捉え直す · 分岐数が3を超える → サブタスクに分割する。

暗黙モード： マーカーを付けると回答が煩雑になる場合（推論が正確性に役立つ定型作業など）は、マーカーを表示せずに手法を内部で適用します。

詳細： 実例（API 設計、デバッグ、アーキテクチャ）、高度な手法（らせん状の改善、仮説検証、収束）、メタ戦略（不確実性への対処、修正の連鎖）については、$sequential-thinking スキル（.claude/skills/sequential-thinking/SKILL.md）を参照してください。

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

1. すべての主張に対して、file:line、grep の結果、またはフレームワークのドキュメントを引用します
2. 確信度を明示します：80%超ならそのまま進める、60〜80%なら先に検証する、60%未満なら推奨しない
3. アーキテクチャの変更では、サービスを横断した検証が必要です
4. 「証拠が十分ではありません」は、妥当かつ期待される回答です

以下を満たすまで作業をブロックします： - [ ] 証拠のファイルパス（file:line） - [ ] grep 検索を実施済み - [ ] 類似パターンを3つ以上確認済み - [ ] 確信度を明示済み

証拠なしでの使用は禁止： 「明らかに」、「私はそう思います」、「〜するべきです」、「おそらく」、「これは〜が原因です」 未完了の場合 → 次を出力します："証拠が不十分です。確認済み：[...]。未確認：[...]。" 設計パターンの品質 — すべてのコード変更で優先的に確認します。

1. OOP による DRY： 目的、命名パターン、またはライフサイクルが同じクラス／モジュールを特定します。プロジェクトの言語／フレームワークに関する知識を活用し、慣用的な抽象化（基底クラス、ミックスイン、トレイト、プロトコル、デコレーター）を判断します。類似するパターンが 3 つ以上ある場合は、共通の抽象化を抽出します。
2. 適切な責務： ロジックは最も低い層に置きます（エンティティ > ドメインサービス > アプリケーションサービス > コントローラー）。コントローラーにビジネスロジックを置いてはいけません。
3. SOLID： 単一責任（変更理由は 1 つ）。オープン・クローズド（変更せず拡張する）。リスコフの置換（サブタイプは置換可能）。インターフェース分離（小さなインターフェース）。依存性逆転（抽象に依存する）。
4. 抽出／移動／名前変更の後： 対象範囲全体を grep して、参照先がなくなった箇所がないか確認します。見落としは一切許容しません。
5. YAGNI の基準： パターンを推奨するのは、同じものが 3 回以上存在する場合に限ります。将来使うかもしれないという理由で抽出してはいけません。

指摘すべきアンチパターン： ゴッドオブジェクト、コピー＆ペーストによる継承、循環依存、リーキーアブストラクション。

設計品質に対する逐次的な注意 — すべての懸念を一度に扱うのではなく、品質の各観点を一度に 1 つずつ順番に確認します（逐次的なパス）。— 理由：注意が分散すると、1 つの観点に集中したパスなら検出できる違反を見落とします。

1. 該当する観点を特定する — コードの言語、ドメイン、パターンに基づき、適用する品質の観点を判断します。DRY、SOLID 原則（SRP／OCP／LSP／ISP／DIP）、OOP の慣用表現、凝集度／結合度、GRASP、デメテルの法則、CQRS の不変条件などが該当します。観点のリストは固定ではありません。コードが実際に何をしているかから導き出してください。

2. 各観点について、集中して個別に確認する — 各観点に対して、順番に 1 つずつ集中して確認します。各パスで複数の懸念を混在させてはいけません。

3. 基準：類似パターンが 3 つ以上ある場合は抽出が必須 — 任意の提案ではありません。対応が必要な必須の構造修正として指摘してください。

4. 同種の違反が 2 件以上ある場合は構造上の問題 — 個々の事例を列挙するのではなく、アーキテクチャ上の解決が必要な「パターンの問題」として報告してください。 複雑さの防止（Ousterhout） — 必須です。コードは変更コストで評価します。1つのビジネス上の変更は、1つのコード変更に対応するべきです。レビューでは、次のすべてを指摘してください。

5. 変更の増幅 — 小さなビジネス上の変更で3か所を超える編集が必要になる場合、構造上の欠陥です。もっともらしい将来の変更（バリアントの追加、フィールドの追加、認可の追加）について、編集箇所を数えます。3か所を超える場合は却下します。

6. 認知負荷 — 安全に変更するために、読み手が過剰なコンテキストを把握しておく必要がある状態です。深い継承、長いパラメーターリスト、ブール値の罠、暗黙的な順序依存を指摘します。

7. エントリーポイント間の横断的な重複 — ロギング、エラー処理、バリデーション、認証、トランザクションが、コントローラー／ハンドラー／ルートごとに再実装されている状態です。ミドルウェア／インターセプター／フィルター／デコレーター／アスペクトに引き上げます。

8. 実装技術の漏出 — リポジトリが IQueryable／QuerySet／Criteria／生のカーソル／ORM エンティティを呼び出し元に返している状態です。完成した結果と、意図が伝わるメソッド（Query() ではなく GetActiveVipUsers()）を返します。

9. 型による分岐の散在 — 列挙型／識別子に対する switch／if チェーンが複数箇所にある状態です。新しいバリアントの追加は新しいファイルで行い、N か所の編集を発生させないようにします。境界にある単一のファクトリー／レジストリーでの switch は許容できますが、分岐の散在は却下します。

10. 貧血モデル — ドメインオブジェクトがゲッター／セッターしか持たず、ロジックがサービスに漂流している状態です。不変条件や振る舞いはオブジェクトに移します（order.Status = ... ではなく order.Checkout()）。

11. プリミティブ型偏重 — 口座番号、メールアドレス、金額、割合、日付範囲に生の string／int／decimal を使い、すべての入力箇所で再検証している状態です。コンストラクターで一度だけ検証する値オブジェクト／レコード／構造体でラップします。

12. 横断的関心事のインライン化 — 認可／テナント分離／監査／サニタイズを、すべてのハンドラーの先頭に手書きしている状態です。宣言的なマーカー（@RequirePermission("Order.Delete")）で意図を示し、中央で一度だけ適用します。

13. 浅いモジュール — 大きなインターフェース（公開メソッドが多い、フラグが多い、コンストラクターパラメーターが多い）で、ロジックの少ない小さなクラスをラップしている状態です。小さなインターフェースの背後に多くの実装を隠せるとき、モジュールは深いと言えます。インターフェースの習得コストが実装の習得コストとほぼ同じなら、インライン化します。

14. 繰り返されるコンポーネント／ハンドラーのライフサイクルに基底クラスがない — 3つ以上のフォーム／CRUD ハンドラー／リストビューで、読み込み／変更状態／送信／ページネーションを再実装している状態です。基底クラス／フック／コンポーザブル／ミックスイン／トレイトに抽出します。

15. 抽象化が早すぎる／遅すぎる — 3回ルールに従います。1回目はそのまま書きます。2回目で重複に気づきます。3回目で抽出します。実際の違いが現れる前に汎用フレームワークを作らず、4回目までコピー＆ペーストを続けないでください。

16. 埋め込みユーティリティーロジックがヘルパーに抽出されていない — インラインのページネーションループ（while (hasMore) { skip += take; ... }）、場当たり的な日時計算、文字列の解析／書式設定、コレクションの分割、リトライ／バックオフループ、URL／クエリ文字列の構築などです。アルゴリズムが自明でなく、かつスタック全体で汎用的（ビジネス固有ではない）なら、util／helper／extensions に抽出し、利用側からは1行で呼び出せるようにします。インラインで重複させると、バグが入り込む範囲も重複します。

17. ロジックが誤った（上位の）レイヤーにある — 呼び出し先へ移す — データを所有する呼び出し先ではなく、呼び出し元にビジネスロジック／導出ロジックが書かれている状態です。基本方針：コントローラーのコードはアプリケーションサービスにあるべきです。アプリケーションサービスのコードはドメインサービスまたはエンティティにあるべきです。コンポーネントのコードはビューモデル／ストア／サービスにあるべきです。呼び出し元が呼び出し先のデータ形状を調べて何かを計算しているなら、意図が伝わる呼び出し先のメソッドに計算を移します。責務を持つ最下位のレイヤーを選びます（Entity > Domain Service > App Service > Controller · Model/VM > Store > Component）。上位レイヤーに配置すると、兄弟となる呼び出し元が同じ処理を必要とした際に、ロジックが重複します。

18. ルールは所有者が持つ — 最初に書くときに抽出する — ある型のデータから導出、正規化、検証、または計算するロジックを呼び出し元にインラインで書く場合は、所有する型に移します。1か所でしか使われていなくても抽出します。きっかけは重複ではなく、責務の誤りです。兄弟となる呼び出し元は必ず現れます。インラインのコピーはコンパイルエラーにもならず、検索できる名前もないまま、気づかれずに乖離していきます。よくある問題箇所： バックエンド — アプリケーション層のハンドラー／コマンド／クエリ／サービス／コントローラーにインラインで書かれた、ドメインエンティティ／値オブジェクト／ドメインサービスが担うべきルール。フロントエンド — コンポーネントにインラインで書かれた、モデル／ストア／ビューモデル／API サービスが担うべき導出／書式設定／バリデーション。修正方法： 所有する型に、静的またはインスタンスのメソッドとしてルールを一度だけ命名し、呼び出し元はその名前で呼び出します。将来別のバリアントが必要になったら、所有者に名前付きメソッドをもう1つ追加し、近似した処理をインラインで書くことはしません。まず責務を正しくし、再利用はその結果として実現します。

抽出先 — 名前を付けたルールの配置先：

ルールの形状	配置先
エンティティ自身のデータに対する純粋関数	エンティティの静的メソッド
エンティティの状態を変更／保護する振る舞い	エンティティのインスタンスメソッド
プリミティブ値が常に満たす不変条件	値オブジェクトのコンストラクター
DI（リポジトリ／設定／時計）が必要	DI に登録するヘルパークラス
型をまたいで再利用されるドメイン非依存アルゴリズム	ユーティリティー／拡張メソッド
純粋な形状変換／射影変換	DTO マッピング

コミット前の編集箇所テスト（答えが「多数」なら却下）：

変更シナリオ	変更箇所
新しいバリアントの追加（顧客タイプ、決済方法）	新しいファイル1つ
HTTP エラーレスポンス形式の変更	ミドルウェア／フィルター1つ
永続化されるすべてのエンティティへのタイムスタンプフィールドの追加	基底エンティティ／インターセプター1つ
新しいエンドポイントへの認可の追加	宣言的マーカー1つ
データベース／ORM の切り替え	データ層のみ
ビジネス計算ルールの変更	所有するエンティティのメソッド1つ
フォームへの読み込みインジケーターの追加	基底コンポーネント／フック1つ
ドメインプリミティブへのバリデーションルールの追加	値オブジェクトのコンストラクター1つ
ページネーション／リトライ／日時アルゴリズムの変更	ヘルパー／ユーティリティー関数1つ
エンティティデータの導出処理の変更	エンティティのメソッド1つ

運用上の指針：

• まず呼び出し箇所を書きます。
• もっともらしい将来の変更について、編集箇所を数えます。
• コードを追加するより、削除することを優先します。
• 境界では前提を明示し、内部では詳細を隠します。
• 再利用前のスキャン — 自明でないコードブロックを書く前に、類似アルゴリズムを grep します（while.*skip、DateTime.*Add、split／join の連鎖、ページネーションループ、リトライループ）。既存のヘルパーが見つかったら呼び出します。見つからず、パターンがスタック全体で汎用的なら、2つ目の呼び出し元が現れる前にユーティリティーへ抽出します。
• レイヤー配置テスト — 「明日、兄弟となる呼び出し元がこれを必要としたら、同じ処理をもう一度導出するだろうか？」と考えます。答えが「はい」なら、ロジックのレイヤーが間違っています。より下位へ移します。
• 将来の再利用に備える — レビュアーが、別の機能にも現れる可能性が高いブロック（ドメイン非依存アルゴリズム、共通のライフサイクル、繰り返される導出処理）に気づいた場合、純粋な YAGNI を理由に見過ごしてはいけません。今すぐ抽出する（簡単なら）か、2つ目の呼び出し元で気づかれないまま重複しないよう、正確な抽出先を記載した追跡可能な TODO を作成します。気づかれない重複が、デフォルトの失敗パターンです。
• 判断に迷ったら、「要件が変わったとき、何を変更する必要があるだろうか？」と問いかけます。

優れたコードの尺度は変更コストです。 最短であることでも、最も巧妙であることでも、最も抽象化されていることでもありません。コードのごく一部を読めば安全に変更でき、そのコストが最も低いことです。 検証済み指摘の修正＋完全な再レビューのループ — 再レビューはラウンド数ではなく、検証済みの指摘を修正するサイクルによって開始されます。レビューの目的は、ラウンドの終了基準を満たす完全なレビューが完了するまで、「レビュー → 指摘の検証 → 検証済みの指摘の修正 → 完全な再レビュー」を繰り返すことです（以下の重大度の下限を参照）。問題のないレビューが完了した時点でループは終了します。それ以降のラウンドは不要です。

別名、自己レビュー収束ループ。 この名称は歴史的なものです。2ラウンドの上限はありません。「ダブル・ラウンドトリップ」とは、検証済みの指摘を修正するサイクルによって、少なくとも1回の新たな再レビューが必須になるという意味にすぎません。以下の3ラウンドの上限の範囲内で、問題のないレビューが完了するまで実行されます。

ラウンド上限 — 最大3ラウンド（上限であり、決して目標ではありません）。 どのラウンドでも、問題のないレビューが完了した時点でループは直ちに終了します。ラウンド1も例外ではありません。上限は、ループを続ける義務を課すものではありません。重大度の下限を適用しても、ラウンド3でブロッキング指摘が未解決の場合は、停止し、未解決の指摘を列挙してユーザーに直接確認し、エスカレーションします。上限に達したからといって、黙って「十分です」と判定して PASS を出すことは決してありません。また、上限を問題のないレビューの要件の代わりにしてはいけません。進展がない状態が2回続いた場合のブロッカールールは、引き続きそれより前の終了条件です。どちらかが先に発生した時点でエスカレーションします。

重大度の下限 — ラウンド3からは、LOW はブロッキング対象になりません。 終了基準はラウンドごとに厳格化されるため、細部の調整にこだわってループするのではなく、影響度に応じて収束します。 すべての箇所で述語を1つだけ定義します。blocking_findings(round, findings) は、ラウンド1〜2では検証済みのすべての指摘事項を返し、ラウンド3以降では検証済みのCRITICAL／HIGH／MEDIUMの指摘事項のみを返します。二値ゲート（テスト合格、セキュリティ上の必須修正、必須成果物）は、それを所有する不変条件で明示的に免除されている場合に限り、対象外です。

ラウンド	終了基準 — 新しい全件レビューが以下を満たしたらループ終了	続行するために修正必須
1-2	重大度を問わず、検証済みの指摘事項がゼロ	CRITICAL · HIGH · MEDIUM · LOW
3+	検証済みのCRITICAL／HIGH／MEDIUMの指摘事項がゼロ — LOWのみなら合格	CRITICAL · HIGH · MEDIUMのみ

ラウンド3以降、LOWの指摘事項は修正必須ではありません。検証済みの指摘事項がすべてLOWのラウンドは、ループをただちに終了します。それらを理由に次のラウンドを開始してはいけません。重大度の区分はSYNC:severity-rubric（CRITICALはマージをブロック · HIGHは必須修正 · MEDIUMは修正推奨 · LOWは可能なら修正）に従います。ラウンド1〜2の基準は変わらないため、簡単に直せるLOWも、早い段階で修正します。

重大度下限ルール：

• 保留したLOWを黙って除外してはいけません。 修正されていないLOWはすべて、ファイル、行、説明とともに最終レポートの## Deferred LOW Findings (severity floor, round ≥3)に記載し、担当者が対応を予定できるようにします。レポートから除外することは、クリーンな合格ではなくプロトコル違反です。
• 終了条件を満たすために指摘事項の区分を下げてはいけません。 実際にはCRITICAL／HIGH／MEDIUMである指摘事項をLOWに格下げしてループを終了するのは、誤った合格です。重大度はSYNC:severity-rubricに従い、終了基準を適用する前に、影響度に基づいて決めます。適用後に決めてはいけません。また、終了を意識して決めてもいけません。理由：ラベルを付け替えれば到達できる下限は、下限ではありません。
• 下限が制約するのはループであり、基準ではありません。 下限は_反復_を終了させるものであり、既知のCRITICAL／HIGH／MEDIUMを含む状態でのリリースを許可するものではありません。また、指摘事項を採用する際の指摘事項存続基準を引き下げるものでもありません。
• 下限はハードゲートには適用されません。 テスト合格ゲート（テストスイートが実際に合格する必要があります）、セキュリティ上の必須修正ゲート、および重大度ではなく二値の基準を持つゲートは影響を受けません。テスト失敗は失敗であり、LOWの指摘事項ではありません。

全般的な適用範囲（新たな出力／判断すべて）： 新たに作成した出力や判断には、少なくとも1回のセルフレビューが必要です。新たな判断には、少なくとも1回の$why-review --validate-findingsパスが必要です。再確認の対象として指摘されたものは、その出力を最終版として扱う前に、少なくとも1回再確認します。このループは、レビュー用スキルだけでなく、成果物を作成するあらゆるスキルに適用されるデフォルトの収束契約です。

ルーティング不変条件（スキル作成者向け）： 指摘事項を検証するスキルは、それらを必ず$why-review --validate-findings（最終バリデーター）に渡す必要があります。インラインの指摘事項検証を独自に実装してはいけません。why-reviewを経由することで、指摘事項存続基準とこのループが適用されます。verify-review-validate-coverageセンサーは、このルートが使われていることを機械的に検証します。

ラウンド1： メインセッションでレビューします。対象ファイルを読み、内容を把握し、問題点を記録します。指摘事項と判定（PASS／FAIL）を出力します。

ラウンド1後の判断：

• 問題なし（PASS、指摘事項ゼロ） → レビューを終了します。確認のために新しいサブエージェントを起動してはいけません。
• blocking_findings(round, findings)が空でない → まず、使用中のレビュー用スキルの指摘事項検証ゲートを実行します。レビュー用スキルのデフォルトゲートは$why-review --validate-findings <report-path>です。検証済みの指摘事項のみを修正し、その後、新しいタスク分解を使ってレビュー手順を最初からやり直します。

修正サイクルのたびに、新しい全件レビューを行います： 現在の対象全体に対し、レビュー手順を最初から実行します。その手順でサブエージェントを使用する場合は、spawn_agentを新たに呼び出してください。以前のエージェントを再利用してはいけません。レビュアーは、前のラウンドの記憶を一切持たず、すべてのファイルを最初から読み直します。起動方法についてはSYNC:fresh-context-review、標準のAgentプロンプトテンプレートについてはSYNC:review-protocol-injectionを参照してください。新しい全件レビューでは、次の点を必ず検出します。

• 前のラウンドで見落とされた横断的な問題
• 変更したファイル間の相互作用によるバグ
• 規約からの逸脱（新しいコードと既存パターンとの不整合）
• 存在すべきなのに欠けている要素
• 前のラウンドで合理化され、見過ごされた微妙なエッジケース
• 修正自体が引き起こしたリグレッション

ループの終了： 全件レビューを再実施するたびに、そのラウンドの終了基準に照らして同じ判断を繰り返します。基準を満たしたら終了し、ブロッキング指摘事項が残っていれば、指摘事項を検証し、修正して、最初のレビュー段階からやり直します。ラウンド1〜2では、重大度を問わず指摘事項がゼロなら終了です。ラウンド3以降はCRITICAL／HIGH／MEDIUMがゼロなら終了するため、LOWのみのラウンドでループを終了します（保留するLOWはレポートに記載します）。上限は3ラウンドです。次のいずれかが先に発生した時点で、ユーザーに直接確認を求めてください。同じ検証済み指摘事項が、進展のないまま2回の全件実行で繰り返される · 修正にプロダクト担当者またはオーナーの判断が必要 · ラウンド3終了時点でもCRITICAL／HIGH／MEDIUMが未解決。3ラウンドを超えてループしてはいけません。また、上限到達を合格として扱ってはいけません。

ルール：

• クリーンなラウンド1でレビューを終了します。ラウンド2の実施は必須ではありません。
• ラウンド3以降、検証済みの指摘事項がすべてLOWのラウンドはループを終了します。LOWだけを修正するために次のラウンドを開始してはいけません。その代わり、LOWを保留として記載します。
• ラウンド3の終了条件を満たすために、CRITICAL／HIGH／MEDIUMをLOWに格下げしてはいけません。重大度は基準の適用前に、影響度に基づいて割り当てます。
• 未検証の指摘事項を修正してはいけません。まず、呼び出し元が指定する検証ゲートを使って検証します。
• 存続する各指摘事項は、why-reviewの指摘事項検証ルーチンで定義される指摘事項存続基準も満たす必要があります。この基準は一般的な行動判断ゲートより意図的に厳しく設定されています。「この指摘事項を残すか」は「この証拠に基づいて対応するか」より厳しい問いです。基準未満の指摘事項は、そのまま残さず、格下げするか削除します。
• 修正サイクル後の全件レビューを省略してはいけません（修正のたびに、それ以前の判定は無効になります）。
• ラウンドをまたいでサブエージェントを再利用してはいけません。サブエージェントを使う反復ごとに、新しいAgent呼び出しを起動します。
• メインエージェントはサブエージェントのレポートを読みますが、指摘事項を選別、再解釈、または覆してはいけません。
• 3ラウンドの上限が、クリーンなレビューの要件に取って代わることはありません。上限は暴走するループを抑えるためのものであり、レビューがクリーンでないままリリースすることを許可するものではありません。クリーンな合格なら、どのラウンドでもループを早期終了できます。上限に達した場合は、合格ではなくエスカレーションします。
• 3ラウンドの上限と、進展のない状態が2回繰り返された場合のブロッカールールを併せて適用します。どちらもエスカレーションのトリガーであり、完了条件ではありません。
• 再帰的な呼び出し回数と、繰り返し発生するブロッカーを、会話コンテキスト内で追跡します（セッションの範囲内）。
• 最終判定には、実行したすべてのラウンドを反映します。

レポートには、実行したラウンドN≥2ごとに## Round N Findings (Fresh Sub-Agent)を含めます。また、LOWが未解決のままラウンド3以降の終了基準でループが終了した場合は、## Deferred LOW Findings (severity floor, round ≥3)を必ず含めます。 新鮮なコンテキストでの再レビュー — 適用可能な場合は、分離されたサブエージェントでレビュー全体を再開し、修正後にオーケストレーターが確証バイアスに陥るのを防ぎます。

理由： メインエージェントは、自身（または$feature-implement）がたった今修正した内容を把握しているため、それに沿って指摘を合理化してしまいます。新しいサブエージェントには記憶がまったくなく、最初から読み直すため、メインエージェントが退けた問題を見つけられます。サブエージェントのバイアスは、（1）新しいコンテキスト、（2）プロトコルの全文挿入、（3）メインエージェントがレポートを取捨選択しないことによって軽減されます。

タイミング： 検証済みの指摘を修正するサイクルの後に限ります。問題がゼロ件だったレビューラウンドでループを終了し、確認用サブエージェントを起動してはいけません。問題が見つかったレビューラウンドでは、指摘を検証 → 修正 → 第1フェーズからレビュー全体を再開、という手順を実施します。

方法：

1. 新しいレビュー全体の実行／タスク分解を開始します。そのプロトコルでエージェントが必要な場合は、新しいspawn_agentツール呼び出しを作成します。コードレビューにはcode-reviewerのagent_typeを、計画／ドキュメント／成果物のレビューにはgeneral-purposeを使用します
2. 必須のレビュー用プロトコルをすべて、プロンプトに全文そのまま挿入します。必要な一覧とテンプレート全体はSYNC:review-protocol-injectionを参照してください。プロトコルをファイルパスで参照してはいけません。ファイル読み込みの間接参照を挟むと、AIの遵守率が低下します（SYNC:shared-protocol-duplication-policyを参照）
3. サブエージェントは、自身のツール呼び出しを使って、対象ファイルをすべて最初から読み直します。プロンプトにファイル内容をインラインで渡してはいけません
4. サブエージェントは、構造化されたレポートをplans/reports/{review-type}-round{N}-{date}.mdに書き込みます
5. メインエージェントはレポートを読み、自身のレポートに指摘を反映します。指摘を上書きしたり、取捨選択したりしてはいけません

ルール：

• 直前のレビュー全体で問題がゼロ件だった場合は、新しいサブエージェントをスキップします（修正がなければ、新たに検証する内容もありません）
• 修正サイクル後にレビュー全体を再開するのを絶対に省略してはいけません。修正が入るたびに、それまでの判定は無効になります
• ラウンドをまたいでサブエージェントを再利用してはいけません。新しいラウンドごとに、新しいspawn_agent呼び出しを作成します
• SYNC:double-round-trip-reviewに定めるラウンドの終了基準を満たすまで続けます。ラウンド1～2では、重大度を問わず指摘がゼロ件であること。ラウンド3以降では、CRITICAL／HIGH／MEDIUMの指摘がゼロ件であること。したがって、検証済みの指摘がすべてLOWであるラウンドではループを終了し、次のラウンドを開始する代わりに、該当するLOWの指摘を繰り越し項目として列挙します。同じブロッカーが進展なしに3回繰り返された場合は、ユーザーに直接確認してエスカレーションします
• 反復回数と繰り返し発生するブロッカーは、会話のコンテキストで管理します（セッション内のみとし、永続ファイルには保存しません）

レビュー用プロトコルの挿入 — 新しいサブエージェントのレビュープロンプトには、11個のプロトコルブロックをすべて全文そのまま含める必要があります。以下のテンプレートには、11個すべての本文がすでにインラインで展開されています。実行時にテンプレート全体をAgent呼び出しのpromptフィールドへそのままコピーし、「Task／Round／Reference Docs／Target Files／Output」セクションの{placeholders}のみ、コンテキストに応じた値に置き換えてください。埋め込み済みのプロトコルセクションには手を加えないでください。

インライン展開の理由： プレースホルダーマーカーを使うと、実行時にファイル読み込みの間接参照が必要になります。間接参照を挟むとAIの遵守率が大幅に低下します（SYNC:shared-protocol-duplication-policyを参照）。そのため、このテンプレートには11個すべてのプロトコル本文があらかじめ埋め込まれています。

サブエージェントの種類の選択

• code-reviewer — コードレビュー用（ソースファイル、Gitの差分、実装のレビュー）
• general-purpose — 計画／ドキュメント／成果物のレビュー用（Markdownの計画書、ドキュメント、仕様のレビュー）

エージェント呼び出しの標準テンプレート（そのままコピー）

spawn_agent({
  description: "Fresh Round {N} review",
  agent_type: "code-reviewer",
  prompt: `
## Task
{review-specific task — e.g., "Review all uncommitted changes for code quality" | "Review plan files under {plan-dir}" | "Review integration tests in {path}"}

## Round
Round {N}. You have ZERO memory of prior rounds. Re-read all target files from scratch via your own tool calls. Do NOT trust anything from the main agent beyond this prompt.

## Protocols (follow VERBATIM — these are non-negotiable)

### Spec ↔ Tests ↔ Code Triangulation
DO THIS FIRST — before any per-protocol check below. The review target is the WHOLE PACKAGE, not the diff alone: load the behavior's spec (§3 ACs / §4 BRs / §8 TCs), its tests, and the changed code TOGETHER, and reason about their mutual consistency BEFORE judging any one in isolation.
1. Locate all three faces: the Feature Spec section(s) governing the changed behavior, the tests that guard it, and the production code that implements it. A missing face is itself a finding (SPEC-GAP / TEST-GAP / DEAD-SPEC).
2. Triangulate pairwise — every disagreement is a finding; classify which face is wrong:
   - code vs spec: behavior the code does that no §3/§4/§8 rule describes → CODE-EXTRA or SPEC-STALE; a [HARD] §4 rule or §5 invariant with no enforcing code path → CODE-WRONG.
   - tests vs spec: a §8 TC with no test, or a test asserting behavior no TC/rule names → TEST-GAP or SPEC-SILENT.
   - tests vs code: a changed code path with no covering test → TEST-GAP; a test that still passes against a deliberately broken invariant → WEAK-TEST (apply the mutation thinking in Bug Detection).
3. Hidden-rule capture: any invariant the code enforces but the spec never states (SPEC-SILENT) MUST be surfaced as a finding to add into §3/§4/§8 AND guarded with a test — the enrichment loop, never a silent pass.
4. Only after the three faces agree — or every disagreement is logged as a finding — proceed to the per-protocol checks below; when enrichment adds spec/test content, re-review the package against the enriched spec.
NEVER mark review PASS while any spec/test/code face disagrees without a logged finding. The diff is the entry point; the package is the unit of judgment.

### Evidence-Based Reasoning
Speculation is FORBIDDEN. Every claim needs proof.
1. Cite file:line, grep results, or framework docs for EVERY claim
2. Declare confidence: >80% act freely, 60-80% verify first, <60% DO NOT recommend
3. Cross-service validation required for architectural changes
4. "I don't have enough evidence" is valid and expected output
BLOCKED until: Evidence file path (file:line) provided; Grep search performed; 3+ similar patterns found; Confidence level stated.
Forbidden without proof: "obviously", "I think", "should be", "probably", "this is because".
If incomplete → output: "Insufficient evidence. Verified: [...]. Not verified: [...]."

### Bug Detection
MUST check categories 1-4 for EVERY review. Never skip.
1. Null Safety: Can params/returns be null? Are they guarded? Optional chaining gaps? .find() returns checked?
2. Boundary Conditions: Off-by-one (< vs <=)? Empty collections handled? Zero/negative values? Max limits?
3. Error Handling: Try-catch scope correct? Silent swallowed exceptions? Error types specific? Cleanup in finally?
4. Resource Management: Connections/streams closed? Subscriptions unsubscribed on destroy? Timers cleared? Memory bounded?
5. Concurrency (if async): Missing await? Race conditions on shared state? Stale closures? Retry storms?
6. Stack-Specific: Check the configured language/runtime pitfalls and framework-specific failure modes discovered from local code.
Classify: CRITICAL (crash/corrupt) → FAIL | HIGH (incorrect behavior) → FAIL | MEDIUM (edge case) → WARN | LOW (defensive) → INFO.

### Design Patterns Quality
Priority checks for every code change:
1. DRY via OOP: Same-suffix classes (*Entity, *Dto, *Service) MUST share base class. 3+ similar patterns → extract to shared abstraction.
2. Right Responsibility: Logic in LOWEST layer (Entity > Domain Service > Application Service > Controller). Never business logic in controllers.
3. SOLID: Single responsibility (one reason to change). Open-closed (extend, don't modify). Liskov (subtypes substitutable). Interface segregation (small interfaces). Dependency inversion (depend on abstractions).
4. After extraction/move/rename: Grep ENTIRE scope for dangling references. Zero tolerance.
5. YAGNI gate: NEVER recommend patterns unless 3+ occurrences exist. Don't extract for hypothetical future use.
Anti-patterns to flag: God Object, Copy-Paste inheritance, Circular Dependency, Leaky Abstraction.

### Logic & Intention Review
Verify WHAT code does matches WHY it was changed.
1. Change Intention Check: Every changed file MUST serve the stated purpose. Flag unrelated changes as scope creep.
2. Happy Path Trace: Walk through one complete success scenario through changed code.
3. Error Path Trace: Walk through one failure/edge case scenario through changed code.
4. Acceptance Mapping: If plan context available, map every acceptance criterion to a code change.
5. Tests Verify Intent: For test/spec changes, verify tests name the protected business rule or invariant and would fail if that intent breaks.
6. Migration Test Exclusion: Do not write tests for migration code. Schema/data migrations are one-time execution paths, not core application logic.
NEVER mark review PASS without completing both traces (happy + error path).

### Test Spec Verification
Map changed code to test specifications.
1. Identify the project's test/spec format from existing docs, test-case files, BDD feature files, or spec folders.
2. Every changed code path MUST map to a corresponding test case/spec (or flag as "needs test case").
3. New functions/endpoints/handlers → flag for test spec creation.
4. Migration files are excluded from test/spec creation; schema/data migrations are one-time execution paths, not core application logic.
5. If spec evidence fields exist, verify they point to actual code (file:line, not stale references).
6. Verify each meaningful test case names the business intent/invariant; flag behavior-only cases that only mirror implementation details.
7. Auth/data changes → verify corresponding authorization and data-state test cases exist.
8. If no specs exist for a changed path → log the gap and recommend the project's test-spec workflow.
NEVER skip test mapping. Untested code paths are the #1 source of production bugs.

### Behavioral Delta Matrix
MANDATORY for any bugfix review. Produce input-state × pre-fix × post-fix × delta table BEFORE writing verdict.
- Minimum 3 rows; include at least one row OUTSIDE the original bug report.
- Any "REGRESSION" delta → review returns FAIL until a preservation test is added.
- Narrative descriptions do NOT substitute for the matrix.
Example rows (external-record sync fix):
| Input                 | Pre-fix | Post-fix                  | Delta      |
| --------------------- | ------- | ------------------------- | ---------- |
| Record exists (valid) | Reused  | Always recreated → orphan | REGRESSION |
| Record missing (404)  | Error   | Recreated                 | Fixed      |

### Fix-Layer Accountability
NEVER fix at the crash site. Trace the full flow, fix at the owning layer. The crash site is a SYMPTOM, not the cause.
MANDATORY before ANY fix:
1. Trace full data flow — Map the complete path from data origin to crash site across ALL layers (storage → backend → API → frontend → UI). Identify where bad state ENTERS, not where it CRASHES.
2. Identify the invariant owner — Which layer's contract guarantees this value is valid? Fix at the LOWEST layer that owns the invariant, not the highest layer that consumes it.
3. One fix, maximum protection — If fix requires touching 3+ files with defensive checks, you are at the wrong layer — go lower.
4. Verify no bypass paths — Confirm all data flows through the fix point. Check for direct construction skipping factories, clone/spread without re-validation, raw data not wrapped in domain models, mutations outside the model layer.
BLOCKED until: Full data flow traced (origin → crash); Invariant owner identified with file:line evidence; All access sites audited (grep count); Fix layer justified (lowest layer that protects most consumers).
Anti-patterns (REJECT): "Fix it where it crashes" (crash site ≠ cause site, trace upstream); "Add defensive checks at every consumer" (scattered defense = wrong layer); "Both fix is safer" (pick ONE authoritative layer).

### Rationalization Prevention
AI skips steps via these evasions. Recognize and reject:
- "Too simple for a plan" → Simple + wrong assumptions = wasted time. Plan anyway.
- "I'll test after" → RED before GREEN. Write/verify test first.
- "Already searched" → Show grep evidence with file:line. No proof = no search.
- "Just do it" → Still need task tracking. Skip depth, never skip tracking.
- "Just a small fix" → Small fix in wrong location cascades. Verify file:line first.
- "Code is self-explanatory" → Future readers need evidence trail. Document anyway.
- "Combine steps to save time" → Combined steps dilute focus. Each step has distinct purpose.

### Graph-Assisted Investigation
MANDATORY when .code-graph/graph.db exists.
HARD-GATE: MUST run at least ONE graph command on key files before concluding any investigation.
Pattern: Grep finds files → trace --direction both reveals full system flow → Grep verifies details.
- Investigation/Scout: trace --direction both on 2-3 entry files
- Fix/Debug: callers_of on buggy function + tests_for
- Feature/Enhancement: connections on files to be modified
- Code Review: tests_for on changed functions
- Blast Radius: trace --direction downstream
CLI: python .claude/scripts/code_graph {command} --json. Use --node-mode file first (10-30x less noise), then --node-mode function for detail.

### Understand Code First
HARD-GATE: Do NOT write, plan, or fix until you READ existing code.
1. Search 3+ similar patterns (grep/glob) — cite file:line evidence.
2. Read existing files in target area — understand structure, base classes, conventions.
3. Run python .claude/scripts/code_graph trace <file> --direction both --json when .code-graph/graph.db exists.
4. Map dependencies via connections or callers_of — know what depends on your target.
5. Write investigation to .ai/workspace/analysis/ for non-trivial tasks (3+ files).
6. Re-read analysis file before implementing — never work from memory alone.
7. NEVER invent new patterns when existing ones work — match exactly or document deviation.
BLOCKED until: Read target files; Grep 3+ patterns; Graph trace (if graph.db exists); Assumptions verified with evidence.

## Reference Docs (READ before reviewing)
- `.claude/docs/development-rules.md` — canonical development rules, code-quality guidelines, and pre-commit checklist
- docs/project-reference/code-review-rules.md
- {skill-specific reference docs — e.g., integration-test-reference.md for integration-test-review; backend-patterns-reference.md for backend reviews; frontend-patterns-reference.md for frontend reviews}

## Target Files
{explicit file list OR "run git diff to see uncommitted changes" OR "read all files under {plan-dir}"}

## Output
Write a structured report to plans/reports/{review-type}-round{N}-{date}.md with sections:
- Status: PASS | FAIL
- Issue Count: {number}
- Critical Issues (with file:line evidence)
- High Priority Issues (with file:line evidence)
- Medium / Low Issues
- Cross-cutting findings

Return the report path and status to the main agent.
Every finding MUST have file:line evidence. Speculation is forbidden.
`
})

ルール

• テンプレートを、埋め込み済みのプロトコルセクション11個を含めてそのままコピーしてください
• Task／Round／Reference Docs／Target Files／Output セクションの {placeholders} のみを、コンテキストに応じた内容に置き換えてください
• コードレビューには code-reviewer の agent_type を、計画／ドキュメント／成果物のレビューには general-purpose を選択してください
• プロトコルセクションの言い換え、要約、省略はしないでください
• ファイルの内容をインラインで渡さないでください。サブエージェントは独自のツール呼び出しで読み取るため、新鮮なコンテキストを得られます
• プロトコルをファイルパスやタグ名で参照しないでください。本文はすでに上記に埋め込まれています
• プロトコル用のプレースホルダーマーカーを導入しないでください。プロトコルは文字どおり展開された状態にしてください

合理化による手順の省略を防ぐ — AI は次のような言い逃れで手順を省略します。見抜いて拒否してください：

言い逃れ	反論
「計画を立てるほど複雑ではない」	簡単な作業でも前提を誤れば時間を無駄にします。必ず計画してください。
「あとでテストします」	GREEN の前に RED です。まずテストを書き、検証してください。
「すでに検索しました」	file:line 形式の grep 結果を示してください。証拠がなければ検索したことになりません。
「とにかく実行します」	タスクの追跡は依然として必要です。深さは省略しても、追跡は省略しないでください。
「小さな修正です」	間違った箇所への小さな修正が、問題を連鎖させることがあります。まずファイルと行を確認してください。
「コードを見れば分かります」	将来の読者には根拠をたどれる記録が必要です。必ず記録してください。
「時間短縮のために手順をまとめます」	手順をまとめると焦点がぼやけます。それぞれの手順には固有の目的があります。

ロジックと意図のレビュー — コードの動作が、変更の理由と一致していることを確認してください。

1. 変更意図の確認： 変更したすべてのファイルは、必ず明記された目的に沿っている必要があります。無関係な変更はスコープクリープとして指摘してください。
2. 正常系の追跡： 変更したコードを通じて、成功するシナリオを最初から最後までたどってください
3. エラー系の追跡： 変更したコードを通じて、失敗またはエッジケースのシナリオをたどってください
4. 受け入れ条件との対応付け： 計画のコンテキストがある場合、すべての受け入れ条件をコード変更に対応付けてください
5. 意図を検証するテスト： テスト／仕様の変更では、テストが保護対象のビジネスルールまたは不変条件を明示し、その意図が崩れたときに失敗することを確認してください。
6. マイグレーションのテスト除外： マイグレーションコードのテストは作成しないでください。スキーマ／データのマイグレーションは一度限りの実行経路であり、アプリケーションの中核ロジックではありません。

正常系とエラー系の両方を最後まで追跡せずに、レビューを PASS と判定してはいけません。

バグ検出 — すべてのレビューで、カテゴリ1〜4を必ず確認してください。省略してはいけません。

1. Null 安全性： パラメーターや戻り値が null になる可能性はありますか？ 適切にガードされていますか？ オプショナルチェーンの抜けはありませんか？ .find() の戻り値は確認されていますか？
2. 境界条件： オフバイワン（< と <= の違いなど）はありませんか？ 空のコレクションは処理されていますか？ ゼロ値／負の値や最大制限は考慮されていますか？
3. エラー処理： try-catch の範囲は適切ですか？ 例外を黙って握りつぶしていませんか？ エラーの種類は具体的ですか？ finally でクリーンアップしていますか？
4. リソース管理： 接続／ストリームは閉じられていますか？ 破棄時にサブスクリプションを解除していますか？ タイマーはクリアされていますか？ メモリ使用量に上限がありますか？
5. 並行性（非同期処理がある場合）： await の不足はありませんか？ 共有状態に競合状態はありませんか？ 古くなったクロージャーやリトライの集中はありませんか？
6. 技術スタック固有の問題： 設定された言語／ランタイムで注意すべき落とし穴と、ローカルコードから判明したフレームワーク固有の障害モードを確認してください。

分類： CRITICAL（クラッシュ／破損）→ FAIL | HIGH（誤った動作）→ FAIL | MEDIUM（エッジケース）→ WARN | LOW（防御的対応）→ INFO テスト仕様の検証 — 変更したコードをテスト仕様に対応付けます。

1. 既存のドキュメント、テストケースファイル、BDD のフィーチャーファイル、または仕様フォルダーから、プロジェクトのテスト／仕様形式を特定します。
2. 変更したコードパスはすべて、対応するテストケース／仕様に必ず対応付けます（または「テストケースが必要」としてフラグを立てます）。
3. 新しい関数／エンドポイント／ハンドラーには、テスト仕様の作成が必要であることを示します。
4. マイグレーションファイルは、テストケース／テストの作成対象から除外します。スキーマ／データのマイグレーションは一度限りの実行パスであり、コアアプリケーションロジックではありません。
5. 仕様の根拠を示すフィールドがある場合は、実際のコードを指していること（古い参照ではなく file:line）を確認します。
6. 意味のある各テストケースが、ビジネス上の意図／不変条件を示していることを確認します。実装の詳細をなぞるだけの振る舞いテストにはフラグを立てます。
7. 認証／データの変更については、対応する認可とデータ状態のテストケースが存在することを確認します。
8. 変更したパスに仕様がない場合は、その不足を記録し、プロジェクトのテスト仕様ワークフローを推奨します。

テストとの対応付けを絶対に省略しないでください。 テストされていないコードパスは、本番環境のバグの最大の原因です。

修正レイヤーの責任 — クラッシュが発生した箇所では絶対に修正しないでください。処理全体をたどり、担当レイヤーで修正します。

AI のデフォルトの動作：場所 A でエラーを確認 → 場所 A を修正。これは誤りです。クラッシュ箇所は症状であり、原因ではありません。

修正前に必ず行うこと：

1. データフロー全体をたどる — データの発生元からクラッシュ箇所まで、すべてのレイヤー（ストレージ → バックエンド → API → フロントエンド → UI）を通る完全な経路をマッピングします。不正な状態がクラッシュする場所ではなく、どこで入り込むのかを特定します。
2. 不変条件の責任レイヤーを特定する — この値が有効であることを保証する契約を持つレイヤーはどれですか？ そのレイヤーが責任を負います。不変条件を消費する最上位のレイヤーではなく、その不変条件を所有する最下位のレイヤーで修正します。
3. 修正は一つにし、保護を最大化する — 「ここを修正すれば、一度の変更ですべての下流の利用箇所を保護できるか？」と問いかけます。防御的チェックのために3つ以上のファイルを変更する必要があるなら、レイヤーが間違っています。さらに下位のレイヤーを探してください。
4. 迂回経路がないことを確認する — すべてのデータフローが修正箇所を通ることを確認します。ファクトリーを経由しない直接構築、再検証を伴わないクローン／スプレッド、ドメインモデルでラップされていない生データ、モデルレイヤー外での変更がないかを確認します。

次の項目が完了するまで作業はブロックされます： - [ ] データフロー全体を追跡済み（発生元 → クラッシュ） - [ ] 不変条件の責任レイヤーを file:line の根拠とともに特定済み - [ ] すべてのアクセス箇所を監査済み（grep 件数） - [ ] 修正レイヤーの妥当性を説明済み（最も多くの利用箇所を保護する最下位レイヤー）

アンチパターン（却下してください）：

• 「クラッシュした場所で直す」 — クラッシュ箇所 ≠ 原因箇所です。上流をたどってください。
• 「すべての利用箇所に防御的チェックを追加する」 — 防御の分散はレイヤーの誤りを示します。権威ある修正一つのほうが、多数の分散したガードより優れています。
• 「両方修正したほうが安全」 — 権威あるレイヤーを一つ選んでください。レイヤーをまたいで重複したチェックを行うと、不変条件の責任者について誤解を招きます。

ソース／テストの乖離チェック。 コーディング、修正、デバッグ、調査、テスト、レビューの作業では、ソースの振る舞いが変わった際に、影響を受ける単体テスト／統合テスト／E2E テストを調べ、意図した振る舞いに合わせてテストを変更すべきか、ソースの変更が意図しないバグであり修正すべきかを、根拠に基づいて判断します。マイグレーションコードのテストは作成しないでください。スキーマ／データのマイグレーションは一度限りの実行パスであり、コアアプリケーションロジックではありません。 AI のミス防止 — すべてのタスクで避けるべき失敗モード：

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

重大度の基準 — 修正の容易さではなく、結果に基づいてすべての指摘を分類してください。すべてのレビューで同じ尺度を使い、「高」がどこでも同じ意味になるようにしてください。

重大度	対応	定義
CRITICAL	マージをブロック	実行時のサイレントな失敗、データ破損、検証の回避、セキュリティホール
HIGH	必ず修正	誤った動作、不変条件の欠落、アーキテクチャ違反
MEDIUM	修正を推奨	設計上の負債、保守性、将来のバグにつながる可能性
LOW	修正できると望ましい	規約、ドキュメント、軽微な明確さの問題

スコアに基づくスキルでは、数値尺度をこれらの段階に対応づけてください。別の用語体系を作らないでください。

• 0-2 の基準スコアリング（例：production-readiness-review）：0 = CRITICAL/HIGH（基準を満たしておらず、本番利用の準備をブロックする）、1 = MEDIUM（部分的に満たしており、修正を推奨）、2 = 合格（指摘なし）。
• 2 軸スコアリング（例：パフォーマンスレビュー、影響度 × 発生可能性）：結果のセルを最も近い段階に対応づけてください。影響度が高く、発生可能性も高い場合 → CRITICAL/HIGH、影響度が低い、または発生可能性が低い場合 → MEDIUM/LOW。

指摘の段階によってゲートが決まります。CRITICAL/HIGH は PASS の前に解決するか、責任者が明示的に受け入れる必要があります。MEDIUM/LOW は、追跡可能なフォローアップを設定したうえでリリースできます。 目標契約の充足ループ — ユーザーの目標を外部ファイルに保存して、それに基づいて実行し、保存されたすべての必須基準に合格するか、ブロッカーがエスカレーションされるまでレビューと修正を繰り返します。範囲を限定したクローズドループです。終わりのない自律的な探索は絶対に行いません。

1. 有効な目標を解決する（次の順）：有効な計画の goal.md → plans/goals/{YYMMDD-HHmm}-{slug}/goal.md → 現在のユーザーリクエストから新しい目標契約を作成する（テンプレート：.claude/templates/goal-contract-template.md）。
2. 必須セクション： Original Request、Purpose、Success Criteria（チェックボックス。必須か任意かを明記）、Constraints、Evidence Required、Iteration Log、Goal Satisfaction matrix。
3. 作業前： 有効な目標を読み、予定している作業を保存済みの成功基準に対応付けます。実行は保存済みの基準に基づいて行い、チャットの記憶だけに頼ってはいけません。
4. 実行／検証後： 結果、証拠の参照先（file:line、コマンド出力、レポートのパス）、残っているギャップを記載した Iteration Log のエントリーを追記します。
5. レビューチェックポイント： Goal Satisfaction matrix を出力します。形式は | Success Criterion | Evidence | Status | とし、ステータスは PASS／FAIL／BLOCKED とします。全体を PASS とするには、すべての必須基準が PASS である必要があります。
6. ループ規則（再試行）： 必須基準が FAIL → ギャップが実在することを検証 → 修正 → 影響を受ける基準のみ再レビュー。すべての必須基準が PASS になったら、適切に停止します。
7. エスカレーション規則（停止）： 基準に進展がない状態が2回連続する場合、またはユーザーの入力が必要なブロッカーがある場合は、ユーザー向けの理由を添えて基準を BLOCKED とし、エスカレーションします。無期限にループしてはいけません。
8. スキップ規則： 簡単な会話タスクでは、記録に一行の理由を残す場合に限り、目標ファイルを省略できます。ユーザーが承認したチェックポイントのスキップは、理由と範囲を添えて目標ファイルに記録します。
9. セキュリティ： 目標ファイルにシークレット、トークン、認証情報、顧客の個人データを保存してはいけません。証拠の参照先を記録し、機密情報の値はマスキングしてください。

以下を満たすまで先に進めません： 有効な目標を解決する（またはスキップ理由を記録する） · 編集前に保存済みの成功基準を読む · 実行後に反復の証拠を追記する · PASS 判定の前に Goal Satisfaction matrix を出力する トレードオフの確認ゲート — いかなる判定、スコア、指摘、推奨を出す前にも、必ず次の3つの質問を行ってください。レビュー対象そのものについてだけでなく、あなたが提示するすべての推奨についても同様です。理由：代償を示さずにメリットだけを挙げるのはレビューではなく、賛同です。最も大きな代償は、誰も書き留めなかったものです。

1. トレードオフはありますか？ 何を犠牲にするのかを明示してください。「なし」／「純粋なメリット」は分析未完了であり、回答ではありません。ないと主張する場合は、確認した観点と、それぞれに影響がない理由を述べてください：将来の変更コスト · 複雑さ · パフォーマンス／レイテンシー · メモリ／コスト · 結合度 · 可逆性 · 移行の負担 · 運用負荷 · 影響範囲 · セキュリティ態勢 · テスト容易性 · チームのスキル／習熟期間 · 提供までの時間 · UX。
2. それだけの価値はありますか？ 得られるもの（指標を含む） · かかるコスト · 誰が負担するか · いつ発生するかを明示して、メリットと代償を比較し、そのうえで 価値がある／価値がない／不明 と判定してください。指標もコストも示さない「より良い」は、この質問への回答として不合格です。「価値がない」場合は、そのまま推奨し続けず、撤回または代替してください。
3. そのトレードオフは、ユーザーに確認するだけの重要性がありますか？ 重要なトレードオフを決めるのはユーザーであり、あなたではありません。次のいずれかに該当する場合は重要です：不可逆／一方通行（データ移行、公開契約、ストレージ形式、ベンダーロックイン） · コストを他者に転嫁する（別チーム、運用／オンコール担当、将来のメンテナー、エンドユーザー） · ある品質特性を別の品質特性と引き換える（正確性↔速度、セキュリティ↔利便性、レイテンシー↔コスト、シンプルさ↔柔軟性） · 境界を越える（クライアント↔サーバー層、サービス契約、イベント契約、共有ライブラリ） · 重大な影響を伴う経路（認証、金銭、データ整合性、破壊的変更、残存リスクが高または中） · 価値の判定が不明。

重要 → 判定を確定させずに停止し、ユーザーに直接確認してください — トレードオフ、両方の選択肢、それぞれが犠牲にするもの、そしてあなたの推奨を示してください。重要でない → 1行の根拠とともにその場に記録し、続行してください。

質問できない実行コンテキスト — 黙って済ませず、引き継いでエスカレーションしてください。 ユーザーへの直接質問が届くのはメインの対話型エージェントだけです。サブエージェントはユーザーに質問できず、ターミナル／判定のみのモードは設計上、何も質問しません。そのようなコンテキストで実行している場合、義務は免除ではなく、転送されます。次のすべてを行ってください：(a) 質問1と2を通常どおり完了する。(b) 重要度を判定し、トレードオフ評価の行に confirmed? = NO — cannot ask from this context と記録する。(c) 未確認の重要なトレードオフを返却する要約／判定で明示し、呼び出し元（または親オーケストレーター）があなたに代わってユーザーに直接確認するようエスカレーションする — ディスク上のレポートファイル内だけで触れられた重要なトレードオフは、引き継ぎとはみなされません。(d) 無条件の PASS を出さない — 判定に未確認の重要なトレードオフがあると明記し、ユーザーが回答するまで呼び出し元のゲートが閉じたままになるようにする。呼び出し元は、あなたの返答を読んだ時点でエスカレーション義務を引き継ぎます。

この例外が対象とするのは到達可能性であり、利便性ではありません。ユーザーに実際に連絡できない場合（起動されたサブエージェント、ターミナルの検証／判定のみのモード、非対話型／ヘッドレス実行）に限り適用されます。質問を省略する、一方通行の変更を独断で承認する、質問が面倒だから重要度を下げる許可には決してなりません — 質問できるなら、必ず質問してください。

レビュー対象の判断ごと、および推奨ごとに、トレードオフ評価の行を出力してください：| decision | sacrifices | gain (metric) | who pays, when | WORTH IT/NOT/UNCLEAR | material? | confirmed? |。

次の条件を満たすまで進行不可：トレードオフが明示されている（または、確認した観点を挙げた根拠が示されている） · 価値の判定が出されている · 重要度が判定されている · すべての重要なトレードオフがユーザーに確認済み、または — 質問できないコンテキストでは — 呼び出し元が確認できるよう返却する判定に引き継がれている。確認も引き継ぎもされていない重要なトレードオフを、PASS と判定することはできません。また、重大度の低い注記として埋もれさせてはなりません。

トレードオフを確認せずに「トレードオフはない」と答えてはなりません · ユーザーに代わって重要なトレードオフを黙って決めてはなりません · 意見の収束や提供のプレッシャーを、一方通行の変更を強行する根拠にしてはなりません · 複数の重要なトレードオフを曖昧な「進めますか？」にまとめてはなりません。

• MANDATORY MUST ATTENTION あらゆる指摘について、file:line 形式の根拠を示してください。確信度が80％を超える場合のみ対応し、60％未満の場合は推奨しないでください。

• MANDATORY MUST ATTENTION OOP を通じて DRY を確認してください（同じサフィックス → 基底クラス）。責務が適切な層（最も下位の層）にあることと、SOLID を確認してください。変更後は、参照先がなくなった項目が残っていないか Grep で確認してください。

• MANDATORY MUST ATTENTION 複雑さの抑制を徹底してください。ビジネス上の変更1件につき、コード変更は1件にします。変更の波及（将来の変更に3か所を超える編集が必要な状態）、散在する型切り替え、貧血モデル、プリミティブ型への執着、抽象化を通じた技術要素の漏出、浅いモジュール、切り出されていないユーティリティロジック（ページング／日時／文字列／リトライ → ヘルパー）、誤った上位層にあるロジック（呼び出し先／エンティティ／VM に移動）を指摘してください。純粋な YAGNI を理由に、気づかれにくい重複を正当化してはいけません。

• MANDATORY IMPORTANT MUST ATTENTION レビューループ（別名 セルフレビュー収束ループ）を実行してください。レビュー → 指摘内容の検証 → 検証済みの指摘の修正 → 全体の再レビュー。指摘がゼロの完全なレビューが完了したら、レビューを終了します。新たに生成した出力や判断は、少なくとも1回セルフレビューしてください。新たな判断は、最終判断として扱う前に、少なくとも1回 $why-review --validate-findings を実行してください。

• MANDATORY 重大度の下限を適用してください。ラウンド1～2は重大度を問わず指摘がゼロになった時点で終了します。**ラウンド3以降は、CRITICAL／HIGH／MEDIUM の指摘をゼロにすることが基準です。LOW の指摘は修正不要となるため、LOW のみのラウンドはループを終了します。**報告書には、対応を保留したすべての LOW の指摘を記載してください。終了条件を満たすために、実際の CRITICAL／HIGH／MEDIUM を LOW に分類し直してはいけません。また、この下限を二値判定のゲート（テストが成功していること、セキュリティ上必須の修正）に適用してはいけません。

• MANDATORY ラウンド上限を3に設定してください。これは上限であり、目標ではありません。クリーンなレビューが完了したら、ラウンド1を含め、どのラウンドでも直ちにループを終了します。ラウンド3の完了時に CRITICAL／HIGH／MEDIUM の指摘が未解決の場合は、停止して、ユーザーに直接確認を求めてエスカレーションしてください。暗黙の PASS は禁止です。進展のない状態が2回繰り返された場合のブロッカー規則は、これより早い終了条件です。いずれかの条件に先に達した時点でエスカレーションしてください。終わりのないループを行ってはいけません。

• MANDATORY MUST ATTENTION 簡単に見えるかどうかにかかわらず、すべての手順を実行してください。「計画するほど複雑ではない」は回避であり、理由にはなりません。

• MANDATORY MUST ATTENTION graph.db が存在する場合、主要ファイルに対してグラフコマンドを少なくとも1つ実行してください。手順：grep → グラフトレース → grep で検証。

• MANDATORY MUST ATTENTION 変更したすべてのファイルが、明示された目的に役立っていることを確認してください。正常系とエラー系の処理経路を追跡してください。スコープの逸脱を指摘してください。

• MANDATORY MUST ATTENTION 毎回のレビューで、null 安全性、境界条件、エラー処理、リソース管理を確認してください。

• MANDATORY MUST ATTENTION 変更したすべての関数／エンドポイントをテストに対応付けてください。変更箇所の近くにある、プロジェクトのテスト仕様形式を探してください。カバレッジの不足を指摘し、テストの作成を推奨してください。

• MANDATORY MUST ATTENTION 多言語対応のフロントエンド／UI テキストを変更する場合は、PASS とする前に翻訳の更新が反映されていることを確認してください。更新されていない場合は、リスクをユーザーが明示的に承認していることを確認してください。

MUST ATTENTION 最初のレビューでは、まず変更の背景を記録し、影響を受ける主要領域のパイプライン全体を、クライアント↔サーバー境界をまたいで包括的に追跡してください（BE→FE は順方向、FE→BE は逆方向）。両層でルート／DTO／フィールド／型／null 許容性／認証が一致していることを確認してください。不一致があれば BREAKING の指摘として扱います。単一層のみの変更、またはドキュメントのみの変更の場合に限り、この手順を省略できます（省略したことを明記してください）。

IMPORTANT MUST ATTENTION マイクロサービス／イベント駆動型の場合は、タスクの対象範囲にあるプロデューサー、コンシューマー、サーガ、コントラクトを調査してください。各接点について、担当者・メッセージ・コンシューマー・リスク（NONE／ADDITIVE／BREAKING）を記録してください。コンシューマーの見落としは、気づかれないリグレッションにつながります。

IMPORTANT MUST ATTENTION データフロー全体を追跡し、クラッシュが発生した箇所ではなく、責任を持つ層で修正してください。?. を追加する前に、すべてのアクセス箇所を調査してください。 必ず注意 重要な思考と順序立てた思考を適用してください。すべての主張には適切な追跡可能な根拠が必要です（リポジトリ／コードに関する主張には file:line、調査、製品、コンテンツ、ドキュメントに関する主張にはソース URL または成果物のセクション）。確信度が 80％を超える場合に行動し、60％未満の場合は推奨しないでください。ハルシネーション対策：推測を事実として提示せず、不確実性は率直に認め、独立した情報源で相互検証し、自分の確信度にも懐疑的でいてください。

必ず注意 順序立てた思考を適用してください。複数ステップでは Thought N/M、REVISION／BRANCH／HYPOTHESIS のマーカーを使い、確信度をより近い値で示してください。$sequential-thinking スキルを参照してください。

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

• 必須 ファイルの言語、ディレクトリの意味、変更の性質からレビューのカテゴリを導き出し、カテゴリごとにサブタスクを作成してください。

• 必須 各カテゴリの確認事項は、file:line の根拠を用いて第一原理から導き出してください。固定のチェックリストは使わないでください。

• 必須 対象作業を始める前にタスク追跡を開始してください。一度に 1 つのタスクだけを移行してください。

• 必須 計画とレビューの所見を plans/reports/ に段階的に保存し、ディスクから統合してください。

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

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

• 必須 プロジェクト設定、ルートの指示ファイル、または必須の参照ドキュメントが欠落しているか古い場合は、通常のプロジェクト固有作業に入る前に $project-init、または対象を絞った下位レベルの手順を自動的に実行してください。

重要・必ず注意 デバッガーのトレースゲート：重大なバグ修正／調査／レビューでは、観測された最終出力から始め、reader → storage/projection → writer → consumer/job → producer/trigger の順に逆向きに追跡してください。すべての入力経路と仮説を列挙してから修正してください。トレース、仮説マトリクス、修正を担当するレイヤー、順方向の収束の証明がそろうまで、作業は禁止です。

• 必須 親ワークフローの行で、子フェーズの追跡を代替しないでください。入れ子になっている場合はフェーズを展開し、親と関連付けてください。

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

• 必須 作業前に有効な Goal Contract を特定してください（有効な計画の goal.md → plans/goals/{YYMMDD-HHmm}-{slug}/goal.md → 現在の依頼から作成）。編集前に、保存済みの成功基準を読んでください。

• 必須 実行後に反復の根拠を追記し、PASS と報告する前に Goal Satisfaction マトリクス（PASS／FAIL／BLOCKED）を提示してください。検証済みの FAIL がある場合はループし、進展が繰り返し得られない場合やブロッカーがある場合はエスカレーションしてください。Goal ファイルにシークレットを保存しないでください。

• 必須 変更セットが大きい場合は、サイズ上限（ファイル数 ≤8 または差分行数 ≤2000）ごとにバッチ分けし、各バッチに並行サブエージェントを 1 つ割り当ててください。多数のファイルを 1 つずつレビューしないでください。

• 必須 カテゴリが 6 を超える、またはファイル数が 40 を超える場合は、階層型の統合レイヤーを追加してください。各懸念事項の統合担当者は、懸念事項間の相互作用候補を提示し、オーケストレーターは結論を出す前に懸念事項横断の確認を実行してください。

• 必須 所見を結果の重大度に応じて Critical／High／Medium／Low に分類してください。Critical／High は、修正されるか担当者が受け入れるまで PASS をブロックします。

• 必須 スコア形式のスキル（sre 0-2、perf の二軸）は、並行する重大度用語を使わず、同じ 4 段階に対応付けてください。

Prompt-Enhance Closing Anchors

重要：必ず注意してください このスキルでは、明示的にユーザーの承認を得ない限り、宣言されたステップの順序に従ってください。ステップを決してスキップ、並べ替え、統合しないでください。 重要：必ず注意してください 各ステップ／サブスキルの呼び出しでは、実行前に in_progress を設定し、実行後に completed を設定してください。 重要：必ず注意してください スキップしたステップには必ず明確な理由を記載してください。完了したステップには必ず簡潔な証拠を記載してください。 重要：必ず注意してください Task ツールを利用できない場合は、ステータスを同期した同等のステップごとの計画トラッカーを維持してください。

• 必須：必ず注意してください。トレードオフに関する3つの質問を常に確認してください — レビュー対象と、行うすべての推奨事項について、次の質問を確認してください。（1）トレードオフはありますか？ 何を犠牲にするのかを明示してください（変更コスト・複雑さ・パフォーマンス・結合度・可逆性・移行・運用負荷・影響範囲・セキュリティ・テスト容易性・提供までの時間・UX）。「なし」／「純粋なメリット」では分析が未完了です。確認した観点を明記してください。（2）その価値はありますか？ 利得（指標を含む）とコスト、誰が負担するか、いつ発生するかを比較し、価値あり／価値なし／不明を示してください。価値なしの場合は、取り下げるか、別の案に置き換えてください。（3）ユーザーへの確認が必要なほど重大ですか？ 取り消せない変更／後戻りできない決定、別のチーム／運用担当者／メンテナー／ユーザーへのコスト転嫁、ある品質特性と別の品質特性とのトレードオフ、階層／サービス／イベント／ライブラリの境界をまたぐ変更、認証／金銭／データ整合性／破壊的変更／リスクが高または中の経路、判定が不明の場合は、停止して、判定前にユーザーへ直接確認してください。
• 必須 ユーザーの確認を得ていない重大なトレードオフは、決して PASS にできません。重大度が低い注記に埋もれさせず、黙って判断せず、提供や収束の圧力を後戻りできない決定の根拠にしてはなりません。 — 理由：取り消せない決定について、十分な説明を受けたうえで判断するのは、レビュー担当者ではなくユーザーです。
• 必須 — ユーザーに確認できない状況では、黙って進めず、必ず引き継いでください。 ユーザーに直接確認できるのはメインの対話エージェントだけです。サブエージェントはユーザーに確認できず、ターミナル／判定のみのモードでは設計上、質問を行いません。その場合、義務が免除されるのではなく、対応が引き継がれます。トレードオフを明示し、重大性を判断し、confirmed? = NO — cannot ask from this context を記録してください。また、未確認の重大なトレードオフを返却する判定／要約に記載し、呼び出し元がエスカレーションできるようにしてください（ディスク上のレポートにだけ記載しても引き継ぎにはなりません）。無条件の PASS を決して出してはなりません。これは、ユーザーに本当に連絡できない場合（起動されたサブエージェント、ターミナルの検証モード、ヘッドレス実行）にのみ適用されます。ユーザーに確認できる場合は、必ず確認してください。

並列サブエージェントのディスパッチ — タスクの分解ができた時点で、実行する前に並列化を計画します。明らかに独立したタスクを順次実行すると、実時間を無駄にします。対象は、ワークフローのステップ、計画、バッチ更新、調査、リサーチ、スキャン、レビュー、ドキュメントの同期など、すべての複数ステップの作業です。計画の実行はメタデータによるゲート制御とし、デフォルトで並列化することは絶対にありません — ファンアウトは、計画で宣言された内容（PAR／SEQ タグとフェーズごとの書き込み対象）のみに従います。タグのない計画は順次実行します。理由：導出した書き込み対象では、連鎖的な書き込みや生成される書き込みを検出できないためです。

1. すべてのタスクに PAR または SEQ のタグを付けます。 PAR にできるのは、入力に保留中のすべてのタスクの出力が含まれず、かつ書き込み対象が他のすべての PAR タスクと重複しない場合です。それ以外は SEQ とし、その理由となる依存関係を MUST ATTENTION に明記します。
2. PAR タスクをウェーブにまとめます。 同じウェーブのメンバー間に依存関係があってはなりません。同じファイルに書き込むタスクを同じウェーブに含めることは絶対にありません。読み取り専用の作業（検索、調査、レビュー、リサーチ）は自由に並列化できます。
3. ディスパッチ前に宣言します： Parallel plan: wave 1 = [...] · wave 2 = [...] · SEQ = [...] (reason)。
4. 各ウェーブは1つのメッセージで起動します — すべての spawn_agent 呼び出しを1つの応答にまとめ、ターンごとに小分けしてはなりません。各タスクを適切な専門家に割り当てます（.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 に理由を明記して MUST ATTENTION を満たす · ウェーブを宣言し、書き込み対象が重複しないことを確認する · 各ウェーブを1つのメッセージで起動する · 次のウェーブに進む前にバリアを守る。

• 必須 タスクの計画後、各タスクに PAR／SEQ のタグを付け、すべての PAR ウェーブを1つのメッセージで並列サブエージェントとして起動します。ワークフロー、バッチ更新、調査、リサーチ、レビューはデフォルトで並列化します。計画の実行では、計画で宣言された内容に基づく場合にのみファンアウトします。
• 必須 ウェーブごとに書き込み対象を重複させない · 次のウェーブに進む前に全員の返答を待つ · 専門家に割り当てる · サブエージェント自身のエージェント定義で許可されていない限り、サブエージェントがさらにファンアウトすることは絶対にありません。

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

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

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

最後の確認事項

重要な目標： 受け入れまたは引き継ぎの前に、レビュー済みのコードが正確で、変更しやすく、規約に準拠し、検証によって裏付けられていることを確認します。

必ず注意 プロトコルの適用（このスキルに含まれる SYNC／共有ブロックの簡潔な要約。各行は上記の正式な本文を示します。適用されるのは本文です）： 要約だけに基づいて行動してはいけません。記載された条件が発生した場合は、必ず該当する正式なブロックを読んでください。

• 体系的なバッチ処理： 大規模な変更セットをサイズ上限付きの並列バッチに分割し、削減します。

• 終点から始めるデバッガートレース： 修正前に、観測された最終状態から逆方向にトレースします。

• グラフを活用した調査： まず主要なファイルに対してグラフコマンドを実行します。

• カテゴリレビューの思考： 第一原理からカテゴリごとの懸念事項を導き出します。

• サブエージェントの返却契約： サブエージェントは要約のみを返し、レポートはディスク上に保存します。

• ネストされたタスクの作成： ワークフローの行の下に子フェーズを展開します。

• プロジェクト参照ドキュメントのガイド： 対象作業の前にプロジェクトのドキュメントを読みます。

• タスク追跡と外部レポート： タスクを初期化し、調査結果を段階的に保存します。

• 批判的思考のマインドセット： 主張ごとに追跡可能な証拠を示し、決して推測しません。

• 逐次思考プロトコル： 確信度を添えた複数ステップの Thought N/M で進めます。

• 証拠に基づく推論： file:line を引用し、確信度が80%を超えた場合に対応します。

• デザインパターンの品質： OOP、最下層、SOLID を用いて DRY を実現します。

• 複雑さの予防： 1つのビジネス上の変更につき、コード変更は1つにします。

• 二重ラウンドトリップレビュー： レビュー → 検証 → 修正 → 再レビューを問題がなくなるまで繰り返します。

• 新鮮なコンテキストでのレビュー： 修正後、記憶が新しいサブエージェントを使って再レビューします。

• レビュープロトコルの埋め込み： 11個すべてのプロトコル本文をそのまま埋め込みます。

• 正当化の防止： 手順を省略するための言い逃れを退け、証拠を示します。

• ロジックと意図のレビュー： 変更されたコードが明示された目的に合致していることを確認します。

• バグ検出： レビューのたびに、null、境界、エラー、リソースを確認します。

• テスト仕様の検証： 変更されたパスをすべてテストに対応付けます。

• 修正レイヤーの説明責任： クラッシュ発生箇所ではなく、責任を持つレイヤーで修正します。

• ソースとテストの乖離確認： ソースを変更したら、影響を受けるテストを調整します。

• AI の誤りの防止： 生成された内容を証拠と照合し、下流の参照を追跡し、影響を受ける出力をすべて検証し、コンテキスト喪失後に読み直し、曖昧さを明らかにします。

• 重大度の基準： 影響に基づいて分類し、Critical／High の場合は PASS を阻止します。

• 必須 ネストされたタスクの展開契約 — ワークフロー内で呼び出された場合も、タスク追跡を使って内部フェーズを [N.M] $skill-name — phase の接頭辞付きで展開し、TaskUpdate(parentTaskId, addBlockedBy: [childIds]) で関連付けます。ワークフローの行はコンテナであり、代わりにはなりません。

• 必須 作業を始める前に、タスク追跡を使って作業を小さな TODO タスクに分割します。

• 必須 ユーザーに直接質問して意思決定を確認します。自動的に決めてはいけません。

• 必須 作業品質を検証する最終レビュータスクを追加します。

• 必須・要注意 レビューの前に、プロジェクト固有の参照ドキュメント（コーディング規約、アーキテクチャ、テスト規約）を検索します。

• 必須・要注意 フェーズ0：まず変更の種類を検出します。認証／パフォーマンス関連のファイルは、一般レビューの前に専門サブエージェントへ振り分けます。

• 必須・要注意 このレビューの完了後に $why-review を実行し、設計の根拠、検討した代替案、リスク評価を検証します。

• 並列サブエージェントのディスパッチ： タスクに PAR／SEQ のタグを付け、PAR タスクを書き込み範囲が重複しない単位でウェーブにまとめ、各ウェーブを1つのメッセージで起動し、次へ進む前にバリアを設けます。

[TASK-PLANNING] 着手する前に、タスクの範囲を分析し、タスク追跡を使って小さな TODO タスクとサブタスクに体系的に分割します。

---

締めくくりのリマインダー — 変更のしやすさが成功の指標です。 すべての指摘、 テスト、リファクタリング、抽象化について、次の1つの問いに答えてください。これによって 次の変更のコストは下がるのか、上がるのか？ 将来の変更コストを下げないものは 退けてください。結合、隠れた状態、重複した知識、不明瞭な意図こそが真の敵です。 それぞれを名前を挙げて指摘してください。 正当化の防止： | 回避策 | 反論 | | -------------------------------- | ----------------------------------------------------------------------------- | | 「目的は明らか」 | それでも冒頭で明示してください。初頭効果／新近効果により、長いプロンプトでも成果が意識され続けます。 | | 「既存のリマインダーで十分」 | クロージングリマインダーで Goal を繰り返してください。最後にアンカーを置くことで、逸脱を防ぎます。 | | 「プロンプトの編集に証拠は不要」 | 変更したファイルの証拠を引用し、古いプロトコル文が残っていないことを確認してください。 |

フックレスプロンプトプロトコルミラー（自動同期）

ソース：.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/ に関する作業では、ドキュメントインデックスに記載されたローカルの仕様文書を参照してください。仕様／テスト／コードの同期が必要な場合は、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、ビジネスエンティティ、機能ルール）を一切参照してはいけません。漏れがコンパイルされ、実行されると、再利用可能なはずの層が一つの利用側と結合していても、レビューで気づかれずに通過してしまいます。共有型からドメイン情報を排除し、サブクラス化／コンポジションを通じて、ドメインフィールド／ロジックを利用側へ移してください。理由：一つの利用側のドメインに結合した層は、もはや再利用可能ではありません。