planning

構造化された計画

概要

構造化された計画では、コードを書く前に、曖昧な要件を承認済みの文書化された実装計画に落とし込みます。確認のための質問、トレードオフを含むアプローチの比較、明示的なユーザーの承認を必須にすることで、無駄な作業の最も一般的な原因である「間違ったものを作ってしまうこと」を防ぎます。簡単に見えるかどうかにかかわらず、すべてのタスクでこのプロセスを実施します。

開始時に宣言します：「計画スキルを使用して、構造化された実装計画を作成します。」

トリガー条件

• ユーザーが新機能、機能強化、または変更を依頼した場合
• バグ修正に1行を超える変更が必要な場合
• 複数のファイルにまたがるリファクタリング作業
• アプローチがまだ文書化されておらず、承認もされていないタスク
• 承認済みの設計がある状態で、ブレインストーミングスキルから移行する場合
• /plan コマンドが実行された場合

---

フェーズ 1：コンテキストの収集

目標： 質問する前に、コードベースと既存のパターンを把握します。

1. 関連するファイル、ドキュメント、最近のコミット、CLAUDE.md を確認します
2. 既知のプロジェクトのコンテキスト、技術スタック、規約について、メモリファイルを確認します
3. 関連する作業がないか、docs/plans/ にある既存の計画を確認します
4. 新しい作業で踏襲すべき既存のパターンを特定します
5. 調査中に見つかった技術的な制約を書き留めます

停止 — 次の条件を満たすまでフェーズ 2 に進んではいけません：

• コードベースの関連箇所を調査している
• 既存のアーキテクチャとパターンを理解している
• 過去の決定についてメモリファイルを確認している

---

フェーズ 2：確認のための質問

目標： 一度に1つずつ、的を絞った質問をして曖昧さをなくします。

1. 1回のメッセージにつき質問は1つだけにします。複数の質問で相手を圧倒してはいけません
2. 可能な場合は選択式の質問を優先します
3. 質問する前にコードベースを調べます。調査で分かることを質問してはいけません
4. 曖昧な要件を、具体的で検証可能な基準に置き換えます

質問カテゴリの優先順位

優先度	カテゴリ	質問の例
1	目的	「これはどのような問題を解決しますか？誰を対象としていますか？」
2	成功基準	「どのように動作を確認しますか？『完了』とはどのような状態ですか？」
3	制約	「パフォーマンス、互換性、またはスケジュール上の制約はありますか？」
4	対象外	「明示的に実装しないものは何ですか？」
5	既存のパターン	「X で使われているパターンに従うべきですか？それとも新しいアプローチが必要ですか？」
6	エッジケース	「［境界条件］の場合、どのように動作するべきですか？」

質問のルール

ルール	理由
1回のメッセージにつき質問は1つ	認知的な負荷を防ぎます
選択式の質問を優先	回答が速くなり、曖昧さも減ります
質問前に調査	ユーザーの時間を尊重し、調べられることは事前に確認します
検証可能な基準	回答が曖昧だと、実装も曖昧になります

停止 — 次の条件を満たすまでフェーズ 3 に進んではいけません：

• 目的と成功基準を理解している
• 制約と対象外の項目を特定している
• 重大な曖昧さが残っていない

---

フェーズ 3：アプローチの設計

目標： トレードオフを示したうえで、具体的なアプローチを2～3案提案し、明確な推奨案を示します。

各アプローチには、以下を含めます：

セクション	内容
アーキテクチャの概要	アプローチを説明する2～3文
主要なファイル	作成または変更する正確なパス
依存関係	外部依存関係または互換性を損なう変更
トレードオフ	メリットとデメリットを明記
作業量の見積もり	タスク数（時間ではありません）
リスクレベル	理由を添えた低／中／高のいずれか

アプローチ選択の判断表

要素	重要度	評価方法
既存パターンとの整合性	高	現在のコードベースの慣例に合っていますか？
シンプルさ	高	要件を満たすうえで、可動部分が最も少ない方法ですか？
テスト容易性	中	各コンポーネントを個別にテストできますか？
将来の拡張性	低	ユーザーが将来の計画に言及した場合にのみ検討します
パフォーマンス	変動	ユーザーがパフォーマンス上の制約を指定した場合にのみ検討します

