plan

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

簡単な概要

目標： コードベースを調査し、ユーザーと協力して検証済みの実装可能な段階的計画を作成します。各フェーズはすぐに開始できるように（正確なファイルパス、未決事項ゼロ、対応する TC ID を明示）、コーディングを手戻りなく、将来の変更コストを最小限に抑えて進められるようにします。

概要：

• 計画のみ — コードの実装や実行は絶対に行わないでください。plan.md、フェーズごとの phase-XX ファイル、Goal Contract の goal.md を作成し、その後引き継ぎます。
• メインパイプライン（AI が忘れがちな手順）： 有効な計画／提案された計画を事前確認 → Goal Contract（goal.md）を初期設定 → 1 回のリサーチウェーブ（researcher と scout のサブエージェントを同時に起動し、統合前にバリアを設ける） → コードベースとプロジェクト参照資料を分析（ドキュメントがない場合は scout） → planner サブエージェントが plan.md と phase-XX ファイルを作成（代替案、根拠、UI レイアウト、テスト仕様） → 並列化の確認（すべてのフェーズに PAR／SEQ と書き込み対象を付与し、## Execution Waves を記述） → 計画の粒度に関する事後セルフチェック → 必須の最終タスク。
• 計画の出力自体に並列化のメタデータを含めます — すべてのフェーズに、所有する書き込み対象を添えて PAR／SEQ を付与し、すべての SEQ にはそれを必要とする依存関係を記載します（Plan Parallelism Metadata を参照）。これを省くのは、このスキルの欠陥です。$plan-execute は計画に記載された内容に基づいてのみ並列処理を実行します。
• --mode={ci|cro} の振り分け： ci は GitHub Actions の実行結果／ログから修正を計画します（references/mode-ci.md を読み込みます）。cro はコンバージョン率最適化を計画します（25 項目のフレームワーク、references/mode-cro.md）。デフォルト（フラグなし）は標準フローです。モードで追加されるのは参照資料だけです。同じエンジン、同じ $plan-review ゲート、同じ planner エージェントを使用します。
• デフォルトモードは HARD（並列サブエージェント、プロジェクト参照ドキュメント、3 ラウンドを上限とする $plan-review の収束ループ）です。ファストモードは、些細なタスクの条件をすべて満たす場合に限って使用します。すべてのフェーズで 5 項目の粒度チェック（「今すぐコーディングを始められますか？」）に合格し、TC ID を含む ## Test Specifications を設け、ボトムアップで見積もります（工数日数はフェーズの時間数から算出し、SP は派生値とします）。
• 必須の最終タスクとゲート： フェーズごとにテスト仕様を記述 → $plan-validate → $plan-review（収束ループ、最大 3 ラウンド） → $why-review（単独実行） → 確定したフェーズに基づいて再見積もり。承認前に New Tech/Lib ゲートを通過すること。Domain Entity Gate（計画がエンティティ／VO／集約に触れる場合は必須） — SYNC:domain-entity-change-gate を適用し、実装に判断を先送りせず、計画段階で分類、不変条件の所有者、集約境界、並行処理、構築、イベント、テスト義務を決定します（それぞれの所有ファイルを明記します）。次のステップに進む前に、ユーザーに直接確認を求めてください。

ワークフロー：

1. 事前確認 — 有効な計画／提案された計画を検出するか、新しいディレクトリを作成します
2. リサーチウェーブ — 独立した調査スレッドをすべて 1 つのメッセージで起動します（researcher と scout のサブエージェント、各自のツール呼び出しは最大 5 回）。その後、統合前にバリアを設けます
3. コードベース分析 — プロジェクト参照ドキュメント（patterns-reference、project-structure、architecture、adr）を検索します。見つからない場合は scout を起動します
4. 計画の作成 — Planner サブエージェントが、必要なセクションをすべて含む plan.md と phase-XX ファイルを作成します
5. 並列化の確認 — すべてのフェーズに書き込み対象を添えて PAR／SEQ を付与し、plan.md に ## Execution Waves を記載します
6. 事後検証 — 必要に応じてユーザーに質問し、$plan-validate を通じて判断内容を確認します

主要ルール：

• 計画のみ：コード変更を実装または実行しないでください
• 計画の作成後は、必ず $plan-review を実行します
• 次のステップに進む前に、必ずユーザーに確認を求めます
• 必須・重要・要注意 計画に新しい技術／ライブラリが含まれるかを検出し、検証タスクを作成します（以下の New Tech/Lib Gate を参照）
• 必須・重要・要注意 計画がエンティティ、値オブジェクト、または集約に触れる場合は、以下の Domain Entity Gate を実行します。エンティティ関連のタスクに着手する前に、パラダイムとサブドメインとの適合性を示し、該当するすべての判断項目について、所有ファイルを明記して回答します。「実装時に調査する」は回答になりません。該当しない場合は No domain-entity surface — gate N/A と記録します

第一原則 — 変更しやすさ

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

コード、リファクタリング、テスト、抽象化を評価するときは、次のように問いかけてください。 これは次の変更をより低コストにしますか、それとも高コストにしますか？

• 変更コストを高める「ベストプラクティス」は却下します（時期尚早な抽象化、 投機的な汎用化、漏れのある間接化、効果のない形式主義など）。
• 調査結果では、実際の敵を明示します。結合、隠れた状態、重複した 知識、不明確な意図、早すぎる段階で公開される不可逆な決定。
• 変更しにくい洗練された設計より、変更しやすいシンプルな設計を優先します。

以下のルール、パターン、チェックリストを適用する前に、この視点を当てはめてください。 後続のルールによって変更コストが高まる場合は、この原則を優先します。

---

デフォルトのモードポリシー

デフォルトのモードは HARD（完全な厳密さ）です。 以下のすべてのセクション――並列リサーチャーサブエージェント、完全な $plan-review 収束ループ（最大3ラウンド）、ベースクラスの grep、マイクロサービス／イベント駆動型の分析、ユーザーによる必須承認――がデフォルトで適用されます。

次の条件をすべて満たす場合に限り、ファストモードへのオプトアウトが可能です（本当に単純なタスクであること）。

• 単一ファイルの編集で、変更行数が30行以下
• 設計上の選択肢がない（妥当な方法が1つだけ）
• サービス間への影響、コントラクトの変更、新しい依存関係がない
• 新しいパターンを導入しない――既存のコードベースのパターンに従う
• ユーザーが変更を迅速に行うよう明示的に依頼している

いずれかの条件を満たさない場合は、以下の完全なプロトコルを使用します。 判断に迷った場合は、デフォルトの HARD を選びます。重要なタスクで厳密さを省くと、厳密さによって削減できる作業量以上に手戻りが増えるためです。

ファストモードで省略するもの（これらに限る）： 並列リサーチャーサブエージェント（代わりに直接 grep を実行）、$plan-review の再レビュー・ループ（単一ラウンドとし、調査結果が残っていても新たな再レビューは行わない）、$plan-validate のインタビュー（インラインでの確認のみ）、新技術／ライブラリゲート（本当に新しい依存関係がない場合に限る）。

新技術／ライブラリゲート（すべての計画で必須）

計画の作成後、プロジェクトに存在しない新しい技術／パッケージ／ライブラリがないか検出することが必須・重要・要注意です。見つかった場合は、ライブラリごとにタスクを追跡 → WebSearch で上位3つの代替候補を調査 → 比較（適合性、サイズ、コミュニティ、学習曲線、ライセンス） → 確信度（％）を添えて推奨 → ユーザーに直接確認を求めます。計画で既存の依存関係のみを使用する場合は省略できます。

ドメインエンティティゲート（エンティティ、VO、または集約に触れる計画では必須）

SYNC:domain-entity-change-gate（以下にインライン化）を適用してください。これは $plan-review と $changes-review が参照するものと同じプロトコルであり、A～P のチェックリストは $domain-entities-review が管理します。— 理由：集約境界、不変条件の責任、または並行性を「実装中に見つける」計画では、設計レビューで却下される設計がリリースされ、手戻りのコストが二重にかかります。

発動条件：ドメインエンティティ／値オブジェクト／集約ルート、そのフィールド、不変条件、関係、または状態遷移を追加・変更する場合、集約境界、リポジトリ、または集約をまたぐ参照を追加・変更する場合、ドメインイベントを追加する場合、または並行性／再構成に関する懸念がある場合です。それ以外の場合は No domain-entity surface — gate N/A と記録してください。

計画では、該当する各項目について、決定内容とそれを担うファイルを必ず明記してください。未回答の項目がある計画は実行できません。

1. 分類 — エンティティ、値オブジェクト、集約ルートのいずれか（交換テストを適用）。
2. 不変条件の責任 — エンティティが強制するルールと、境界が検証するルール。失敗の通知方法（例外をスローするか Result を使うか）は、プロジェクトの規約に準拠させます。
3. 集約境界と並行性 — 何を同一トランザクションで扱い、その理由は何か。集約をまたぐ参照には ID を使います。並行性トークンはルートに置きます。集合に対する不変条件には、強制方法を指定します。
4. 構築と再構成 — 作成と読み込みの経路を分けます。読み込み時にイベントを発生させてはいけません。
5. イベント — 何を発生させるか、いつディスパッチするか（コミット後／outbox）、ドメイン契約と統合契約のどちらか。
6. テスト要件 — 各不変条件について、プロパティ TC と境界の反例ケースを計画タスクに含めます。暗黙のままにしてはいけません。

