AIコーディングエージェントを脱線させない方法: 探索し、計画し、そして作る

Claude CodeやCursorのようなエージェント的コーディングツールを初めて使うとき、人は一行のリクエストを打ち込んで祈りがちだ。うまくいくこともある。だが多くの場合、エージェントは自信満々で間違ったものを作る——尋ねてもいない問題を解決し、予期しないファイルに触れ、実際に重要だったエッジケースを飛ばす。

直し方はより賢いモデルではない。ワークフローだ。まず探索し、次に計画し、それから作る。これはAnthropicが公式のClaude Codeベストプラクティスガイドで推奨するパターンで、編集する前にリポジトリを読めるあらゆるエージェントに同じ発想が当てはまる。

なぜいきなりコードに飛びつくと失敗するのか

AIエージェントは限られたコンテキストウィンドウの中で動く——会話の進行中の記録に加え、読んだすべてのファイルと実行したすべてのコマンドだ。計画を飛ばすと2つのことがうまくいかなくなる。

1. エージェントが意図を推測する。 あなたの心は読めないので、曖昧なプロンプトはもっともらしいが間違った実装を返す。
2. ミスが静かに積み重なる。 いったんエージェントが編集を始めると、ステップ1の誤った前提は、あなたが気づく前にさらに10の変更の下に埋もれる。

考えることとやることを分けると、誤った前提を、まだ直すのが安いうちに——12ファイルの巻き戻しではなく一文の訂正で——捕まえられる。

ステップ1: 読み取り専用モードで探索する

今やほとんどの本格的なエージェントには、読んで分析はできるが何も変更できないモードがある。Claude Codeではプランモードと呼ばれ、エージェントがファイルを読み、編集や状態変更コマンドの実行、コミットをせずに質問に答える読み取り専用の状態だ。

まずはエージェントに、コードを変更するのではなく理解するよう求めよう。

Read /src/auth and explain how we handle sessions and login.
Also look at how we manage environment variables for secrets.

これは共有コンテキストを構築し、修正を任せる前にエージェントが実際にあなたのコードベースを理解しているか確認していることになる。

ステップ2: 計画を求め、それから押し返す

エージェントが探索したら、コードの前に具体的な計画を求めよう。

I want to add Google OAuth login. What files need to change?
What's the session flow? Write a step-by-step plan — don't write code yet.

エージェントは番号付きの計画を返す。どのファイルに触れるか、新しいセッションフロー、トークンをどこに保存するか。さて、最初の草案を受け入れてはいけない。ここが軌道修正の最も安い瞬間だ。穴を突こう。

• 「OAuthコールバックが途中で失敗したらどうなる?」
• 「src/auth/tokens.tsにすでにrefreshTokenヘルパーがある——新しく書く代わりにそれを再利用して。」
• 「これはログインフローだけに留めて。既存のパスワードリセットのコードには触れないで。」

ここで計画を数分練ることが、後で間違った実装をほどく1時間を節約する。

ステップ3: 検証する手段を持って作る

ここでようやくエージェントにコードを書かせる——そして自分の仕事をチェックする手段を与える。どんなプロンプトにも加えられる最も強力なひとつの要素は、エージェントが自分で実行できる検証ステップだ。

Implement the OAuth flow from your plan. Write a test for the callback
handler covering the failure case, run the test suite, and fix any failures.

実行できるチェック——テスト、ビルド、比較用のスクリーンショット——がなければ、「できたように見える」がエージェントの持つ唯一のシグナルになり、あなたがすべてのミスのエラー検出器になる。チェックがあれば、ループは自律的に閉じる。エージェントは書き、テストを実行し、結果を読み、通るまで反復する。成功を主張するだけでなく、実際のテスト出力を見せるよう求めよう。

ステップ4: 計画を飛ばすべきときを知る

計画にはオーバーヘッドがあり、常に見合うわけではない。変更が小さく、スコープが明白なら——タイポの修正、ログ行の追加、変数のリネーム——エージェントに直接やらせればいい。Anthropicのガイドからの良い経験則: 差分を一文で説明できるなら、計画を飛ばせ。 探索・計画・構築のサイクルは、複数ファイルにまたがる仕事、自信のないアプローチを使う仕事、よく知らないコードに触れる仕事のために取っておこう。

セーフティネット: 早く軌道修正し、チェックポイントを使う

良い計画があっても、エージェントは漂流する。2つの習慣で主導権を保てる。

• 脱線した瞬間に割り込む。 間違ったアプローチをエージェントが完了するのを待ってはいけない。Claude Codeでは、Escがコンテキストを保ったまま動作の途中で停止させ、軌道修正できる。
• チェックポイントで自由に実験する。 Claude Codeは各変更の前にファイルのスナップショットを取るので、エージェントにリスクのあることを試させ、うまくいかなければ巻き戻して（Esc Escまたは/rewind）別のアプローチを試せる。（チェックポイントはエージェント自身の編集を追跡し、外部プロセスは追跡しない——便利機能であり、gitの代わりではない。）

そして、同じミスを2回より多く訂正している自分に気づいたら、コンテキストはおそらく失敗した試みで汚染されている。クリアして、今学んだことを織り込んだ鋭いプロンプトで再スタートしよう——より良いプロンプトでのクリーンなセッションは、行き止まりだらけの長いセッションにほぼ常に勝る。

まとめ

探索、計画、構築、検証。最初のタスクでは遅く感じ、2つ目までに元が取れる。自信満々で間違ったコードを受け取るのをやめ、あなたが実際に意図したものを作るエージェントを得始める。