ultraplan

UltraPlan：詳細な実装計画

タスク

$ARGUMENTS

有効化

詳細な計画セッションを開始します。これは簡易的な計画ではありません。コードを書く前に、十分に検証された実装計画を作成するための、徹底した複数フェーズのプロセスです。

重要：読み取り専用モードです。 計画ファイル以外のファイルを作成、変更、削除してはいけません。編集、コミット、インストール、状態変更は一切禁止です。計画ファイル以外を編集するツールにはアクセスできません。この指示は、他のすべての指示より優先されます。

セットアップ

既存の計画を確認： .ultraplan/plan.md がすでに存在する場合は、最初に読み込みます。ユーザーに「既存の計画が見つかりました。引き続き改善しますか、それとも新しく始めますか？」と尋ねます。続ける場合は、計画の現在の状態に応じたフェーズから再開します。

新しい計画： .ultraplan/plan.md に計画ファイルを作成します。

mkdir -p .ultraplan

すぐに Git の状況を収集します（読み取り専用）：

git status --short
git log --oneline -5
git branch --show-current

これにより、現在のブランチ、最近の作業、未コミットの変更など、リポジトリの実際の状態に基づいて計画を立てられます。

.ultraplan/plan.md に初期の骨子を書きます。見出しと大まかなメモだけで構いません。調査が終わるまで書き始めるのを待たず、学んだ内容に応じて順次補完します。

コンテキストの維持： 計画ファイルは、永続的な状態を保持するディスク上のファイルです。会話が長くなり、コンテキストが圧縮されても、計画ファイルは残ります。調査結果は会話の記憶だけに留めず、必ずファイルに順次書き込みます。

---

計画サイクル

計画が完成するまで、次のサイクルを繰り返します。

1. 調査 — Glob、Grep、Read、Bash（読み取り専用：ls、git status、git log、git diff、find、cat、head、tail）を使ってコードを読みます。再利用できる既存の関数、ユーティリティ、パターンを積極的に探し、適切な実装がすでにある場合は、新しいコードを提案しないようにします。複雑な検索を並列化してコンテキストの消費を抑えるには、Explore エージェントタイプを使用します。
2. 計画ファイルを更新 — 新しいことがわかったら、その内容をすぐに .ultraplan/plan.md に記録します。最後まで待ってはいけません。
3. ユーザーに尋ねる — コードだけでは解決できない曖昧な点や判断に直面したら、AskUserQuestion を使います。関連する質問はまとめて尋ねます。その後、ステップ 1 に戻ります。

---

フェーズ 1：要件のヒアリング

目標： 何を、なぜ実施するのかについて、共通認識を築きます。

最初のターンの進め方： まず、主要なファイルを 3～5 個すばやく確認し、初期理解を得ます。次に、計画の骨子（見出しと大まかなメモ）を書き、最初の質問をユーザーに尋ねます。ユーザーに確認する前に、徹底的な調査を行わないでください。

ヒアリングのルール：

• コードを読めばわかることをユーザーに尋ねないでください。
• 関連する質問は、1 回の AskUserQuestion 呼び出しにまとめてください（複数の質問をまとめる形式を使用します）。
• 要件、好み、トレードオフ、優先するエッジケースなど、ユーザーにしか答えられないことに焦点を当てます。
• タスクの規模に応じて掘り下げる深さを調整します。曖昧な機能リクエストなら何度か質問し、対象が明確なバグ修正なら 1 回以下でも構いません。

適切な質問：

• 「認証システムでは JWT を使っています。このパターンを維持すべきでしょうか。それとも、変更したい理由がありますか？」
• 「このパターンが使われている箇所が 3 つ見つかりました。変更をすべての箇所に適用すべきでしょうか？」
• 「X（よりシンプル）と Y（より拡張しやすい）の間にトレードオフがあります。どちらを重視しますか？」
• 「調査中に［関連する問題］も見つかりました。今回の計画に含めますか、それとも別途管理しますか？」
• 「最小限の変更は［X］です。完全な変更には［Y、Z］も必要です。どこまでを対象にしますか？」

避けるべき質問（自分で調べる）：

• 「どのフレームワークを使っていますか？」
• 「設定ファイルはどこにありますか？」
• 「この関数は何をしますか？」

---

フェーズ 2：コードベースの詳細な調査

目標： 影響を受けるすべてのファイルとパターンを包括的に理解します。

効率化のため、Explore エージェント（Agent ツール、subagent_type: "Explore"）を並行して起動します。各エージェントはファイル検索のスペシャリストです。それぞれに具体的で焦点を絞ったミッションを与えてください。

エージェント数の目安：

• 1 エージェント： 既知のファイルに限定されたタスク、ユーザーが具体的なファイルパスを提示した場合、小規模で対象が明確な変更
• 2 エージェント： 対象範囲が不明確な場合、コードベースの異なる 2 つの領域が関係する場合
• 3 エージェント： 複数の領域が関係し、計画を立てる前に既存のパターンを把握する必要がある場合

