「OAuth 認証を一式追加して」「この古いライブラリから新しいライブラリに移行して」── そういう大きな仕事を、最初のプロンプトに丸ごと書いて流すと、たいてい思ったように進まない。本章では、そうした仕事を扱うための推奨ワークフローと、セッションをどこで区切るかを扱う。

大きいまま渡すと何が起きるか

「OAuth を実装して」とだけ送ると、Claude は思いついた経路で動き出す。途中まで進んでから「こっちのアプローチの方が良いな」と方針を変えたり、想定と違うファイルを触り始めたりする。

このとき起きていることは:

  • コンテキストが急速に膨らむ ─ 関連しそうなファイルを次々読み込み、枠を埋める
  • 見当違いに気づくのが遅れる ─ Claude は出力を続けるので、こちらが止めるタイミングがズレる
  • 修正ループの温床になる ─ 「ここ違う、こう直して」と何往復も重ね、文脈はさらに散らかる

基礎で扱った /compact /clear は応急処置にはなるが、そもそも一回のターンで扱う仕事の大きさが間違っているケースが多い。先に手を付けるべきは「分け方」である。

推奨ワークフロー: 探索 → 計画 → 実装 → コミット

公式が推奨するのは、四つのフェーズに分けて進めるやり方である。

1. 探索

まず何が関係しているかを Claude に読ませるフェーズ。Plan Mode に入って、質問で状況を確認する。

/plan
src/auth 配下を読んで、現在のセッション管理とログインの流れを教えてほしい。
あと、シークレットの環境変数管理がどうなっているかも知りたい。

ここでは編集はさせない。「コードベースの土地勘」を作る段階である。

2. 計画

土地勘ができたら、具体的な実装計画を作らせる。

Google OAuth を追加したい。どのファイルを変える必要がある?
セッションの流れはどうなる? 計画を作ってほしい。

Plan Mode のまま、Claude が文章で計画を書く。ここで Ctrl+G を押すとエディタが開いて計画を直接編集できる。Claude が書いた計画に「この部分は別のアプローチで」と手を入れてから承認する、というやり方が有効である。

3. 実装

計画が固まったら Plan Mode を抜けて、コーディングを開始する。承認時に「どのモードで進めるか」を選べる ── 各編集を手動レビュー (慎重)、acceptEdits で自動承認 (中速)、auto モードで一気に進める (高速、要件あり)。

実装時に重要なのは、計画に照らして検証させること。

計画通りに OAuth フローを実装してほしい。
コールバックハンドラのテストも書いて、テストスイートを通して、失敗があれば直して。

「テストを通す」のような検証目標を一緒に渡すと、Claude が自分で失敗を検出して直す ─ 実装の品質が安定しやすくなる。検証の話は後の章で詳しく扱う。

4. コミット

実装が一段落したら、コミットメッセージと PR を Claude に任せる。

説明的なメッセージでコミットして、PR を開いて。

ここまでがひと続きのワークフロー。

フェーズの間で区切るか

四つのフェーズをひとつのセッションで通すこともできるし、フェーズごとに /clear で区切ることもできる。判断軸はコンテキストの重さである。

  • 探索で大量にファイルを読み、計画で長い文章を書いた後そのまま実装に入ると、コンテキストはかなり埋まっている
  • このとき /clear で切ると、計画という「成果物」が引き継がれない問題がある
  • 解決策: 計画を SPEC.md のようなファイルに書き出してから /clear、新しいセッションで @SPEC.md を読ませて実装させる

公式ベストプラクティスでも、より大きな機能では「仕様を書き出して、新しいセッションで実装する」流れが推奨されている。新しいセッションはクリーンなコンテキストを持ち、実装に集中できる。

一回のセッションが扱える粒度

「どこまでなら一つのセッションでやれるか」の感覚は、使っていくうちに掴んでくる類のものだが、初期の目安として:

  • 触るファイルが片手で数えられる (5〜6 個まで)
  • 触る概念がひとつのまとまり (認証、ロギング、単一の API、など)
  • 依存関係が浅い (「これを直すとあれも、それも…」が少ない)

これを越えそうな時は、フェーズ単位で区切るか、機能単位でさらに分割するかを検討する。Plan Mode で計画を書かせた段階で「これは大きすぎる」と分かることも多い ─ そのとき計画を二回に分けて実装する前提に組み直すのが、後で詰まらない。

ここまでで「大きな仕事の進め方」の骨格を見てきた。次章では、その中でプロンプト自体の質をどう上げるか、具体的なテクニックを扱う。

参考情報