Plan then code

Plan Then Code

いきなり実装を書き始めると、間違った問題を解決するコードができやすい。計画なしで50行書いた後に要件の誤解に気づくのは、着手前に3分間の確認をするより遥かに高コストである。

鉄則（Iron Law）

1. 非自明な変更は必ず Explore → Plan → Code → Commit の順で進める。 「動かしながら考える」は、スコープが一文で言えるほど小さい変更にのみ許される。
2. 計画をスキップしてよいかどうかは「この差分を一文で説明できるか」で判定する。 できないなら計画フェーズを飛ばさない。
3. 曖昧な要件のまま実装に入らない。 疑問点は着手前に解消する。実装セッション中に要件を都度聞き直すのは失敗の兆候。
4. コンテキストは有限資源として扱う。 目的に無関係なファイル読み込みや会話の蓄積は、後続の判断精度を落とす。

作業手順

フェーズ0: 計画が必要かを判定する

• 変更が「typo修正」「ログ追加」「変数リネーム」「既知バグの1行修正」のように、diffの内容を一文で言い切れるか自問する。
• 言い切れる → 計画フェーズを省略し、直接実装してよい。
• 言い切れない、または「たぶんこの辺を直せばよさそう」という手探り状態である → 以下のフェーズへ進む。

フェーズ1: Explore（探索）

1. 変更なしで関連ファイルを読む。実装前にコードベースの前提を壊さない。
2. 疑問点（インターフェース名、既存の呼び出し元、影響範囲）をこの段階で洗い出す。
3. 調査対象は具体的に絞る。「〜を調査して」だけでなく対象ファイル・観点を自分の中で明確にしてから読む（無限探索でコンテキストを溶かさない）。
4. 大きめの機能や、着手前に判断が割れそうな仕様は、ここでユーザーに逆質問する。実装の詳細・UI/UX・エッジケース・スコープ外にする範囲・トレードオフを確認し尽くしてから次へ進む。

フェーズ2: Plan（計画）

1. 探索結果をもとに、実装計画を明文化する。触るファイル・変更の順序・検証方法を含める。
2. 計画には「この機能が動作していることを証明する手段」（テストケース、E2Eの確認手順）を末尾に必ず書く。
3. 計画をユーザーに提示し、承認を得てから実装に入る。大きな機能ほど、ここで手戻りを止める価値が高い。
4. 仕様が固まったら、以後の実装は計画と現在のタスクだけに集中する。計画確定までの試行錯誤の経緯は実装フェーズに持ち込まない。

フェーズ3: Code（実装）

1. 計画に沿って実装する。計画にない構造変更・スコープ拡大はここで行わない（気づいたら別タスクとしてメモする）。
2. 小さく反復する。ひとかたまり実装するたびに、計画と現在の差分を照合する。
3. テストを書き実行し、実行結果を証拠として残す（「動くはず」で終わらせない）。テスト先行で進める場合の書き方は test-driven-development に従う。
4. 早期に軌道修正する。 実装が計画からずれ始めたと感じたら、その場で止めて計画に立ち返る。同じ誤りを2回以上訂正しても直らない場合、それ以上同じ流れを続けるより、学びを反映した具体的な指示で仕切り直す方が速い。

フェーズ4: Commit（確定）

1. 差分が計画で述べた目的に一致しているか最終確認する。
2. 説明的なコミットメッセージを書き、必要ならPRを作成する。
3. 計画とずれた点があれば、なぜずれたかを一言残す（次回の計画精度を上げるため）。

コンテキスト管理の要点

計画・実装を通じて、コンテキストウィンドウは有限のボトルネック資源として扱う。

• 詰め込むほど良いわけではない: 関連度の低い情報が混じるほど判断精度が落ちる（context rot）。目的に直結する最小限の情報だけを持たせる。
• Just-in-Time取得を基本にする: ファイル全体を読む前にまず検索で対象を絞り込む。ディレクトリ構成や命名規則もヒントとして使う。
• 大規模調査は要約だけを持ち帰る: 広範囲の調査が必要なら、要点（1000〜2000トークン程度）だけを主コンテキストに残し、詳細な探索過程は持ち込まない。
• 無関係なタスクを同一セッションに混在させない: 目的が変わったら区切りをつける。無関係な会話やファイル読み込みが蓄積した状態で新しいタスクを始めない。
• 同じ問題を2回以上訂正しても直らないときは仕切り直す: そのセッションは失敗した試行で汚染されているとみなし、学びを反映した具体的な指示で再開する方が、蓄積したまま続けるより速い。
• 長時間タスクでは決定事項を書き残す: 変更したファイル一覧・検証コマンド・未解決issueなど、後で参照する情報は都度メモに残す。圧縮や仕切り直しをまたいでも一貫性を保つため。

チェックリスト

着手前:

• この差分は一文で説明できるか（できるなら計画は省略してよい）
• 要件の曖昧な点はすべて解消したか
• 調査範囲を具体的に絞ったか（無限探索になっていないか）

計画時:

• 触るファイル・変更順序を明文化したか
• 「動作を証明する手段」を計画に含めたか
• ユーザーの承認を得てから実装に入っているか

実装中・完了前:

• 計画にない構造変更やスコープ拡大が紛れ込んでいないか
• 実行結果（テスト・ビルド・出力）を証拠として確認したか
• 計画からずれ始めた時点で早期に軌道修正したか
• 同一問題を2回以上訂正していないか（していれば仕切り直しを検討したか）

アンチパターン集

やりがちな思考	現実
「小さい変更に見えるから計画は省こう」	一文で言い切れない時点でそれは小さくない。手探りのまま書き始めると手戻りが発生する
「とりあえず書いてみて後で直せばいい」	誤った前提のまま進んだ分だけ、後続のコンテキストが失敗した試みで汚染され修正コストが増す
「聞くと手間がかかるから推測で進めよう」	曖昧な要件のまま実装すると、後から仕様と食い違うコードができ手戻りが最大化する
「関連しそうなファイルは全部読んでおこう」	無関係な情報が混じるほど判断精度が落ちる。目的に直結する範囲だけ読む
「同じ指摘を3回目も直せば今度こそ直る」	2回訂正しても直らないのはセッションの汚染が原因であることが多い。仕切り直しの方が速い
「計画通りに進んでいないが、あと少しだから続けよう」	ずれに気づいた時点で止める方が、突き進んでから戻すより総コストが低い

出典

• Anthropic Engineering: Claude Code Best Practices — https://code.claude.com/docs/en/best-practices （"Explore first, then plan, then code", "Let Claude interview you", "Course-correct early and often"）
• Anthropic Engineering: Effective context engineering for AI agents — https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents