solo-plan

/plan

このスキルは自己完結型です。外部の計画スキル（superpowers など）に委任せず、以下の手順に従ってください。

コードベースを調査し、仕様と段階的な実装計画を作成します。対話形式での質問は行わず、コードを調査します。

使用するタイミング

具体的なファイル単位の実装計画を伴う、あらゆる機能、バグ修正、リファクタリングの作業トラックを作成します。/setup の有無にかかわらず使用できます。

MCP ツール（利用可能な場合に使用）

• session_search(query) — Claude Code のチャット履歴から類似する過去の作業を探します
• project_code_search(query, project) — プロジェクト間で再利用可能なコードを探します
• codegraph_query(query) — 影響を受けるファイルの依存関係を確認します
• codegraph_explain(project) — アーキテクチャの概要を表示します。技術スタック、言語、ディレクトリ層、主要なパターン、主な依存関係、ハブとなるファイルが含まれます
• kb_search(query) — 関連する手法をナレッジベースから検索します

MCP ツールを利用できない場合は、Glob + Grep + Read に切り替えます。

手順

1. タスクの説明を解析します。対象は $ARGUMENTS です。

   • 空の場合は、AskUserQuestion を使って「どの機能、バグ、またはリファクタリングの計画を立てますか？」と尋ねます。
   • 質問は最大 1 つです。

2. コンテキストを検出し、計画ファイルの保存先を決定します。

   プロジェクトコンテキスト（コードを含む通常のプロジェクト）：

   • 作業ディレクトリに package.json、pyproject.toml、Cargo.toml、*.xcodeproj、または build.gradle.kts が存在することで検出します
   • 計画のパス：docs/plan/{trackId}/

   ナレッジベースコンテキスト（ドキュメント中心のプロジェクト）：

   • パッケージマニフェストが見つからず、docs/、notes/、または番号付きの構造化ディレクトリなどが存在することで検出します
   • 計画のパス：docs/plan/{shortname}/
   • 注：shortname はタスクから導出します（kebab-case、ディレクトリ名に日付の接尾辞は付けません）

   検出したコンテキストに基づいて $PLAN_ROOT を設定します。以降のファイルパスではすべて $PLAN_ROOT を使用します。

3. プロジェクトのコンテキストを読み込む（並列に読み込みます）：

   • CLAUDE.md — アーキテクチャ、制約、実施事項／禁止事項
   • docs/prd.md — プロダクトの機能（存在する場合）
   • docs/workflow.md — TDD ポリシー、コミット戦略（存在する場合）
   • package.json または pyproject.toml — 技術スタック、バージョン、依存関係

4. タスクの種類を自動分類します。タスクの説明に含まれるキーワードに基づいて分類します。

   • 「fix」、「bug」、「broken」、「error」、「crash」を含む → bug
   • 「refactor」、「cleanup」、「reorganize」、「migrate」を含む → refactor
   • 「update」、「upgrade」、「bump」を含む → chore
   • それ以外 → feature

5. 調査フェーズ — 変更が必要な箇所を把握するため、コードベースを調査します。

   a. アーキテクチャの概要を取得します（MCP が利用可能な場合は最初に実行します）。

   codegraph_explain(project="{CLAUDE.md またはディレクトリ名から取得したプロジェクト名}")
   

   技術スタック、言語、ディレクトリ層、主要なパターン、主な依存関係、ハブとなるファイルが表示されます。

   b. RepoMap を取得します（MCP が利用可能な場合）。

   codegraph_repomap(project="{CLAUDE.md またはディレクトリ名から取得したプロジェクト名}")
   

   重要なファイルと、それらがエクスポートするシンボル（クラス／関数）の YAML マップが表示されます。

   c. 関連ファイルを探します — タスクに関連するパターンを Glob + Grep で検索します。

   • タスクの説明に含まれるキーワードを検索します
   • ディレクトリ構造を確認して、アーキテクチャを把握します
   • 変更が必要なファイルを特定します

   d. 先例を取得します（コンテキストグラフのパターン — 計画を立てる前に過去の解決策を検索します）。

   • 過去のセッションを検索します（MCP が利用可能な場合）。

     session_search(query="{タスクの説明に含まれるキーワード}")
     

     類似タスクの解決方法、問題点、効果のあったパターンを確認します。
   • 関連する手法をナレッジベースから検索します。

     kb_search(query="{タスクの種類}: {キーワード}")
     

     ハーネスのパターン、アーキテクチャ上の制約、品質スコアを確認します。

   e. プロジェクト間でコードを検索します（MCP が利用可能な場合）。

   project_code_search(query="{関連するパターン}")
   

   f. 影響を受けるファイルの依存関係を確認する（MCP を利用できる場合）：

   codegraph_query(query="MATCH (f:File {path: '{file}'})-[:IMPORTS]->(dep) RETURN dep.path")
   

   g. 影響を受ける領域の既存テストを読む — 使用されているテストパターンを把握します。

   h. CLAUDE.md のアーキテクチャ上の制約を読む — 境界と規約を把握します。

   • ハーネスのセクションを確認します：モジュール境界、データ検証ルール、Lint 設定。
   • docs/ARCHITECTURE.md と docs/QUALITY_SCORE.md があれば読みます。

   i. デプロイインフラを検出する — デプロイフェーズを計画に含めるため、デプロイスクリプトや設定を検索します：

   find . -maxdepth 3 \( -name 'deploy.sh' -o -name 'Dockerfile' -o -name 'docker-compose.yml' -o -name 'wrangler.toml' -o -name 'sst.config.ts' \) -type f 2>/dev/null
   

   見つかった場合は、それらを読んでデプロイ先を把握します。具体的なコマンドを含むデプロイフェーズを計画に追加します。

6. 重複する計画を検出する — 新しいトラックを作成する前に、同様の範囲をカバーする既存の計画を確認します。

   ls docs/plan/*/plan.md docs/plan/*/spec.md 2>/dev/null
   

   見つかった既存の計画ごとに、以下を行います：

   • spec.md の概要と受け入れ条件を読みます。
   • 新しいタスクの説明と範囲を比較します。
   • タスクが重複しているかを確認します（ファイルまたは受け入れ条件の50％超が共通）。

   重複が検出された場合：

   • 既存の計画が未完了の場合（[ ] のタスクが残っている）：新しいトラックを作成せず、既存の計画を拡張することを推奨します。ユーザーに次のように表示します：「既存のトラック {trackId} は同様の範囲をカバーしています（{overlap description}）。拡張しますか、それとも別のトラックを作成しますか？」
   • 既存の計画が完了している場合（すべてのタスクが [x]）：新しいトラックを続行しますが、spec.md の Dependencies で以前のトラックを参照します。
   • 複数の既存計画が互いに重複している場合：続行する前に、1つのトラックに統合することを推奨します。

   重複がない場合： 通常どおり続行します。

7. トラック ID を生成する：

   • タスクの説明から短い名前（2～3語、ケバブケース）を抽出します。
   • 形式：{shortname}_{YYYYMMDD}（例：user-auth_20260209）。

8. トラックディレクトリを作成する：

   mkdir -p $PLAN_ROOT
   

   • プロジェクトのコンテキスト：docs/plan/{trackId}/
   • KB のコンテキスト：docs/plan/{shortname}/

9. $PLAN_ROOT/spec.md を生成する： 一般的な質問ではなく、調査結果に基づいて作成します。

   # Specification: {Title}
   
   **Track ID:** {trackId}
   **Type:** {Feature|Bug|Refactor|Chore}
   **Created:** {YYYY-MM-DD}
   **Status:** Draft
   
   ## Summary
   {1-2 paragraph description based on research}
   
   ## Acceptance Criteria
   - [ ] {concrete, testable criterion}
   - [ ] {concrete, testable criterion}
   {3-8 criteria based on research findings}
   
   ## Dependencies
   - {external deps, packages, other tracks}
   
   ## Out of Scope
   - {what this track does NOT cover}
   
   ## Technical Notes
   - {architecture decisions from research}
   - {relevant patterns found in codebase}
   - {reusable code from other projects}
   

10. $PLAN_ROOT/plan.md を生成する： 調査に基づき、ファイル単位の具体的な計画を作成します。簡潔にまとめます：2～4フェーズ、タスクは合計5～15件。

    重要な形式ルール（/build によって解析されます）：

    • フェーズ見出し：## Phase N: Name
    • タスク：- [ ] Task N.Y: Description（ピリオドまたは詳細な説明を付けます）
    • サブタスク：インデントして - [ ] Subtask description
    • すべてのタスクに [ ]（未着手）、[~]（進行中）、[x]（完了）を使用します。

    # Implementation Plan: {Title}
    
    **Track ID:** {trackId}
    **Spec:** [spec.md](./spec.md)
    **Created:** {YYYY-MM-DD}
    **Status:** [ ] Not Started
    
    ## Overview
    {1-2 sentences on approach}
    
    ## Phase 1: {Name}
    {brief description of phase goal}
    
    ### Tasks
    - [ ] Task 1.1: {description with concrete file paths}
    - [ ] Task 1.2: {description}
    
    ### Verification
    - [ ] {what to check after this phase}
    
    ## Phase 2: {Name}
    ### Tasks
    - [ ] Task 2.1: {description}
    - [ ] Task 2.2: {description}
    
    ### Verification
    - [ ] {verification steps}
    
    {2-4 phases total}
    
    ## Phase {N-1}: Deploy (if deploy infrastructure exists)
    _Include this phase ONLY if the project has deploy scripts/configs (deploy.sh, Dockerfile, docker-compose.yml, wrangler.toml, sst.config.ts, vercel.json). Skip if no deploy infra found._
    
    ### Tasks
    - [ ] Task {N-1}.1: {concrete deploy step — e.g. "Run python/deploy.sh to push Docker image to VPS", "wrangler deploy", etc.}
    - [ ] Task {N-1}.2: Verify deployment — health check, logs, HTTP status
    
    ### Verification
    - [ ] Service is live and healthy
    - [ ] No runtime errors in production logs
    
    ## Phase {N}: Docs & Cleanup
    ### Tasks
    - [ ] Task {N}.1: Update CLAUDE.md with any new commands, architecture changes, or key files
    - [ ] Task {N}.2: Update README.md if public API or setup steps changed
    - [ ] Task {N}.3: Remove dead code — unused imports, orphaned files, stale exports
    
    ### Verification
    - [ ] CLAUDE.md reflects current project state
    - [ ] Linter clean, tests pass
    
    ## Final Verification
    - [ ] All acceptance criteria from spec met
    - [ ] Tests pass
    - [ ] Linter clean
    - [ ] Build succeeds
    - [ ] Documentation up to date
    
    ## Context Handoff
    _Summary for /build to load at session start — keeps context compact._
    
    ### Session Intent
    {1 sentence: what this track accomplishes}
    
    ### Key Files
    {list of files that will be modified, from research}
    
    ### Decisions Made
    {key architecture decisions from research phase — why X over Y}
    
    ### Risks
    {known risks or edge cases discovered during research}
    
    ---
    _Generated by /plan. Tasks marked [~] in progress and [x] complete by /build._
    

    計画の品質ルール：

    • すべてのタスクに、具体的なファイルパス（調査で特定したもの）を記載します。
    • タスクはアトミックにします。各タスクは1つのコミットに対応します。
    • フェーズはそれぞれ独立して検証できるようにします。
    • 合計は5～15タスクにします（70件ではありません）。
    • 最後のフェーズは必ず「Docs & Cleanup」にします。
    • 条件とタスクの対応付け： spec.md のすべての受け入れ条件に、plan.md の少なくとも1つのタスクを必ず対応させます。両方のファイルを生成した後、各条件を列挙し、それに対応するタスクがあることを確認します。対応するタスクがない条件があれば、タスクを追加します。条件の未対応は、「計画は完了したが仕様を満たしていない」という問題の最大の原因です。
    • ハーネスを考慮する： タスクで新しいパターンを導入する場合は、Lint ルールまたは CLAUDE.md の制約を更新するタスクを含めます。モジュール境界に関わる場合は、依存関係の方向を検証するタスクを含めます。「今後のエージェントがこれを壊さないようにするには、どのハーネスの変更が必要か」を考えます。