エンティティ関連のタスクを計画する前に、パラダイム（OO-mutable／type-driven-immutable／event-sourced）とサブドメインへの適合性（core／supporting／generic／CRUD）を必ず明示してください。CRUD サブドメインにリッチドメインモデルを計画してはいけません。また、イミュータブルモデルやイベントソーシングモデルに対して、セッターや可変性に関するタスクを計画してはいけません。

---

グリーンフィールドモード

自動検出： 既存のコードベースが見つかりませんでした（ソースディレクトリ、マニフェストファイル、内容が入力された project-config.json が見つかりません）→ スキルはグリーンフィールドモードに自動で切り替わります。計画用の成果物（docs/、plans/、.claude/）は対象外です。リポジトリには、実際のコードが含まれるディレクトリが必要です。

グリーンフィールドが検出された場合：

1. コードベース分析フェーズ（コードを grep する researcher サブエージェント）をスキップします
2. 代わりに実施： WebSearch + WebFetch による市場調査とビジネス評価
3. アーキテクチャの決定を solution-architect エージェントに委任します
4. 出力：グリーンフィールド固有のフェーズ（ドメインモデル、技術スタック、プロジェクト構成）を含む plans/{id}/plan.md
5. プロジェクトの参照ドキュメントを読む作業はスキップします（グリーンフィールドには存在しません）
6. 技術動向、ベストプラクティス、フレームワークの比較など、幅広いウェブ調査を有効にします
7. すべての意思決定ポイントで、2～4 個の選択肢と信頼度（％）を提示し、ユーザーに直接確認する必要があります
8. [CRITICAL] ビジネス優先プロトコル： 技術スタックの決定は、ビジネス分析をすべて終えた後に行います。ユーザーに最初から技術スタックを選ばせてはいけません。まずビジネス評価を完了し → 技術要件を導き出し → 現在の市場の選択肢を調査し → 比較レポートを作成して → ユーザーに提示します。技術スタックの調査方法の詳細については、solution-architect エージェントを参照してください。

• 調査レポートは 150 行以下、plan.md は 80 行以下にします
• 外部メモリ： すべての調査・分析内容を .ai/workspace/analysis/{task-name}.analysis.md に書き込みます。計画を生成する前に、分析ファイル全体を読み直します。

計画方法論エンジンを実行します。各フェーズで該当する references/engine-*.md を読み込みます（独自のスキップ条件に該当するフェーズはスキップします）。

• references/engine-research.md — 調査と分析（researcher のレポートが提供されている場合はスキップ）
• references/engine-figma.md — デザインコンテキストの抽出（Figma の URL がない場合、またはバックエンドのみの場合はスキップ）
• references/engine-codebase-understanding.md — コードベースの理解（scout のレポートが提供されている場合はスキップ）
• references/engine-solution-design.md — ソリューション設計（トレードオフ、セキュリティ、パフォーマンス、エッジケース、アーキテクチャ）
• references/engine-plan-organization.md — 計画の作成、構成、出力基準

モードの振り分け（--mode={ci|cro}）

デフォルト（--mode フラグなし）：このセクションは無視し、以下の標準的な計画フローをバイト単位で変更せずに実行します。 --mode は、同じエンジン、同じ必須の $plan-review ゲート、同じ planner エージェントに加えて、ドメイン固有の参照ファイルの読み込みと入力規約を追加するだけです。エンジンを置き換えることはありません。

フラグ	位置引数 $ARGUMENTS	計画前に読み込むもの	計画のフロントマターの上書き
--mode=ci	GitHub Actions の実行／ログ URL	references/mode-ci.md（CI 失敗の種類：ビルド／テスト／環境／Docker／依存関係）	priority: P1、tags: [ci, bugfix]
--mode=cro	最適化するコンテンツ／課題（任意でスクリーンショット／URL）	references/mode-cro.md（25 項目の CRO フレームワーク + マルチモーダル入力）	priority: P2、tags: [cro, conversion]

--mode が指定されている場合：(1) 対応する references/mode-*.md を読み込みます。(2) $ARGUMENTS にその入力規約とドメインの重点項目を適用します。(3) 以下の標準的な計画ワークフローを実行します。同じ planner サブエージェント、同じフェーズファイル構成、同じ必須の $plan-review を使用します。モードが追加するのは参照情報だけです。

スキャフォールディング優先プロトコル（条件付き）

有効化の条件（すべて満たす必要があります）：

1. アクティブなワークフローが workflow-greenfield-init または workflow-big-feature であること
2. AI は次のパターンを使って、既存の基盤となる抽象化を必ず自ら調査すること：
   • 抽象／基底クラス：abstract class.*Base|Base[A-Z]\w+|Abstract[A-Z]\w+
   • ジェネリックインターフェース：interface I\w+<|IGeneric|IBase
   • インフラストラクチャの抽象化：IRepository|IUnitOfWork|IService|IHandler
   • ユーティリティ／拡張レイヤー：Extensions|Helpers|Utils|Common（ディレクトリまたはクラス）
   • フロントエンドの基盤：base.*component|base.*service|base.*store|abstract.*component（フロントエンドがある場合）
   • DI／IoC 登録：プロジェクトのフレームワークに適した DI 登録パターンを検索する
3. 既存のスキャフォールディングが見つかった場合 → スキップします。 次の内容を記録します："Existing scaffolding detected at {file:line}. Skipping Phase 1 scaffolding."
4. 基盤となる抽象化が見つからない場合 → スキャフォールディングフェーズに進みます。

有効化された場合：

計画のフェーズ 1 は必ずアーキテクチャスキャフォールディングとし、すべての基底抽象クラス、ジェネリックインターフェース、インフラストラクチャの抽象化、OOP／SOLID 原則に基づく DI 登録を含めます。機能ストーリーより前に実施します。AI は、技術スタックに必要な基底クラスを自ら調査します。インフラストラクチャはすべてインターフェースの背後に配置し、少なくとも 1 つの具象実装を用意します（依存性逆転）。フェーズ 1 の成果物には、$scaffold が出力するゴールデンパスのサンプル一式も必ず含めます。該当する各パターンにつき、コンパイルチェック済みの *.example.* を 1 つ用意します（バックエンド：command・query・handler・不変条件を持つ entity・value-object・repository・domain event と event handler。UI がある場合のフロントエンド：form・list・store・API service。テスト：正常系と失敗系のパスを含む統合テストを 1 つ）。これらは、スキャフォールディングした基底抽象化を使用し、本番ビルドから除外された独立した examples/ ツリーに配置します。これにより、スキャフォールディング後の $architecture-review-full ゲートで、機能開発に着手する前に実際に評価できるコードが用意されます。

スキップした場合： 計画は通常どおり進み、機能ストーリーは既存の基底クラスを基盤に構築されます。

計画のみ — 共同作業が必要

手動の計画モード切り替えツールは使用しないでください。すでに計画ワークフローにあります。 コード変更の実装や実行は行わないでください。 ユーザーと共同作業してください。判断が必要な質問をし、推奨案を添えて選択肢を提示します。 計画の作成後は、必ず $plan-review を実行して計画を検証してください。 次のステップに進む前に、必ずユーザーに計画の確認を求めてください。

あなたのミッション

$ARGUMENTS

作成前チェック（アクティブな計画と提案された計画）

注入されたコンテキストの ## Plan Context セクションを確認します。

• 「Plan:」にパスが表示されている場合：アクティブな計画が存在します。ユーザーに「これを続けますか？ [Y/n]」と尋ねます。
• 「Suggested:」にパスが表示されている場合：ブランチに一致するヒントのみです。これを有効化するか、新しく作成するかをユーザーに尋ねます。
• 「Plan: none」の場合：## Naming セクションの命名規則に従って新しい計画を作成します。

ワークフロー

1. 新規作成の場合：## Naming セクションの Plan dir: を使用してディレクトリを作成し、node .claude/scripts/set-active-plan.cjs {plan-dir} を実行します。再利用する場合：Plan Context にあるアクティブなプランのパスを使用します。すべてのサブエージェントにディレクトリパスを渡します。
2. Goal Contract の初期設定（調査とフェーズの記述より前に実施）： SYNC:goal-contract-satisfaction-loop に従ってアクティブな目標を確定します。.claude/templates/goal-contract-template.md から {plan-dir}/goal.md を作成または更新し、元の依頼、目的、成功基準、制約、必要な証拠を記録します。各フェーズの成功基準は、保存済みの目標基準に対応させます。シークレットは伏せてください。
3. references/engine-plan-organization.md の「Plan Creation & Organization」ルールを厳守します。
4. プロジェクト参照資料の事前確認 — ディスパッチ前に実施。 必要なプロジェクト参照資料を特定して読み込みます。参照資料の不足や古さは、対象を限定した調査入力として記録します。作業者の開始後に初めて適用規約を見つけることがないようにします。
5. 調査ウェーブ — 1 つのメッセージ、1 つのバリア。 このタスクに必要な独立した調査スレッド（モジュールごとのコード調査、パターンの発見、依存関係のマッピング、先行事例やライブラリの検索など）を列挙し、それぞれに PAR または SEQ のタグを付けてから、ディスパッチ前に Parallel plan: wave 1 = [...] · SEQ = [...] (reason) を宣言します。調査は読み取り専用のため、別のスレッドの出力を使う場合（その出力名を明記します）を除き、スレッドは PAR です。ウェーブ全体を 1 つのメッセージで起動します。外部調査や先行事例の調査には researcher エージェント（最大 2 つ、各エージェントのツール呼び出しは最大 5 回）を使用します。コードベースの調査には、読み取り範囲が重複しないよう、モジュールまたは領域ごとに scout エージェントを使用します。各エージェントには、{plan-dir}/research/ または {plan-dir}/scout/ 配下に個別のレポートパスを割り当て、同じファイルに複数のエージェントが書き込まないようにします。
6. 事前確認で参照資料と照らし合わせてコードベースを分析します。必要な参照資料がない場合、または 3 日を超えて古い場合に限り： 不足している証拠を集めるため、対象を限定した $scout <instructions> メンバーを調査ウェーブに含めます。計画にない追加のラウンドトリップは実施しません。
7. バリアを越えてから統合します。 ウェーブのすべてのメンバーが戻るまで次に進みません（スキップされたスレッドも戻ったものとして扱います）。レポートの内容は記憶ではなくファイルから読み取り、相反する調査結果を突き合わせ、未解決のギャップを記録します。第 2 ウェーブを実施するのは、第 1 ウェーブでギャップが判明した場合に限ります。
8. メインエージェントが調査／scout レポートのファイルパスを集め、実装計画を作成するよう指示して planner サブエージェントに渡します。
9. 並列化の確認（引き継ぎ前に必須）。 各フェーズの Mode、Wave、write set、SEQ dependency を検証してから、## Execution Waves 行を記述します。詳細は Plan Parallelism Metadata を参照してください。これにより $plan-execute で並列実行できます。タグのないプランは厳密に逐次実行されます。
10. メインエージェントが planner サブエージェントから実装計画を受け取り、ユーザーにレビューを依頼します。

プラン作成後の検証（任意）

プラン作成後、実装前に意思決定を確認するための検証インタビューを提案します。

## Plan Context → Validation: mode=X, questions=MIN-MAX を確認します：

モード	動作
prompt	ユーザーに「短いインタビューでこのプランを検証しますか？」と尋ねます → はい（推奨）／いいえ
auto	$plan-validate {plan-path} を自動的に実行します
off	検証ステップを完全にスキップします

モードが prompt の場合： 上記の選択肢を使って、ユーザーに直接尋ねるツールを使用します。 ユーザーが検証を選択した場合、またはモードが auto の場合： SlashCommand で $plan-validate {plan-path} を実行します。

出力要件

計画ディレクトリ構成（## Naming セクションの Plan dir: を使用）

{plan-dir}/
├── research/
│   ├── researcher-XX-report.md
│   └── ...
├── reports/
│   ├── XX-report.md
│   └── ...
├── scout/
│   ├── scout-XX-report.md
│   └── ...
├── plan.md
├── phase-XX-phase-name-here.md
└── ...

調査出力の要件

• 調査レポートは、すべてのトピックと引用を含め、簡潔な Markdown（150 行以下）にしてください。

計画ファイルの仕様

• すべての plan.md は、必ず YAML フロントマターで始めてください。

  ---
  title: '{Brief title}'
  description: '{One sentence for card preview}'
  status: pending
  priority: P2
  effort: { sum of phases, e.g., 4h }
  story_points: { sum of phase SPs, e.g., 8 }
  man_days_traditional: '{ total e.g., 6d (4d code + 2d test) }'
  man_days_ai: '{ total with AI e.g., 3d (2d code + 1d test) }'
  branch: { current git branch }
  tags: [relevant, tags]
  created: { YYYY-MM-DD }
  ---
  

• 概要は {plan-dir}/plan.md に保存してください（80 行未満）。各フェーズのステータス、進捗、モード（PAR／SEQ）、フェーズファイルへのリンクを記載し、フェーズ表の下に ## Execution Waves の行を追加してください。

• 各フェーズについて、{plan-dir}/phase-XX-phase-name-here.md を作成し、次のセクションを含めてください：Context links、Overview、Key Insights、Requirements、Alternatives Considered（長所と短所を含むアプローチを最低 2 つ）、Design Rationale（選択したアプローチの理由）、Architecture、UI Layout（下記参照）、Related code files、Parallel Execution（モード PAR／SEQ · Write set · SEQ の依存関係 — 下記参照）、Implementation Steps、Todo list、Success Criteria、Risk Assessment、Security Considerations、Next steps。

• UI Layout： フロントエンドに関わるフェーズでは、ASCII ワイヤーフレームを含めてください。コンポーネントをティア（common／domain-shared／page-app）で分類してください。バックエンドのみのフェーズでは、## UI Layout → N/A — Backend-only change. としてください。

計画の並列実行メタデータ（必須 — すべての計画出力に適用）

$plan-execute は、計画で宣言されたもののみを並列実行します。タグのない計画は強制的に順次実行されるため、このメタデータを省略すると、このスキルの不備であり、実行ツールの不備ではありません。

1. 各フェーズに PAR または SEQ をタグ付けする — plan.md のフェーズ表（Mode 列）と各フェーズファイルの ## Parallel Execution セクションに記載してください。PAR は、入力に未完了フェーズの出力が含まれず、書き込み対象が他のすべての PAR フェーズと重複しないことを意味します。

2. フェーズごとに書き込み対象を宣言する — フェーズが作成／変更／削除する正確なファイルパスを記載してください（計画から対象を列挙できる場合のみ glob を使用できます）。2 つの PAR フェーズの書き込み対象は重複してはなりません。重複する場合は、フェーズを統合するか、後のフェーズを SEQ に変更して共有ファイルを明記してください。

3. すべての SEQ で、順次実行を強制する依存関係を明記する — SEQ — needs phase-02's {migration | generated type | contract | file}。「順次実行のほうがよさそう」「順番どおりのほうが安全」、または依存関係が不明確なことは理由になりません。その場合は PAR に変更してください。

4. PAR フェーズをウェーブにまとめる — plan.md の ## Execution Waves 行に記載してください。 Execution waves: wave 1 = [phase-01, phase-03] · wave 2 = [phase-04] · SEQ = [phase-02 (needs phase-01 schema), phase-06 (approval gate)].

5. ゲートとレビューは SEQ の境界にする — ユーザー承認、レビュー、検証、またはマイグレーションのフェーズを、その対象となるフェーズと同じウェーブに含めないでください。対象フェーズのウェーブが完了した後に実行してください。

6. フェーズファイルのブロック形式（各フェーズファイルにそのまま転記してください）：

   ## Parallel Execution
   
   - Mode: PAR | SEQ
   - Write set: `src/a/x.ts`, `src/a/x.spec.ts`
   - Wave: 1
   - SEQ dependency: {name the phase + the exact artifact it produces — omit when Mode: PAR}
   

動作／同期の計画チェック

• 動作を変更する作業では、各フェーズに変更する動作、維持する変更しない動作、TC／テストによる証明、ドキュメント／仕様の同期作業を記載してください。
• AI が抽出した仕様／TC については、正式に承認されるまでは参照専用であることを計画に明記してください。
• .claude のスキル／フック／ワークフロー／同期ツールについては、生成されたミラーとの同期、または同期が不要であることを明示的に示す根拠を計画に含めてください。

重要：タスク計画に関する注意事項（必ず従ってください）

• タスク追跡を使い、作業を必ず多数の小さなToDoタスクに分割してください。
• 作業品質を検証し、修正や改善点を特定するための最終レビューToDoタスクを必ず追加してください。
• 必須の最終タスク： すべての計画ToDoの後に、必ず次の最終タスクを追加してください。
  1. タスク：「各フェーズのテスト仕様を作成」 — すべてのフェーズファイルに、TC-{FEATURE}-{NNN} IDを付けた ## Test Specifications を追加してください。機能ドキュメントがある場合は $spec [mode=tests] を使用し、TDDファーストモードでは Evidence: TBD としてください。
  2. タスク：「$plan-validate を実行」 — $plan-validate スキルでは、重要な質問を通じてユーザーに確認し、計画の前提を検証します。
  3. タスク：「$plan-review を実行」 — $plan-review スキルの収束ループ（レビュー → 指摘事項の検証 → 修正 → 新たに全体を再レビュー）は、最大3ラウンドであり、目標ではありません。 問題のないレビュー結果が出たら、ラウンド数にかかわらずループを終了してください（ラウンド1でも終了します）。ラウンド3の終了時にもCRITICAL／HIGH／MEDIUMの指摘が残っている場合は、黙ってPASSとせず、ユーザーに直接確認してください。SPは各ラウンドの厳密さを高めるものであり、最低ラウンド数を増やすものではありません。≤3の場合はチェックリスト＋コードによる証拠の追跡、4～8の場合はこれに敵対的シミュレーションを追加、>8の場合はすべてのラウンドでコードによる証拠の追跡を必須とします。
  4. タスク：「$why-review を実行（単独実行の場合のみ）」 — ワークフロー内でない場合は、$why-review で設計の根拠、検討した代替案、リスク評価を検証してください。ワークフローにすでに $why-review が含まれている場合は省略してください。
  5. タスク：「確定した計画に基づいて見積もりを再評価」 — 完了前の見積もりはスコープの推測に基づいていますが、フェーズが確定すると実際のコストが明らかになります。フェーズ／TC／判断事項を確定した後、（a）確定したフェーズファイルから bottom_up_hours = Σ phase_hours を再算出する、（b）SYNC:estimation-framework に従って likely_days、risk_margin_pct、min-max range を再計算する、（c）現在のフロントマターにある man_days_traditional／story_points と比較する。|delta| > 20% の場合はフロントマターを更新し、reestimate_delta_pct: <signed> と1行の reestimate_reason を追加してください。|delta| > 50% の場合は SHOULD-RESCOPE としてフラグを立て、実装に進む前にユーザーへ直接確認してください。

