plan-fast

[IMPORTANT] 作業を開始する前に、各ファイルの読み込みタスクも含め、すべての作業を小さなタスクに分割するために TaskCreate を使用してください。長いファイルによるコンテキストの喪失を防ぐためです。簡単な作業の場合、AI は注意を促してスキップするかどうかユーザーに尋ねる必要があります。

まずコードを理解する — 厳格なゲート：既存のコードを読むまで、記述、計画、修正を行わないでください。

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 が存在する場合） - [ ] 根拠をもとに前提を検証する

見積もり — 修正フィボナッチ数列：1（ごく簡単）→ 2（小規模）→ 3（中規模）→ 5（大規模）→ 8（非常に大規模）→ 13（エピック、分割することを推奨）→ 21（必ず分割）。計画のフロントマターに story_points と complexity を出力します。複雑度は自動導出されます：1～2＝低、3～5＝中、8＝高、13以上＝クリティカル。

• docs/project-reference/domain-entities-reference.md — ドメインエンティティのカタログ、関係、サービス間同期（作業にビジネスエンティティ／モデルが関係する場合に読みます）（コンテンツはフックによって自動挿入されます。読む前に [Injected: ...] ヘッダーを確認してください）
• docs/test-specs/ — モジュール別のテスト仕様（計画にテスト戦略を含めるため、既存の TC を読みます）

計画の品質 — すべての計画フェーズに、必ずテスト仕様を含めてください。

1. 各フェーズのファイルに ## Test Specifications セクションを追加し、TC-{FEAT}-{NNN} ID を記載します
2. 各機能要件を1つ以上の TC に対応付けます（または、理由を添えて明示的に TBD とします）
3. TC ID は TC-{FEATURE}-{NNN} 形式に従います。内容全体を埋め込まず、ID を参照してください
4. 新しいワークフローステップに進む前に、TaskList を呼び出してフェーズファイルを再読します
5. コンテキストが圧縮された場合は、まず TaskList を呼び出してください。タスクを重複して作成してはいけません
6. 完了とする前に、フェーズごとに TC の充足を検証します（根拠は TBD ではなく file:line 形式で示す必要があります）

モード： TDD 優先 → 既存の TC を Evidence: TBD で参照します。実装優先 → TBD を使用し、後から /tdd-spec で補完します。

反復的なフェーズの品質 — 計画を立てる前に複雑度を評価します。

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

• 変更するファイルは5つ以下
• 作業時間は3時間以下
• サイクルに従う：計画 → 実装 → レビュー → 修正 → 検証
• フェーズ N が検証に合格するまで、フェーズ N+1 を開始してはいけません

フェーズの成功条件＝すべての TC に合格し、code-reviewer エージェントが承認し、CRITICAL の指摘がないこと。 修正レイヤーの責任 — クラッシュした場所では絶対に修正しないでください。処理の流れ全体をたどり、責任を持つレイヤーで修正します。

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

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

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

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

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

• 「クラッシュした場所で修正する」 — クラッシュ箇所 ≠ 原因箇所です。上流をたどってください。
• 「すべての利用箇所に防御チェックを追加する」 — 防御を分散させるのは、レイヤーの選択が間違っています。あちこちにガードを追加するより、権威ある 1 か所で修正してください。
• 「両方で修正するほうが安全」 — 権威あるレイヤーを 1 つ選んでください。複数のレイヤーに重複するチェックを置くと、不変条件を誰が所有するのかについて矛盾したメッセージが伝わります。

短期間の計画でも、複雑度スコアを評価してください。スコアが 3 以上の場合は、フェーズごとに品質サイクルを設けた複数フェーズの計画を必ず作成してください。

クイックサマリー

目標： コードベースを分析し、コードを一切書かずに、構造化された実装計画を作成します。

ワークフロー：

1. 計画のコンテキストを確認する — 進行中の計画を再利用するか、命名規則に従って新しいディレクトリを作成します
2. コードベースを分析する — backend-patterns-reference.md、frontend-patterns-reference.md、project-structure-reference.md を読みます
3. 計画を作成する — YAML フロントマターを含む plan.md と phase-XX-*.md ファイルを生成します
4. 検証する — /plan-review を実行し、実装を開始する前にユーザーに確認を求めます

主なルール：

• EnterPlanMode ツールは使用しないでください。コードの実装も行わないでください
• ユーザーと協力してください：判断が必要な質問をし、推奨案とともに選択肢を提示します
• 計画の作成後は、必ず /plan-review で検証します

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

自動検出： 既存のコードベースが見つからない場合（src/、app/、lib/、server/、packages/ などのコードディレクトリがない、package.json／*.sln／go.mod などのマニフェストファイルがない、入力済みの project-config.json がない）、このスキルは /plan-hard に切り替えます。計画用の成果物（docs/、plans/、.claude/）は対象外です。プロジェクトには、実際のコードを含むディレクトリが必要です。

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

1. /plan-hard に切り替える — グリーンフィールドのプロジェクト立ち上げには、迅速な計画ではなく、詳細な調査が必要です
2. ユーザーに次のように伝えます：「グリーンフィールドのプロジェクトが検出されました。徹底的な調査と計画を行うため、/plan-hard に切り替えます。」
3. 理由：迅速な計画では調査が省略されますが、グリーンフィールドのプロジェクトには市場調査、技術評価、ドメインモデリングが必要です。これらはすべて、詳細な分析なしには不可能です

懐疑的な姿勢を保ってください。批判的思考と順を追った思考を適用してください。すべての主張には、追跡可能な根拠と信頼度のパーセンテージが必要です（アイデアは 80% を超える必要があります）。

planning スキルを有効にします。

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

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

ミッション

$ARGUMENTS

作成前チェック（有効な計画か、提案された計画か）

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

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

ワークフロー

planner サブエージェントを使用して、次の作業を行ってください。

1. 新規作成する場合：## Naming セクションの Plan dir: を使用してディレクトリを作成し、node .claude/scripts/set-active-plan.cjs {plan-dir} を実行します。 既存の計画を再利用する場合：Plan Context にある有効な計画のパスを使用します。 作業中は、すべてのサブエージェントに必ずディレクトリパスを渡してください。
2. planning スキルの「Plan Creation & Organization」ルールを厳守してください。
3. backend-patterns-reference.md、frontend-patterns-reference.md、project-structure-reference.md を読み、コードベースを分析してください。 3.5. 外部メモリ：分析結果を .ai/workspace/analysis/{task-name}.analysis.md に書き込んでください。計画を作成する前に、このファイルを読み直してください。
4. 必要な情報をすべて集め、このタスクの実装計画を作成してください。
5. ユーザーに計画の確認を求めてください。

出力要件

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

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

計画ファイルの仕様

• すべての 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 }
  branch: { current git branch }
  tags: [relevant, tags]
  created: { YYYY-MM-DD }
  ---
  

• 概要のエントリーポイントを {plan-dir}/plan.md に保存してください。汎用的な内容とし、80行以内にまとめて、実装フェーズごとにステータスと進捗を記載し、各フェーズのファイルへのリンクを含めてください。

• 各フェーズについて、次のセクションをこの順序で含む {plan-dir}/phase-XX-phase-name-here.md を作成してください。Context links（親計画、依存関係、ドキュメントへの参照）、Overview（日付、説明、優先度、実装ステータス、レビュー状況）、Key Insights、Requirements、Architecture、UI Layout（下記参照）、Related code files、Implementation Steps、Todo list、Success Criteria、Risk Assessment、Security Considerations、Next steps。

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

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

• 必ず TaskCreate を使用して、作業を多数の小さな todo タスクに分割してください。
• 作業品質を検証し、修正や改善点を特定する最終レビュー用の todo タスクを必ず追加してください。
• 必須の最終タスク： すべての計画用 todo タスクを作成した後、必ず次の3つの最終タスクを追加してください。
  1. タスク：「各フェーズのテスト仕様を作成する」 — 各フェーズのファイルに TC-{FEAT}-{NNN} ID を付けた ## Test Specifications を追加します。機能ドキュメントがある場合は /tdd-spec を使用してください。TDD ファーストモードでは Evidence: TBD を使用してください。
  2. タスク：「/plan-validate を実行する」 — /plan-validate スキルを起動し、重要な質問でユーザーに確認しながら計画の前提を検証してください。
  3. タスク：「/plan-review を実行する」 — /plan-review スキルを起動し、計画の妥当性、正確性、ベストプラクティスへの準拠を自動レビューしてください。