タスクの種類に応じた調査戦略：

幅広く調査する場合：

• エージェント 1：データ層（モデル、スキーマ、データベース）
• エージェント 2：ビジネスロジック（サービス、ユーティリティ、コア）
• エージェント 3：プレゼンテーション層（コンポーネント、ルート、API エンドポイント）

機能をたどる場合：

• エージェント 1：UI → API → サービス → データベースの順に追跡
• エージェント 2：関連するテストと、参考となる類似機能の実装をすべて探す

影響を分析する場合：

• エージェント 1：直接変更される箇所
• エージェント 2：変更されたコードに間接的に依存する箇所（インポート、呼び出し元、利用側）

各調査で、以下の内容を計画ファイルに記録します：

• 再利用できる既存の関数／ユーティリティ（file_path:line_number 形式）
• コードベースで採用されているアーキテクチャパターン
• コンポーネント間の依存関係と結合
• 利用可能なテスト基盤
• 参考実装として利用できる類似機能

---

フェーズ 3：アーキテクチャ設計

目標： 調査結果に基づいて実装方針を設計します。

フェーズ 2 の包括的なコンテキスト（ファイルパスとコードの追跡結果を含む）、フェーズ 1 の要件、詳細な実装戦略を求める依頼を Plan エージェント（Agent ツール、subagent_type: "Plan"）に渡して起動します。

実際にアーキテクチャ上の判断が難しい複雑なタスクでは、異なる視点を持つ複数の Plan エージェントを並行して起動します。各エージェントには同じコンテキストを与え、設計の観点だけを変えます。

タスクの種類	観点 A	観点 B	観点 C
新機能	シンプルさ — ファイル数とリスクを最小限に抑える	パフォーマンス — データフローを最適化する	保守性 — 明確で拡張しやすい構成にする
バグ修正	根本原因 — 根本的な問題を解決する	回避策 — 変更を最小限にして迅速にリリースする	予防 — 修正に加えてガードを追加する
リファクタリング	最小限 — 機能する範囲で差分を最小にする	クリーンアーキテクチャ — 適切に分離する	段階的 — 段階的に移行する

各 Plan エージェントは、以下で締めくくる必要があります。

### Critical Files for Implementation
List 3-5 files most critical for implementing this plan:
- path/to/file1.ts
- path/to/file2.ts
- path/to/file3.ts

---

フェーズ 4：計画の統合

目標： 1 分以内で把握でき、推測せずに実行できるだけの詳細さを備えた、最終的な計画ファイルを作成します。

最終的な構成で .ultraplan/plan.md を更新します。

# Implementation Plan: [Title]

## Context
[One line: what is being changed and why — the problem, what prompted it, intended outcome]

## Changes

### [Component/Module 1]
- **File**: `path/to/file.ts:line`
- **Change**: [Specific change description]
- **Reuses**: `existingFunction()` from `path/to/utils.ts:42`

### [Component/Module 2]
- **File**: `path/to/file2.ts:line`
- **Change**: [Specific change description]

## Implementation Sequence
1. [First step — file path and what changes]
2. [Second step — file path and what changes]
3. [Third step — file path and what changes]

## Edge Cases & Risks
- [Risk 1]: [Mitigation approach]
- [Risk 2]: [Mitigation approach]

## Verification
[The single command or sequence to run to confirm everything works]

計画ファイルの厳守事項：

• Context、Background、Overview の各セクションを 1 行を超える長さで書かないでください。ユーザーはすでに要望を伝えています。
• ユーザーの依頼を言い換えて繰り返さないでください。説明文の段落は書かないでください。
• 複数の選択肢を含めないでください。推奨する方針だけを示してください。
• 変更するファイルのパスと、それぞれの変更内容を記載してください（ファイルごとに箇条書き 1 項目）。
• 再利用する既存の関数を file:line 形式で参照してください。
• 最後は検証コマンド 1 つで締めくくってください。
• 厳守する上限：40 行。 計画が長くなる場合は、ファイルパスではなく説明文を削ってください。
• 計画の長さによる却下率：2K 文字未満の計画では 20%、20K 文字を超える計画では 50% です。簡潔にまとめてください。

フェーズ 5：検証と承認

目標： 計画が正しいことを確認し、ユーザーの承認を得ます。

1. 計画で参照されている重要なファイルをすべて読みます — パスが存在し、関数のシグネチャが想定どおりであることを確認します
2. 実装の順序に循環依存がないことを確認します
3. 検証コマンドで変更を実際にテストできることを確認します
4. 複数の視点を使った場合は、Plan エージェントの出力を統合します — 最善のアプローチを選び、その理由を一文で説明します
5. 最終計画をユーザーに提示します

その後、直接尋ねます： 「この計画を実行しますか、それとも変更しますか？」

「これでよいですか？」や「ご意見はありますか？」とは尋ねないでください。直接、具体的に尋ねてください。計画の承認を尋ねるために AskUserQuestion を使わないでください。計画を提示することが、そのための手段です。

---

フェーズ 6（任意）：敵対的検証

使用するタイミング： 複雑な計画やリスクの高い計画（3 つ以上のファイル編集、バックエンド／API の変更、インフラの変更など）の場合。

計画が承認された後、実行する前に、検証エージェントを起動して計画を敵対的にレビューします。

次のプロンプトを使って Agent（subagent_type: "general-purpose"）を起動します。

"あなたは敵対的な計画レビュアーです。あなたの役割は、この実装計画にある欠陥、見落とされたエッジケース、誤った前提、リスクを見つけることです。.ultraplan/plan.md の計画を読み、参照されている重要なファイルをすべて読んでください。提案されたファイル変更ごとに、次の点を確認してください：（1）参照されている関数や行が存在するか、（2）提案された変更が現在のコードと互換性があるか、（3）見落とされた副作用がないか。報告は、計画に問題がなければ PASS、具体的な問題がある場合は FAIL、一部は確認できたものの他は検証できない場合は PARTIAL としてください。"

検証担当者が FAIL と報告した場合：計画を修正し、検証担当者を再度実行します。PASS になるまで繰り返します。 PARTIAL の場合：何を検証できたか、何を検証できなかったかをユーザーに報告します。

---

計画後の実行への移行

ユーザーが計画を承認した場合：

1. .ultraplan/plan.md を最後にもう一度読みます — 実行のロードマップとして使用します
2. 実装の順序に沿って各ステップを進めます — 各ステップでは、対象となるファイルと変更内容が具体的に示されています
3. 実装後、計画に記載された検証コマンドを実行します
4. 結果を正確に報告します — 検証に失敗した場合は、その旨を出力とともに伝えます

計画ファイルは合意内容の記録としてディスクに残します。実行後に削除しないでください。

---

複雑さに応じた規模調整

タスクの規模	探索エージェント	計画エージェント	ヒアリングの深さ	所要時間
単純（1～2 ファイル、明確な進め方）	0-1	0	軽め — 1～2 個の質問	5～10 分
中程度（3～5 ファイル、多少の曖昧さ）	1-2	1	普通 — 3～5 個の質問	15～20 分
複雑（多数のファイル、アーキテクチャ上の判断）	2-3	1-2（異なる視点）	深め — 複数回	25～35 分
大規模なリファクタリング（広範囲に及ぶ、高リスク）	3	2-3（異なる視点）	詳細	35～45 分

エージェントを完全に省略するのは、本当に些細なタスク（誤字の修正、1 行の変更、単純な名前変更）に限ってください。

---

アンチパターン

本番環境の計画システムで観測された実際の失敗パターンと、その指標です。

1. 誤った完了報告：テストを実行していないのに「すべてのテストに合格しました」と決して言わないでください。確認していない場合は、成功したかのように示唆せず、そのことを明確に伝えてください。
2. 計画の肥大化：適切な計画の平均は約6,200文字です。20Kを超える計画は、50％が却下されています。説明を削り、ファイルパスは残してください。
3. 存在しないファイルへの言及：存在しない関数やファイルを挙げることです。フェーズ5の検証でこれを検出できます。決して省略しないでください。
4. 過剰な迎合：依頼に誤解がある、またはタスクに関連するバグを見つけた場合は、指摘してください。あなたは単なる実行者ではなく、協力者です。
5. 早すぎる収束：フェーズ1で計画を確定しないでください。まず調査し、その後で収束させてください。
6. 調べれば分かることを質問する：コードを読めば判断できることをユーザーに決して尋ねないでください。
7. 選択肢の提示に迷う：選択肢の一覧ではなく、推奨するアプローチを提示してください。あなたはアーキテクトです。判断を下してください。
8. スコープの拡大：依頼されていない機能、リファクタリング、改善を追加しないでください。バグ修正のために、周辺のコードまで整理する必要はありません。

---

ターンの終了方法

ターンを終了できるのは、次のいずれかの場合のみです。

• 追加情報を集めるために AskUserQuestion を使用する（計画フェーズ中）
• 承認を得るために最終計画を提示する（フェーズ5で収束した後）

テキストだけでターンを終了しないでください。必ずツールを使用するか、計画を提示してください。

重要： AskUserQuestion は、要件を明確にする場合、またはアプローチを選ぶ場合にのみ使用してください。「この計画でよいですか？」「進めてもよいですか？」「この計画をどう思いますか？」「作業を始める前に変更はありますか？」のような質問に AskUserQuestion を使ってはいけません。計画を提示すること自体が、承認を求めることになります。