重要な注意事項

• 作業中にカタログから必要なスキルを有効化してください。
• 品質を損なわない範囲でトークンを効率的に使用してください。レポートでは、簡潔さを優先して文法を犠牲にしても構いません。
• 未解決の質問は、レポートの最後に列挙してください。

---

単独レビューゲート（ワークフロー外の場合のみ）

必須・重要：必ず従ってください： スキルがワークフロー外（単独の $plan）で呼び出された場合、生成する計画には $changes-review を最終フェーズ／タスクとして必ず含めてください。これにより、ワークフローによる適用がなくても、実装によるすべての変更がコミット前にレビューされます。

すでにワークフロー内（例：workflow-feature、workflow-bugfix）で実行中の場合は省略してください。ワークフローの手順で、適切なステップに $changes-review が含まれます。

次のステップ（単独実行の場合：必ずユーザーに直接確認してください。ワークフロー内の場合は省略してください。）

必須・重要：例外はありません。 このスキルの完了後、以下の選択肢を提示し、必ずユーザーに直接確認してください。タスクが「単純」または「明白」に見えても、省略しないでください。判断するのはユーザーです。

• 「完全なワークフローを続行（推奨）」 — 計画が作成された状態から、続行に最適なワークフローを検出します。レビュー、検証、実装、テストが省略されないようにします。
• 「$why-review」 — 実装前に設計の根拠を検証します（単独実行の場合のみ。ワークフローに含まれている場合は省略）。
• 「$plan-review」 — 実装前に計画を検証します。
• 「$plan-validate」 — ユーザーに確認して、計画の決定事項を確定します。
• 「$plan-execute」 — 確定した計画のコーディングとテストを開始します。計画検証後に推奨される実装手順です。
• 「スキップして手動で続行」 — ユーザーが判断します。

計画後の粒度セルフチェック（必須）

すべてのフェーズファイルを作成した後、再帰的な分解ループを実行します。

1. 各フェーズを5項目の基準で評価します（ファイルパス、計画を表す動詞がないこと、各ステップが30分以内、5ファイル以内、未決事項がないこと）。
2. 不合格のフェーズごとに、サブ計画へ分解するタスクを作成します（独自の $plan → $plan-review → $plan-validate → 修正のサイクルを実施）。
3. 新しいフェーズを再評価します。すべてのリーフフェーズが合格するまで繰り返します（最大深度：3）。
4. セルフチェック：「各フェーズについて、今すぐコーディングを始められますか？『調査が必要』なものがあれば、サブ計画に分解します。」

保全インベントリ（バグ修正では必須）

[IMPORTANT] 作業を始める前に、タスク管理を使ってすべての作業を小さなタスクに分割してください。各ファイルの読み込みタスクも含めます。長いファイルによるコンテキストの喪失を防ぎます。単純なタスクの場合は、スキップしてよいか必ずユーザーに確認してください。

• docs/project-reference/domain-entities-reference.md — ドメインエンティティのカタログ、関係性、サービス間の同期（タスクがビジネスエンティティ／モデルに関係する場合に読み込みます）
• docs/specs/ — モジュールごとのテスト仕様（既存の TC を読み込み、テスト戦略を計画に含めます）

各フェーズファイルは必ず以下を満たす必要があります：フェーズあたり5ファイル以内、作業時間3時間以内、明確な成功基準、テストケースとの対応付け。

エビデンスゲート： 必須・重要・絶対遵守 — 主張、調査結果、推奨事項にはすべて、file:line による根拠または信頼度（80％超）を示した追跡可能な証拠が必要です。信頼度が80％未満の場合は、最初に検証してください。

外部メモリ： 複雑または長時間にわたる作業（調査、分析、スキャン、レビュー）では、中間調査結果と最終結果を plans/reports/ 内のレポートファイルに書き込んでください。コンテキストの喪失を防ぎ、成果物としても役立ちます。

計画の粒度 — 実装に入る前に、すべてのフェーズが5項目のチェックに合格する必要があります。

1. 変更する正確なファイルパスを列挙する（「X を実装」のような一般的な記述ではなく）。
2. 計画を表す動詞（調査、確認、分析、判断、検討）を含めない。
3. 各ステップは30分以内、フェーズ全体は3時間以内。
4. フェーズあたり5ファイル以内。
5. アプローチに未決事項や TBD がない。

不合格のフェーズ → サブ計画を作成します。すべてのリーフフェーズが合格するまで繰り返します（最大深度：3）。 セルフチェック：「今すぐコーディングを始められますか？『検討』が必要なステップがあれば、サブ計画に分解します。」

保全インベントリ — バグ修正計画では必須です。計画のタイトルまたはフロントマターに含まれるトリガーキーワード：fix、bug、regression、broken、defect。実装手順を書く前に、作成者は必ずこの表を作成してください。

列： Invariant | file:line | Why (data consequence if broken) | Verification (TC-ID or grep)

作業をブロック： 3行以上であること · すべての File セルに file:line があること · すべての Verification セルに TC-ID または grep があること（「手動で確認」は不可）