計画後の検証

計画を作成した後、AskUserQuestion ツールを使用して、「/plan-review を実行して検証しますか、それとも実装に進みますか？」と質問します。選択肢は次のとおりです。

• 「/plan-review を実行（推奨）」 — /plan-review を実行して計画を検証します
• 「実装に進む」 — 検証をスキップして実装を開始します

重要な注意事項

• 重要： 高品質を維持しながら、トークン消費を効率化してください。
• 重要： スキルカタログを分析し、作業中に必要なスキルを有効化してください。
• 重要： レポートを作成する際は、簡潔さを優先して文法を犠牲にしてください。
• 重要： レポートでは、未解決の質問があれば末尾に列挙してください。

リマインダー — 計画専用コマンド

使用しないでください：EnterPlanMode ツール。 開始しないでください：実装。 必ず実行してください：計画作成後に /plan-review で検証します。 必ず確認してください：実装を開始する前に、ユーザーに計画の確認を求めます。 複数のアプローチがある場合：推奨案を添えて、ユーザーに判断を求めます。

---

計画の粒度に関する自己チェック（必須）

計画の粒度 — 実装前に、すべてのフェーズが次の5項目を満たす必要があります。

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

不合格のフェーズ → サブ計画を作成します。すべてのリーフフェーズが合格するまで繰り返してください（最大深度：3）。 自問してください：「今すぐコーディングを始められるか？ どのステップでも『把握する』必要があるなら、サブ計画に分解する。」

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

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

次のステップ（単独実行：AskUserQuestion でユーザーに必ず質問してください。ワークフロー内の場合はスキップしてください。）

必須・重要・要対応 — 例外なし： このスキルがワークフロー外で呼び出された場合、必ず AskUserQuestion を使用して次の選択肢を提示してください。タスクが「簡単」または「明白」に思えても省略しないでください。判断するのはユーザーです。

• 「フルワークフローに進む（推奨）」 — 最適なワークフローを自動的に検出し、ここから続行します（計画は作成済みです）。これにより、レビュー、検証、実装、テストのステップが省略されないようにします。
• 「/plan-review」 — 計画の妥当性とベストプラクティスを自動レビューします
• 「/plan-validate」 — ユーザーに質問し、計画の決定事項を確認します
• 「スキップして手動で続行」 — ユーザーが判断します

すでにワークフロー内にいる場合はスキップしてください。実行順序はワークフローが管理します。

完了時のリマインダー

• IMPORTANT MUST ATTENTION 作業を始める前に、TaskCreate を使って作業を小さな ToDo タスクに分割してください

• IMPORTANT MUST ATTENTION 新しいコードを作成する前に、コードベースで類似パターンを 3 件以上検索してください

• IMPORTANT MUST ATTENTION すべての主張について file:line の根拠を示してください（確信度が 80％を超える場合に対応すること）

• IMPORTANT MUST ATTENTION 作業品質を検証するための最終レビュー ToDo タスクを追加してください

• IMPORTANT MUST ATTENTION 計画のフロントマターに「テスト仕様」セクションと story_points を含めてください

• IMPORTANT MUST ATTENTION すべてのフェーズが 5 ポイント粒度チェックに合格することを確認してください。不合格のフェーズはサブプランに分割してください。「今すぐコーディングを始められますか？」

• IMPORTANT MUST ATTENTION 変更を加える前に、既存パターンを 3 件以上検索し、コードを読んでください。graph.db が存在する場合はグラフトレースを実行してください。

• IMPORTANT MUST ATTENTION 計画のフロントマターに story_points と complexity を含めてください。SP が 8 を超える場合は分割してください。

• IMPORTANT MUST ATTENTION ## Test Specifications にフェーズごとの TC ID を含めてください。新しいタスクを作成する前に TaskList を呼び出してください。

• IMPORTANT MUST ATTENTION まず複雑さを採点してください。スコアが 6 以上の場合は分解してください。各フェーズでは、計画 → 実装 → レビュー → 修正 → 検証の順に進めてください。省略しないでください。

• IMPORTANT MUST ATTENTION データフロー全体を追跡し、クラッシュが発生した箇所ではなく、所有するレイヤーで修正してください。?. を追加する前に、すべてのアクセス箇所を監査してください。