まず推奨するアプローチを提示してください。 制約を踏まえて、なぜそれが最善の選択なのかを説明します。トレードオフを検討したことがわかるよう、代替案も提示します。

停止 — 以下を満たすまでフェーズ 4 に進まないでください。

• 2 つ以上のアプローチを提案している
• 各アプローチのトレードオフを記録している
• 理由を添えて明確な推奨を示している

---

フェーズ 4：計画のドキュメント化

目標： 詳細で実行可能な計画ドキュメントを作成し、明示的な承認を得ます。

計画ドキュメントの形式

# [Feature Name] Implementation Plan

**Goal:** [One sentence]
**Architecture:** [2-3 sentences]
**Approach:** [Which approach was chosen and why]

---

### Task N: [Component Name]

**Files:**
- Create: `exact/path/to/file.ext`
- Modify: `exact/path/to/existing.ext`
- Test: `tests/exact/path/to/test.ext`

**Steps:**
1. Write the failing test
2. Run test to verify it fails
3. Write minimal implementation
4. Run test to verify it passes
5. Commit

**Verification:** [Exact command to verify this task]

計画の品質チェックリスト

基準	確認事項
各タスクに正確なファイルパスが記載されている	「src/ のどこか」としない
各タスクに検証コマンドがある	「目視で確認」としない
タスクが依存関係の順に並んでいる	前方参照がない
各タスクが 2～5 分で完了する	「モジュール全体を実装する」としない
TDD の手順が明示されている	タスクごとに RED-GREEN-REFACTOR を実施する

計画を docs/plans/YYYY-MM-DD-<feature>.md に保存します。

停止 — 以下を満たすまでフェーズ 5 に進まないでください。

• 計画ドキュメントを作成して保存している
• 各タスクにファイルパス、手順、検証方法が記載されている
• ユーザーから計画への明示的な承認（「はい」、「承認します」、「進めてください」など）を得ている

---

フェーズ 5：実行への移行

目標： 承認済みの計画を、適切な実行スキルに引き継ぎます。

移行の判断表

状況	次のスキル	理由
標準的な実装（10 タスク未満）	task-management	追跡可能な順次実行
大規模な実装（独立したタスクが 10 件以上）	subagent-driven-development	レビューゲートを設けた並列実行
自律的な開発セッション	autonomous-loop	Ralph 方式の反復実行
単一の、範囲が明確なタスク	executing-plans	計画を直接実行

選択したスキルを呼び出し、計画ドキュメントのパスを渡します。

---

アンチパターン／よくある間違い

アンチパターン	失敗する理由	正しいアプローチ
「これは計画するほどのことではありません」	単純なタスクにも、検討されていない前提があります	必ず計画します — 短い計画でもかまいません
「すでにアプローチは決まっています」	そのアプローチがプロジェクトのパターンと衝突する可能性があります	アプローチを文書化し、承認を得ます
「ユーザーは急いでいます」	不適切なコードは、計画されたコードより時間がかかります	計画によって手戻りを防ぎます
「ただのバグ修正です」	バグ修正には根本原因の分析が必要です	パッチだけでなく、修正全体を計画します
「進めながら計画します」	それは計画ではなく、行き当たりばったりです	まず計画し、その後に実行します
一度に 5 つ質問する	ユーザーを圧倒し、曖昧な回答につながります	1 メッセージにつき 1 つ質問します
1 つのアプローチしか提案しない	トレードオフを分析できず、より良い選択肢を見逃す可能性があります	必ず 2～3 つのアプローチを提案します
曖昧なファイル参照	「テストを更新する」— どのテストですか？	必ず正確なファイルパスを記載します
30 分以上かかるタスク	追跡や検証を行うには大きすぎます	2～5 分のタスクに分割します
承認前にコードに着手する	方向性が変わると労力が無駄になります	明示的な「はい」を待ちます

---

合理化を防ぐガード