ネストされたタスク展開の契約 — ワークフローステップを呼び出す場合、[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つの側面を扱い、前提や不確実性を明示します
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を超える → サブタスクに分割。

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

詳細: $sequential-thinking スキル（.claude/skills/sequential-thinking/SKILL.md）には、実例（API 設計、デバッグ、アーキテクチャ）、高度な手法（段階的なブラッシュアップ、仮説検証、収束）、メタ戦略（不確実性への対応、修正の連鎖）が記載されています。

まずコードを理解する — ハードゲート: 既存のコードを読まずに、コードの記述、計画、修正を行ってはいけません。

1. 類似パターンを3つ以上検索します（grep/glob）— file:line 形式で根拠を示します
2. 対象領域の既存ファイルを読み、構造、基底クラス、規約を理解します
3. .code-graph/graph.db が存在する場合は、python .claude/scripts/code_graph trace <file> --direction both --json を実行します
4. connections または callers_of で依存関係を把握し、対象に依存するものを確認します
5. 重要なタスク（ファイル数が3つ以上）の調査内容は .ai/workspace/analysis/ に記録します
6. 実装前に分析ファイルを読み直します。記憶だけを頼りに作業してはいけません。— 理由: 長いコンテキストではファイルから意識が離れていくため、ファイルが正確な情報源です
7. 既存のパターンが使える場合、新しいパターンを決して作りません。既存のパターンに厳密に合わせるか、逸脱する理由を記録します。— 理由: パターンの不統一はコードベースを断片化させ、後から読む人の作業を遅らせます

次の項目が完了するまで作業禁止: - [ ] 対象ファイルを読む - [ ] 3つ以上のパターンを grep する - [ ] グラフをトレースする（graph.db が存在する場合） - [ ] 根拠に基づいて前提を検証する サービス間チェック — マイクロサービス／イベント駆動型：調査、計画、仕様書、機能ドキュメントを完了とする前に必ず実施してください。下流のコンシューマーを見落とすと、気づかれないままリグレッションが発生します。

境界	検索語
イベントの生成元	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 の確認 · コントラクトのレビュー · 破壊的変更リスクへのフラグ付け 見積もりフレームワーク — まずボトムアップで見積もり、SP は DERIVED とします。3日以上になりそうな場合は最小値と最大値の範囲で出力します。スタックに依存しません。基準：開発経験3〜5年、1日あたり生産的な作業時間6時間。AI見積もりでは Claude Code とプロジェクトのコンテキストを前提とします。

手法：

1. 影響範囲の確認（下記）— コードとテストのコストに影響します
2. フェーズに分解 → フェーズごとの時間を算出 → bottom_up_hours = Σ phase_hours
3. likely_days = ceil(bottom_up_hours / 6) × productivity_factor
4. リスクマージン（基本値＋加算分）を合計 → max_days = likely_days × (1 + margin)
5. min_days = likely_days × 0.9
6. likely_days ≥3 の場合は範囲で出力します。<3 の場合は単一の値でも構いません（ただしマージンは記録します）
7. man_days_ai = 同じ範囲 × AI による高速化率
8. story_points は SP-Days を使って likely_days から DERIVED します。決して見積もりの基準にしません。乖離が50%を超える場合は、ボトムアップの見積もりを優先します

生産性係数： 足場となるコード＋コード生成＋AI フックが充実している場合は 0.8 · 成熟した標準的な場合は 1.0 · パターンが弱い場合は 1.2 · 新規開発の場合は 1.5

コスト要因のヒューリスティック（作業種別の行を選ぶ前に適用）：

• UI が支配的なのは CRUD／業務アプリの場合です — バックエンドの1.5〜3倍（状態、バリデーション、レスポンシブ対応、アクセシビリティ、仕上げ）
• バックエンドが支配的なのは次の場合のみです： 複数集約にまたがる不変条件、サービス間コントラクト、スキーマ移行、複雑なクエリ／パフォーマンス、新しいイベントフロー

再利用か新規作成か（レイヤーごとの最重要要因）：

UI の段階	コスト
既存画面でコンポーネントを再利用	0.1-0.3d
既存画面にコントロール／列を追加	0.3-0.8d
コンポーネントを組み合わせて新しい画面を作成	1-2d
独自レイアウト／状態／バリデーションの新画面	2-4d
新しい共有／共通コンポーネント（テーマ適用、テスト済み）	3-6d+

バックエンドの段階	コスト
新しい場所でクエリ／ハンドラーを再利用	0.1-0.3d
既存ハンドラー／エンティティの小規模な更新	0.3-0.8d
既存リポジトリ／モデルに新しいクエリを追加	0.5-1d
既存集約に新しいコマンド／ハンドラーを追加（拡張）	1-2d
新しい集約／エンティティ（リポジトリ、バリデーション、イベント）	2-4d
新しいサービス間コントラクトまたはスキーマ移行	各 2-4d
複数集約にまたがる不変条件／複雑なドメインルール	3-5d

ルール： UI＋バックエンド＋テストの各段階を合計し、生産性係数を適用します。再利用できる場合は段階を省略できます — その旨を明記します。

テスト範囲の要因（test_count を明示的に算出してください。「＋テスト」という曖昧な記載が失敗原因の第1位です）：

要因	件数
正常系のユーザージャーニー	ストーリー／AC の主要フローごとに1件
状態遷移	到達可能な遷移 × 許可されたアクター
複数エンティティの状態の組み合わせ	state(A) × state(B) — 到達可能な組み合わせのみ。直積ではありません
認可マトリクス	(所有者、非所有者、権限昇格済み、未認証) × 各変更操作
バリデーションルール	必須フィールド／境界値／形式／フィールド間チェックごとに1件
UI の状態（新しい画面／ダイアログごと）	正常、読み込み中、空、エラー、一部表示 — 存在する状態のみ
異常系／不変条件	違反可能な業務ルールごとに1件

テスト段階（従来方式、セットアップ＋アサーション＋不安定さを含む）	コスト
1-5 件、フィクスチャを再利用	0.3-0.5d
6-12 件、新しいフィクスチャ1つ	0.5-1d
13-25 件、複数エンティティのセットアップ	1-2d
26-50 件、または新しい状態遷移の網羅	2-3d
>50 件、または E2E ジャーニー全体	3-5d

テストの倍率： 新しいフィクスチャ／シード用ハーネス +0.5d · サービス間／バスのアサーションは各 +0.3d · UI E2E は ×1.5 · 新しいロールごとに +1-2 件

影響範囲（必須の事前確認 — コードとテストの両方に影響）：

1. 直接変更するファイル／コンポーネント — 件数
2. そのうち「複雑なもの」（>500 LOC、複数ハンドラー、中心的、頻繁に変更されるもの）— 件数
3. 下流の利用者（呼び出し元、イベント購読者、サービス間）— 一覧
4. 共有／共通コードへの変更（複数アプリに影響）— yes/no
5. 回帰テストの範囲 — 再テストが必要な領域

ルール： 複雑な箇所に触れる場合は risk_factors に追加します。下流の利用者ごとに回帰テストを +1-3 件追加します。影響範囲が5領域を超える、または複雑な箇所が2つを超える場合は、見積もり前に SPLIT を再検討します。

リスクマージン（最大値を決定）：

likely_days	基本マージン
<1d 軽微	+10%
1-2d 小規模な拡張	+20%
3-4d 実質的な機能	+35%
5-7d 大規模	+50%
8-10d 非常に大規模	+75%
>10d	+100% AND 分割を推奨

リスク要因の加算分（加算方式 — risk_factors に列挙）：

要因	+マージン
touches-complex-existing-feature（>500 LOC、複数ハンドラー、中心的）	+20%
cross-service-contract の変更	+25%
schema-migration-on-populated-data	+25%
new-tech-or-unfamiliar-pattern	+30%
regression-fan-out（再テストが必要な下流領域が3つ以上）	+20%
performance-or-latency-critical	+20%
concurrency-race-event-ordering	+25%
shared-common-code（複数の利用者／アプリ）	+25%
unclear-requirements-or-design	+30%

上限ルール： マージンの合計が100%を超える場合は、作業を停止して分割します（2倍を超える水増しは不誠実です）。likely_days ≥5 でマージンが15%未満の場合は、過小見積もりです。範囲を広げてください。

作業種別の上限（likely_days の厳格な上限）：

作業種別	最大 SP	最大 likely
単一フィールド／設定フラグ／スタイル修正	1	0.5d
既存モデルにプロパティを追加し、既存 UI にバインド	2	1d
拡張エンドポイント＋軽微な UI コントロール（ボタン／メニュー／列）、フィクスチャを再利用	3	2-3d
拡張エンドポイント＋新しい UI 表面、または複数レイヤーの拡張＋新しいドメインルール＋テストファイル2つ以上	5	3-5d
新しいモデル／集約、移行、モジュール間コントラクト、重いテスト（>1.5d）、または新しい UI＋無視できないバックエンド	8	5-7d
新しい UI 表面＋（新しい集約、移行、またはサービス間コントラクト）	13	分割を推奨
サービス間コントラクト＋移行の組み合わせ	13	分割を推奨
これを超える場合	21	分割必須

SP→日数（検証専用）： 1=0.5d/0.25d · 2=1d/0.35d · 3=2d/0.65d · 5=4d/1.0d · 8=6d/1.5d · 13=10d/2.0d（従来方式／AI の likely） AI による高速化： SP 1≈2倍 · 2-3≈3倍 · 5-8≈4倍 · 13以上≈5倍。AI コスト = (code_gen × 1.3) + (test_gen × 1.3)（レビューのオーバーヘッド30%）。

必須のフロントマター：

story_points: <n>
complexity: low | medium | high | critical
man_days_traditional: '<min>-<max>d' # likely が3日以上の場合は範囲、3日未満の場合は '<N>d'
man_days_ai: '<min>-<max>d'
risk_margin_pct: <n> # 基本値＋加算分
risk_factors: [touches-complex-existing-feature, regression-fan-out] # 加算要因の選択肢から指定。該当なしの場合は []
blast_radius:
    touched_areas: <n>
    complex_touched: <n>
    downstream_consumers: [list or count]
    shared_common_code: yes | no
estimate_scope_included: [code, integration-tests, frontend, i18n, docs]
estimate_scope_excluded: [unit-tests, e2e, perf, deployment, code-review-rounds]
estimate_reasoning: |
    以下を含む5〜7行：
    (a) UI の段階 — 適用した行
    (b) バックエンドの段階 — 適用した行
    (c) テスト範囲 — 要因ごとのケース内訳、ファイル数、フィクスチャ、段階の行
    (d) コスト要因 — 支配的な段階とその理由
    (e) 影響範囲 — 変更箇所、複雑な箇所、回帰テスト範囲
    (f) リスク要因 — マージンの要因となるものの一覧と、さらに大きく／小さくならない理由
    例：「UI：Form/Table/Dialog を組み合わせて新画面を作成（約1.5d）。バックエンド：既存集約に新しいコマンドを追加し、
    バリデーションとリポジトリを再利用（約1d）。テスト：遷移4件 × 2アクター＋バリデーション3件＋UI 状態2件 = 13件、
    新しいフィクスチャ1つ → 13-25 件の段階で約1.5d。要因：UI の組み合わせと新しい状態。影響範囲：4領域、複雑な箇所1つ。
    リスク：基本値35%＋複雑な箇所への変更20% = 55% → 最大3.9d → 範囲2.5-4d。」

妥当性のセルフチェック：

• likely_days ≥3d なのに単一の値になっている？ → 不採用。必ず範囲にする

• likely_days ≥5d なのにマージンが15%未満？ → 過小見積もりです。範囲を広げる

• マージンが100%を超えている？ → 停止して、バッファを増やすのではなく分割する

• 既存の複雑な機能に触れるのに、(c) に回帰テストの予算がない？ → 不採用

• 影響範囲が5領域を超える、または複雑な箇所が2つを超えるのに、分割の検討がない？ → 不採用

• 既存モデルと既存 UI への追加だけ？ → テストが1.5dを超えない限り SP は3を上限とする

• 新しい UI 表面（ページ／複雑なフォーム／ダッシュボード）がある？ → バックエンドが単一エンドポイントでも SP 5以上

• バックエンドにサービス間連携／移行／複数集約がある？ → UI に関係なく SP 8以上

• bottom_up_hours / 6 と SP-Days の乖離が50%を超えている？ → ボトムアップの見積もりを優先し、SP を下げる

• テストがない場合に SP が1段階以上下がる？ → テストが支配的な要因です。明記する

• 推論で UI とバックエンド、影響範囲、リスク要因に触れている？ → 不足があれば追加する 計画の品質 — すべての計画フェーズに、必ずテスト仕様を含めてください。

1. 各フェーズのファイルに、TC-{FEATURE}-{NNN} ID を付けた ## Test Specifications セクションを追加します
2. すべての機能要件を、1 件以上の TC に対応付けます（または根拠を明記して TBD とします）
3. TC ID は TC-{FEATURE}-{NNN} の形式にします。内容全体を埋め込まず、ID を参照します
4. 新しいワークフロー手順を開始する前に、現在のタスクリストを呼び出し、フェーズファイルを読み直します
5. コンテキストが圧縮された場合は、最初に現在のタスクリストを呼び出します。タスクを重複して作成してはいけません
6. 完了としてマークする前に、フェーズごとに TC の充足を検証します（エビデンスは file:line とし、TBD は不可）

モード： TDD 優先 → 既存の TC を Evidence: TBD として参照します。実装優先 → TBD を使用し、$spec [mode=tests] で後から補います。

反復的なフェーズの品質 — 計画前に複雑さを採点します。

複雑さの指標： 変更ファイル数が 5 を超える場合は +2、サービスをまたぐ場合は +3、新しいパターンの場合は +2、DB マイグレーションの場合は +2 スコアが 6 以上の場合 → 必ずフェーズに分解します。各フェーズの条件：

• 変更ファイル数は 5 以下
• 作業時間は 3 時間以下
• 次のサイクルに従う：計画 → 実装 → レビュー → 修正 → 検証
• フェーズ N が VERIFY に合格してからフェーズ N+1 を開始します。理由：未検証のフェーズを基盤にすると、下流でエラーが積み重なるためです

フェーズの成功条件 = すべての TC に合格 + code-reviewer エージェントの承認 + CRITICAL な指摘がないこと。

修正レイヤーの責任 — クラッシュ箇所で修正してはいけません。フロー全体をたどり、責任を持つレイヤーで修正します。

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

修正を行う前に必ず実施すること：

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

以下を満たすまで BLOCKED： - [ ] データフロー全体を追跡済み（発生元 → クラッシュ） - [ ] 不変条件の所有者を file:line のエビデンス付きで特定済み - [ ] すべてのアクセス箇所を監査済み（grep 件数） - [ ] 修正レイヤーの根拠を説明済み（最も多くの利用者を保護する最も低いレイヤー）

アンチパターン（却下すること）：

• 「クラッシュする箇所で修正する」— クラッシュ箇所 ≠ 原因箇所です。上流をたどります。
• 「すべての利用箇所に防御的チェックを追加する」— 防御が分散しているなら、レイヤーが間違っています。散在する多数のガードより、信頼できる 1 か所の修正が優先です。
• 「両方修正するほうが安全」— 信頼できるレイヤーを 1 つ選びます。複数レイヤーに重複したチェックを置くと、不変条件の所有者について矛盾したメッセージになります。 AI のミス防止 — どのタスクでも避けるべき失敗パターン：

コンテキストが変わったらファイルを読み直す。 コンテキストの圧縮、作業の再開、長時間にわたる作業によって、記憶が古くなっている可能性があります。作業を進める前に、最新のファイルを確認してください。 生成した内容をソースの根拠と照合する。 AI は API、名称、主張、文書内の事実を幻覚することがあります。文書に記載したり参照したりする前に、該当するソースを確認してください。 削除や名前変更の前に、下流の参照を確認する。 成果物を削除すると、ドキュメント、生成されたミラー、設定、呼び出し元に古い情報が残ることがあります。まず参照関係を洗い出してください。 編集後は影響範囲全体をたどる。 定義を変更しても、派生した出力や利用側への影響を見落とすことがあります。完了と宣言する前に、影響を受ける経路を最後まで確認してください。 最初の出力だけでなく、影響を受ける出力をすべて確認する。 1 つのチェックが成功しても、すべてのチェックが成功したとは限りません。変更の影響を受ける可能性のある出力先をすべて検証してください。 既存の値は意図的に設定されていると考え、変更または不具合として指摘する前に、理由を確認する。 定数、上限、フラグ、しきい値、文言、パターンを変更または報告する前に、周辺のコンテキストと履歴、呼び出し元における処理順序、同じ規約を使う他の 2 か所以上の呼び出し箇所を確認してください。理由を示さず WHAT（何をするか）だけを記載したドキュメントは、ガードがない証拠ではなく、根拠の説明が不足している状態です。 曖昧さを明らかにしてから行動する。黙って解釈を選ばない。 複数の妥当な解釈がある場合は、明示的に質問するか、リスクを添えて前提を示してください。 インフラが管理する中間状態ではなく、システムが担う結果をアサートする。 非同期処理を検証する際は、最終的なビジネス状態をアサートしてください。共有インフラ内で実行中の他プロセスが書き込む可能性のある、配信や再試行の記録は決してアサートしないでください。このようなチェックは単独実行では成功しますが、同じインフラを他の処理と共有した途端に不安定になります。 共有ガイダンスは、対象となる役割に関連する内容に保つ。 共通ガイダンスは、それを受け取るすべてのスキルやエージェントに役立つものでなければなりません。コード固有の義務は、コード固有のプロトコルにのみ記載してください。 ドメインエンティティ変更ゲート — ドメインエンティティ、値オブジェクト、または集約に触れる変更を計画・実装・レビューするすべてのスキルまたはエージェントを拘束する単一のプロトコルです。これにより、プランナー、実装者、レビュー担当者が、同じ変更に同じルールを適用します。完全な A–P チェックリストの正式な所有者は $domain-entities-review です。このゲートは、共通のトリガーと、回答必須の判断項目を定めます。より弱い独自のチェックリストを決して作り直さないでください。理由：計画とレビューでエンティティのルールが食い違うと、レビューで却下される設計を計画が出荷し、手戻りのコストが二重にかかるためです。

トリガー — 次のいずれかに該当すると発動します： 新しいエンティティ／値オブジェクト／集約ルートが導入される · 既存のものにフィールド、不変条件、関係、または状態遷移が追加・削除される · 集約境界、リポジトリ、または集約をまたぐ参照が変更される · ドメインイベントが追加、改名、またはペイロード変更される · ルートの並行性または再構成に関する懸念が変更される。該当するものがない場合は、No domain-entity surface — gate N/A と記載します。

ステップ 1 — 判断する前に検出します。 どちらの回答も、適用されるルールを左右します：

• パラダイム（集約ごとにコードから判定し、決して推測しない）：OO 可変 · 型駆動／不変 · イベントソーシング。セッター、可変性、再構成のルールは OO 可変向けです。他の 2 つに適用すると、誤った指摘や不要な計画タスクが生まれます。
• サブドメインとの適合性： コア（リッチモデルが必要） · 支援（Active Record または軽量モデル） · 汎用（購入し、モデル化しない） · CRUD（トランザクションスクリプト — ここでのリッチエンティティは形式だけのものです）。必須フィールド以外に不変条件がないサブドメインでは、リッチモデルを決して計画したり、指摘したりしないでください。

ステップ 2 — 6 つの判断項目すべてに回答します。 それぞれ、変更において明示的に判断しなければならない事項です：

#	判断項目	回答済みとなる条件
1	分類 — エンティティ、値オブジェクト、集約ルートのいずれか	入れ替えテスト（「同一のコピーと交換可能か？」）を適用している。値オブジェクトは不変で構造的等価性を持ち、リポジトリを持たない
2	不変条件の所有者 — エンティティは「この状態は存在可能か？」を所有し、境界は「この入力は受け入れ可能か？」を所有する	各ルールがどちらか一方に配置され、明示されている。失敗の通知方法（例外または Result）がプロジェクトの規約と一貫している。DB 制約は最後の防衛線であり、ルールでは決してない
3	集約境界と並行性	常に一貫性を保つべき真の不変条件だけを同じ集約にまとめる。集約をまたぐ参照には ID を使う。1 つのトランザクションで変更する集約は 1 つ。並行性トークンはルートが持つ。集合ベースの不変条件（インスタンス間の一意性）には、実際に強制する仕組みを明記し、メモリ内チェックは決して使わない
4	生成と再構成	生成と読み込みの経路が分かれている。読み込み経路ではドメインイベントを一切発行せず、生成ルールも一切再実行しない。必須データはコンストラクター／ファクトリーに置く
5	イベント	集約内で発行する。コミット後にディスパッチする（プロセスをまたぐ場合はアウトボックスを使用）。内部ドメインイベントと公開する統合契約を区別する。ハンドラーは冪等である
6	テストの要件	各不変条件を、全称量化されたプロパティ TC と境界の反例ケースの両方に対応付ける。仕様書で明示し、テストで GUARDED する（Dual-Feedback）。正常系の例が 1 つあるだけでは、カバレッジとは言えない

ステップ 3 — コンテキストに応じて適用します。 判断項目は同じですが、求められる対応は異なります：

呼び出し元のコンテキスト	要件
計画（$plan）	計画では、該当する各項目について判断内容と、それを担当するファイルを明記しなければなりません。未回答の項目がある計画は実行可能ではありません。実装で判明するまで放置せず、表面化させてください。
計画レビュー（$plan-review）	未回答、曖昧な説明、または実装への先送りがある項目は、計画内の file:line を示す指摘事項です。「entity」という語があるだけでは、決して回答になりません。
実装（$plan-execute、$fix、および実装を行うすべてのエージェント — 例：backend-developer）	判断事項は再検討する質問ではなく、入力です。該当する各項目を、計画／仕様で決定されたとおりに、指定された担当ファイルに実装します。未回答の項目が渡された場合はブロッカーです。表面化させて判断を得てください。キーボードを前にして黙って決めたり、計画で未決のままだからといって DB テーブルや UI 画面から集約境界を選んだりしては決していけません。どのルールを適用するかは、引き続きパラダイムとサブドメインとの適合性によって決まります。
変更レビュー（$changes-review）	所有者に引き継ぎます — モード A（デフォルト）： $domain-entities-review のフェーズ 2 の A–P チェックリストを読み、レビューの観点として適用します。モード B（エスカレーション）： 単独で実行され、差分にエンティティファイルが 3 つ以上含まれる場合は、$domain-entities-review に委任します。指摘事項は file:line と重大度を付けて通常の指摘事項セットに加えます。

重複防止 — 次のいずれかに該当する場合は、ゲート全体をスキップします。 委任を示す行を記録してから続行してください：

ゲートを抑止するコンテキスト	委任を示す行
実行中のスキル自体が $domain-entities-review である場合	Gate is this skill's own body — A–P checklist owns it.
$workflow-review-changes 内から呼び出されている場合（ステップ 5 で $domain-entities-review を専用の条件付き並列メンバーとして実行する）	Gate deferred to workflow step 5 $domain-entities-review.
$why-review が --validate-findings の終端モードで実行されている場合	Gate N/A — validate-findings is terminal, no sub-skill calls.

— 理由：このガードがないと、親ワークフローがすでに実行しているレビューと重複し、changes-review → domain-entities-review → why-review → changes-review の循環が発生します。

次のすべてを満たすまで BLOCKED： トリガーの評価が完了（または gate N/A を記録済み） · パラダイムとサブドメインとの適合性を明記済み · 該当する 6 つの判断項目すべてに回答済み、または指摘事項として提示済み · 委任の前にガード行を確認済み。 必ず注意 変更によって新規または更新されたドメインエンティティ、値オブジェクト、または集約の計画やレビューを行う場合は、ドメインエンティティ変更ゲートを適用します。$domain-entities-review が A〜P のチェックリスト全体を担当します。まずパラダイムとサブドメインの適合性を検出し、その後、6 つの判断ポイント（分類・不変条件の所有者と失敗通知・集約境界と並行性・構築と再構成・イベント・プロパティベースの TC テスト義務）すべてに回答します。計画では各判断を明記します。計画レビューでは、未回答の項目を FINDING として扱います。変更レビューでは、担当者に引き継ぎます（モード A は読み取り／モード B は委任）。3 行重複ガードに該当する場合は SKIP し、延期の行を記録します。— 理由：計画担当者とレビュー担当者が共有する単一のプロトコルによって、レビューで却下されるエンティティ設計を含む計画が出荷されるのを防げます。

• 必須の注意 見積もり：ボトムアップで算出したフェーズごとの時間を man_days_traditional の算出に使用します（Σh/6 × productivity_factor）。SP は派生値です。通常、UI コストが支配的です。新しい UI サーフェス（ページ／複雑なフォーム／ダッシュボード）がある場合は、SP を 1 段階引き上げます。Frontmatter には、story_points、complexity、man_days_traditional、man_days_ai、estimate_scope_included、estimate_scope_excluded、estimate_reasoning（UI とバックエンドのコスト要因）を必ず含めます。既存モデルと既存 UI に対する追加変更の場合、テスト範囲が 1.5 日を超えない限り、SP の上限は 3 です。SP 13 では分割を推奨し、SP 21 では必ず分割します。

重要な注意 各フェーズの TC ID を含む ## Test Specifications を追加します。新しいタスクを作成する前に、現在のタスクリストを確認します。

重要な注意 すべてのフェーズが粒度に関する 5 項目チェックに合格することを確認します。不合格のフェーズはサブプランに分割します。「今すぐコーディングを始められますか？」

重要な注意 変更を加える前に、既存のパターンを 3 つ以上検索し、コードを読みます。graph.db が存在する場合は、グラフトレースを実行します。

• 必須の重要な注意 すべての主張について、根拠となる file:line を示します。確信度が 80% を超える場合に実行し、60% 未満の場合は推奨しません。

重要な注意 まず複雑さをスコア化します。スコアが 6 以上の場合は分解します。各フェーズで、計画 → 実装 → レビュー → 修正 → 検証の順に進めます。省略は禁止です。

重要な注意 データフロー全体を追跡し、クラッシュ箇所ではなく、所有レイヤーで修正します。?. を追加する前に、すべてのアクセス箇所を監査します。

重要な注意 マイクロサービス／イベント駆動型の場合、タスクの範囲内にあるプロデューサー、コンシューマー、サガ、コントラクトを調査します。各タッチポイントについて、所有者・メッセージ・コンシューマー・リスク（NONE／ADDITIVE／BREAKING）を記録します。コンシューマーの見落としは、気づかれない回帰を招きます。

必ず注意 批判的思考と順序立てた思考を適用します。すべての主張には、適切に追跡した根拠が必要です（リポジトリ／コードに関する主張には file:line、調査、製品、コンテンツ、ドキュメントに関する主張にはソース URL またはアーティファクトのセクション）。確信度が 80% を超える場合に実行し、60% 未満の場合は推奨しません。ハルシネーション防止のため、推測を事実として提示せず、不確実性を率直に認め、独立して照合し、自身の確信度にも懐疑的であり続けます。

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

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

• 必須 対象作業を始める前にタスク追跡を初期化します。一度に 1 つのタスクだけを移行します。

• 必須 計画とレビューの所見を plans/reports/ に随時保存し、ディスク上の内容から統合します。

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

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

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

• 必須 親ワークフローの行で子フェーズの追跡を代替しないでください。ネストしている場合はフェーズを展開し、親へのリンクを記載してください。

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

• 必須 作業を始める前に、有効な Goal Contract を解決してください（有効な計画の goal.md → plans/goals/{YYMMDD-HHmm}-{slug}/goal.md → 現在のリクエストから作成）。編集前に、保存済みの成功基準を読み込んでください。

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

並列サブエージェントのディスパッチ — タスクの分解ができたら、実行を始める前に並列化を計画してください。明らかに独立したタスクを順次実行すると、所要時間を無駄にします。ワークフローのステップ、計画、バッチ更新、調査、リサーチ、スキャン、レビュー、ドキュメント同期など、複数ステップのすべてのジョブが対象です。計画の実行はメタデータによって制御され、デフォルトで並列化することはありません。ファンアウトは、計画で宣言された内容（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. 各サブエージェントには、自己完結した指示を渡してください。 ゴール、範囲と担当ファイル、参照ドキュメント、返却内容（SYNC:subagent-return-contract に従い、要約と Full report: のパス）、plans/reports/ への逐次保存（SYNC:incremental-persistence に従う）を含めてください。
6. ウェーブごとにバリアを設けてください。 すべてのメンバーから返答があるまで次に進んではいけません（条件によりスキップされたタスクも返答済みとして数えます）。結果を統合し、各タスクを完了またはスキップとして記録してから、次のウェーブをディスパッチしてください。変更を伴うステップはバリアを通過するまで待機させてください。
7. ネストは1階層までです。 ディスパッチされたサブエージェントは自身の指示を実行してください。それ以上のファンアウトはオーケストレーターが担当します。ただし、そのエージェントの .claude/agents/*.md 定義で許可されている場合を除きます。

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

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

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

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

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

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

締めくくりの確認事項

重要・必ず注意 目標： 検証済みで実装にすぐ着手できる計画を提示します。各フェーズは、正確なファイルパス、未決事項ゼロ、対応付け済みの TC ID を備え、ただちに開始できる状態にしてください。これにより、将来の変更コストを最小限に抑え、手戻りなくコーディングを進められます。

適用中のプロトコル（このスキルに含まれる SYNC/共有ブロックの簡潔な要約）：

• 計画の粒度: 各フェーズは5項目のチェックを通過するか、サブプランに分割します。
• 保全インベントリ: バグ修正計画では、不変条件を file:line と検証方法とともに一覧にします。
• ネストされたタスクの作成: 子スキルでは、可視のフェーズタスクを展開します。ネストする場合は親タスクにリンクします。
• プロジェクト参照ドキュメントガイド: 対象作業に取りかかる前に、必須のプロジェクトドキュメントを必ず読みます。
• タスクの追跡と外部レポート: タスクを初期化し、調査結果を plans/reports/ に保存します。
• 批判的思考: すべての主張には追跡可能な根拠が必要です。確信度が80％を超えてから行動します。
• 逐次的思考: 複数ステップの思考には、REVISION／BRANCH／HYPOTHESIS マーカー付きで Thought N/M を付けます。
• まずコードを理解する: 計画を立てる前にコードを読み、3つ以上のパターンを grep します。
• サービス横断チェック: 破壊的変更のリスクを把握するため、プロデューサー、コンシューマー、サーガ、コントラクトを調査します。
• 見積もりフレームワーク: フェーズごとの工数をボトムアップで算出し、人日を導きます。SP は算出値とします。
• 計画の品質: すべてのフェーズに、TC ID を含む ## Test Specifications を設けます。
• フェーズ品質の反復的な改善: まず複雑さを評価し、スコアが6以上の場合は分解します。
• 修正レイヤーの説明責任: クラッシュ発生箇所で修正してはなりません。不変条件を管理する箇所で修正します。
• AI の誤りの防止: 生成内容を根拠と照合し、下流の参照先を追跡し、影響を受けるすべての出力を検証し、コンテキスト喪失後に読み直し、曖昧さを明らかにします。
• 並列サブエージェントのディスパッチ: タスクに PAR／SEQ を付け、PAR のタスクを書き込み範囲が重複しないウェーブにまとめ、各ウェーブを1つのメッセージで起動します。次に進む前にバリアを設けます。 重要・必ず注意 計画のみです。コードを実装したり実行したりしてはいけません。plan.md、フェーズごとのファイル、Goal Contract の goal.md を作成し、引き継いでください。理由：このスキルの契約は計画であり、変更ではありません。 重要・必ず注意 デフォルトモードは HARD です。高速モードを選べるのは、些細なタスクの条件をすべて満たす場合に限ります。理由：重要なタスクで厳密さを省くと、厳密さによって削減できる手戻りよりも大きな手戻りが発生します。 必須・重要・必ず注意 作業を始める前に、タスク追跡を使って作業を小さな TODO タスクに分割してください。最終レビューの TODO も追加してください。コンテキストを失った場合は、まず現在のタスクリストを確認してください。タスクを重複させてはいけません。 必須・重要・必ず注意 調査を始める前に、Goal Contract（goal-contract-template.md を基にした goal.md）を準備してください。各フェーズの成功基準は、保存されたゴール基準に対応させてください。シークレットは伏せてください。 必須・重要・必ず注意 ユーザーに直接質問して、判断を確認してください。タスクが「明白」に思えるからといって、自動的に決めてはいけません。次のステップを決めるのはユーザーです。 必須・重要・必ず注意 すべてのフェーズで、5 項目の粒度チェック（「今すぐコーディングを始められますか？」）に合格する必要があります。不合格のフェーズはサブプランに分割してください（最大深度 3）。 必須・重要・必ず注意 プロジェクトに存在しない新しい技術／ライブラリを検出したら、ライブラリごとにタスク追跡を行い、WebSearch で上位 3 件を調べて比較し、確信度（%）付きで推奨案を提示して、ユーザーに直接質問してください。理由：未検証の依存関係は、早い段階で導入すると元に戻せない決定になります。 必須・重要・必ず注意 見積もりはボトムアップで行います。フェーズの時間から man_days_traditional を算出します（Σh/6 × productivity_factor）。SP は派生値であり、基準にしてはいけません。通常、UI のコストが大半を占めます。estimate_reasoning のフロントマター全体を出力してください。 必須・重要・必ず注意 すべてのフェーズに ## Test Specifications を含め、TC-{FEATURE}-{NNN} の ID を付けてください。すべての機能要件を 1 件以上の TC に対応付けてください（TDD を先行する場合は、明示的に Evidence: TBD と記載してください）。 必須・重要・必ず注意 .claude のスキル／フック／ワークフロー／同期作業では、生成されたミラーを同期するアクション、または同期が不要であることを示す明確な根拠を、計画に必ず含めてください。理由：ミラーがひそかに古くなると、ソースと食い違います。 必須・重要・必ず注意 計画作成後に $plan-review を省略してはいけません。単独で実行するか、ワークフローのステップとして実行してください。単独の $plan では、最後のタスクとして $changes-review も追加します。 重要・必ず注意 計画を立てる前に、既存のパターンを 3 件以上検索し、対象コードを読んでください。file:line 形式で参照を示してください。.code-graph/graph.db がある場合は、グラフトレースを実行してください。理由：ローカルの規約は、汎用的なフレームワークのデフォルト設定より優先されます。 必須・重要・必ず注意 メインパイプライン全体を順番どおりに実行してください。事前の計画チェック → goal.md の準備 → 1 回の調査ウェーブ（1 件のメッセージ内で researcher と scout を実行）→ バリア → コードベースとプロジェクト参照の分析（ドキュメントがない場合は scout を実行）→ planner が plan.md と phase-XX を作成 → 並列化のパス（PAR／SEQ + 書き込みセット + ## Execution Waves）→ 粒度のセルフチェック → 必須の最終タスク。明白に思えるからといって、ステップを省略してはいけません。理由：省略されたステップ（Goal Contract、粒度、テスト仕様）は、AI が気づかないうちに抜かしやすいものです。 必須・重要・必ず注意 調査スレッドは、1 回のウェーブとして 1 件のメッセージ内でディスパッチしてください（最初に Parallel plan: を宣言し、エージェントごとにレポートパスを 1 つ指定します）。すべてのメンバーから返答があるまで、結果を統合してはいけません。理由：並列化しやすい計画作業の半分を、調査担当者 1 人ずつ順に実行すると、時間を浪費します。 必須・重要・必ず注意 出力する計画には、並列化のメタデータを必ず含めてください。すべてのフェーズに PAR／SEQ のタグを付け、書き込みセットを宣言してください。また、すべての SEQ で待機対象の成果物を正確に指定し、plan.md に ## Execution Waves を含めてください。理由：$plan-execute が並列実行できるのは、計画に宣言された内容だけです。タグのない計画は、気づかないうちに順次実行を強制します。 必須・重要・必ず注意 すべての計画に最終タスクブロックを追加してください。フェーズごとのテスト仕様 → $plan-validate → $plan-review（最大 3 ラウンドの収束ループ。問題のないレビューになった時点で、何ラウンド目でも終了）→ $why-review（単独実行の場合のみ）→ 確定したフェーズに対して再見積もり（差分が 50% を超える場合は SHOULD-RESCOPE を付記）。 重要・必ず注意 --mode={ci|cro} は、同じエンジン、ゲート、planner エージェントに、ドメイン参照の読み込み（references/mode-ci.md／mode-cro.md）とインテークを追加するだけです。デフォルト（フラグなし）では標準フローをバイト単位でそのまま実行してください。モードによってエンジンを置き換えたり、$plan-review を省略したりしてはいけません。 合理化への反論：

回避理由	反論
「計画するにはタスクが簡単すぎる」	デフォルトモードは HARD です。すべての簡単な条件を満たす場合に限り、オプトアウトできます。
「コードベースのことはすでに把握している」	3 つ以上のパターンとグラフのトレースについて、file:line を提示してください。証拠がなければ、読んでいないのと同じです。
「フェーズは十分明確だ」	5 項目の粒度チェックを実施してください。「今すぐコーディングを始められるか」— そうでなければ、サブプランを作成してください。
「計画はよさそうなので、レビューは省略する」	$plan-review を省略してはなりません。新たな視点が作成者の見落としを見つけます。
「既存のライブラリだけなので、ゲートは省略する」	それを証明してください。マニフェストを grep してください。新しい技術やライブラリを導入する場合は、承認前に WebSearch を実行し、ユーザーに直接確認してください。
「そのまま SP を見積もる」	SP はフェーズごとのボトムアップの時間から導出するものであり、基準にしてはなりません。まず Σh/6 × productivity を計算してください。
「.claude の変更なので、同期は不要」	ミラーへの対応、または同期不要であることを示す明確な証拠を記してください。古いミラーはオラクルに失敗します。
「--mode=ci なので、通常のフローは省略する」	モードによって参照ペイロードが追加されるだけです。同じエンジン、同じ $plan-review、同じ planner エージェントを使います。
「計画は完了したので、最後のタスクは省略する」	Test Specs → $plan-validate → $plan-review → $why-review → 再見積もりは必須であり、任意ではありません。
「フェーズは順番どおりに見えるので、タグは省略する」	「順番どおりに見える」ことは依存関係ではありません。PAR／SEQ タグを付け、書き込みセットを宣言し、各 SEQ が待機する成果物を明記してください。
「実行側が順序を判断できる」	できません。$plan-execute が並列実行するのは、宣言された書き込みセットに基づく場合だけです。タグがなければ、あなたが引き起こした逐次実行になります。

[TASK-PLANNING] 作業に取りかかる前に、タスクの範囲を分析し、タスク追跡を使って小さな todo タスクとサブタスクに体系的に分割してください。

重要：必ず注意してください 計画のみです。実装は決して行わないでください。行動する際は file:line の証拠を引用してください（確信度が 80% を超えること）。$plan-review と New Tech/Lib および Goal-Contract のゲートは決して省略しないでください。

---

最後にもう一度 — 成功の指標は変更のしやすさです。 すべての指摘、 テスト、リファクタリング、抽象化について、次の 1 つの問いに答えてください。これによって 次の変更のコストは下がるのか、それとも上がるのか？ 将来の変更コストを下げないなら、却下してください。 結合、隠れた状態、重複した知識、意図の不明瞭さこそが真の敵です。名前を挙げて指摘してください。

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

ソース：.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. 実行： コンテキスト指示にある Workflow Step Advancement & Parallel Phases のルールに従って進めます。ステップの進行はモデル主導です。サブエージェントの完了はインライン呼び出しと同様にステップを進めます。並列フェーズのグループは全員の完了を待つバリアです（すべてのメンバーが完了した後にのみ進み、決して逐次化しません）。

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