11. 進捗確認用のタスクリストを作成する：

plan.md を書いた後、進捗を追跡できるように TaskCreate エントリを作成します。

• フェーズごとに1つのタスクを作成します。説明にはタスクリストを記載します。「Phase 1: {name}」
• これにより、ユーザーとパイプラインは計画の進捗をリアルタイムで確認できます。
• /build は作業を進めながら、これらのタスクを更新します。 superpowers:writing-plans スキルが利用可能な場合は、その粒度形式に従います。細分化したタスク（各 2～5 分）、タスクの説明に完全なコード、正確なファイルパス、タスクごとの検証手順を含めます。これにより、上記の組み込み形式が強化されます。

11. AskUserQuestion で承認用の計画を提示する： 仕様の概要と計画の概要を提示します。選択肢：

• 「承認して開始」 — /build を実行する準備ができています
• 「計画を編集」 — 実装前に変更したい
• 「キャンセル」 — トラックを破棄する

「計画を編集」が選択された場合は、$PLAN_ROOT/plan.md を手動で編集してから /build を実行するようユーザーに伝えます。

出力

Track created: {trackId}

  Type:   {Feature|Bug|Refactor|Chore}
  Phases: {N}
  Tasks:  {N}
  Spec:   $PLAN_ROOT/spec.md
  Plan:   $PLAN_ROOT/plan.md

Research findings:
  - {key finding 1}
  - {key finding 2}
  - {reusable code found, if any}

Next: /build {trackId}

よくある誤った判断

次のような考えが浮かんだら、いったん止めて調査してください。調査を省略しようとしています。

考え	実際のところ
「このコードベースは把握している」	把握しているのは、これまでに見た範囲だけです。まだ見ていない部分を検索してください。
「計画は明らかだ」	明白に見える計画では、エッジケースを見落とします。まず調査してください。
「とにかくコーディングを始めよう」	10 分の調査で、2 時間のやり直しを防げます。
「小さな機能だ」	小さな機能でも、多くのファイルに影響します。影響範囲を把握してください。
「進めながら考えよう」	それは計画ではありません。まずファイルパスを書き出してください。
「70 個のタスクで十分だ」	5～15 個のタスクにしてください。それ以上必要なら、複数のトラックに分割してください。

互換性に関する注意事項

• 計画の形式は /build が解析できるものにしてください：## Phase N:、- [ ] Task N.Y:。
• /build は TDD ポリシーとコミット方針を確認するため、docs/workflow.md を読み込みます（存在する場合）。
• docs/workflow.md がない場合、/build は妥当な既定値（中程度の TDD、Conventional Commits）を使用します。

よくある問題

計画のタスクが多すぎる

原因： 機能の範囲が広すぎるか、タスクが十分に細分化されていません。 対処法： 2～4 フェーズで 5～15 個のタスクを目標にしてください。大規模な機能は複数のトラックに分割します。

コンテキストの判定が誤っている（プロジェクトと KB）

原因： ディレクトリに、コードのマニフェストとナレッジベース形式のディレクトリの両方があります。 対処法： package.json または pyproject.toml が存在する場合は、プロジェクトのコンテキストを優先します。

調査フェーズで関連コードが見つからない

原因： コードベースがほとんどない新しいプロジェクトであるか、MCP ツールを利用できません。 対処法： スキルは Glob と Grep にフォールバックします。新しいプロジェクトでは、計画は CLAUDE.md のアーキテクチャとスタックの慣例により多く依存します。