次の条件を満たすまでは、コードを書いたり、ファイルを作成したり、実装作業に着手したりしてはいけません。 1. 要件を理解するために確認の質問をしている 2. トレードオフを含むアプローチを提案している 3. ユーザーが計画を明示的に承認している

これは、どれほど簡単に思えるタスクであっても、すべてのタスクに適用されます。

鉄則：承認済みの計画なしにコードを書いてはいけません。 例外はありません。「これだけ少し」も、「明白だから」も認められません。

次のように考えたら、すぐに手を止めてください。

• 「ちょっとだけ手早く……」— いいえ。まず計画を立ててください。
• 「完全な計画は必要ない……」— いいえ、必要です。計画は簡潔でもかまいません。
• 「あとで記録しよう……」— いいえ。先に記録してください。

---

サブエージェントへのタスク割り当ての機会

タスクのパターン	割り当て先	タイミング
計画中の独立した調査タスク	subagent_type="Explore" を指定した Agent ツール	複数のコードベース領域から情報を集める場合
アーキテクチャ層をまたぐ計画の検証	planner エージェントをディスパッチする Agent ツール	計画が複数のシステム境界にまたがる場合
計画の承認後、独立した実装タスク	Agent ツール（dispatching-parallel-agents スキルに従い、複数を並列で実行）	計画の手順に依存関係がない場合

ディスパッチする際は、dispatching-parallel-agents スキルのプロトコルに従ってください。

---

連携ポイント

スキル	関係	タイミング
brainstorming	上流 — 設計のコンテキストを提供	ブレインストーミングの後に計画を立てる
task-management	下流 — 承認済みの計画を受け取る	標準的な実行経路
executing-plans	下流 — 計画を直接実行する	単一タスクの実行
subagent-driven-development	下流 — 並列で実行する	独立したタスクが多数ある場合
autonomous-loop	下流 — 反復的に実行する	Ralph 方式のセッション
self-learning	双方向 — 計画に情報を提供し、計画から学ぶ	コンテキストの読み込みとパターンの保存
verification-before-completion	下流 — 計画の完全性を検証する	計画が完了したとする前
task-decomposition	補完 — 複雑な計画の WBS を提供	計画に階層的な分解が必要な場合

---

具体例

例：小規模なバグ修正計画

# Fix: Login button disabled state not clearing

**Goal:** Fix login button remaining disabled after failed login attempt
**Architecture:** State management bug in LoginForm component
**Approach:** Reset `isSubmitting` state in the catch block of handleSubmit

### Task 1: Write failing test
**Files:** Test: `tests/components/LoginForm.test.tsx`
**Steps:** Write test that submits invalid credentials and verifies button re-enables
**Verification:** `npm test -- --grep "re-enables button after failed login"`

### Task 2: Fix the bug
**Files:** Modify: `src/components/LoginForm.tsx`
**Steps:** Add `setIsSubmitting(false)` to catch block in handleSubmit
**Verification:** `npm test -- --grep "LoginForm"` — all pass

例：移行コマンド

計画の承認後：

Plan approved and saved to docs/plans/2026-03-15-login-fix.md.
Invoking task-management skill to begin tracked execution.

---

検証ゲート

計画が完了したとする前に、次の点を確認してください。

1. 確認：計画書が docs/plans/ に存在する
2. 実行：品質チェックリストに照らして、計画の完全性を確認する
3. 読み込み：すべてのセクションに具体的な詳細が記載されていることを確認する
4. 検証：ユーザーが明示的に承認している
5. 宣言：その後に限り、実装へ移行する

---

主要な原則

• DRY — 同じことを繰り返さない
• YAGNI — まだ必要のないものは作らない
• TDD — 該当する場合は、まずテストを書く
• 頻繁なコミット — 各タスクの後に、小さく独立したコミットを行う
• 正確なパス — 計画では常に正確なファイルパスを指定する

---

スキルの種類

RIGID — すべての実装タスクで、このプロセスに厳密に従ってください。各フェーズは順序どおりに進める必要があり、変更できません。承認済みの計画なしにコードを書いてはいけません。