Claude Code プランモード入門｜「動くけど違う」を減らす3ステップ

この記事でわかること

• 「動くけど求めたものと違う」コードが返ってくる、本当の原因
• プランモードで「探索 → 計画 → 実装」に分ける具体的な手順
• Claude Code が自分で合否を判定できる「完了条件」の書き方
• テストがないプロジェクトで、何を検証手段にすればいいか
• 大きめの機能を任せる前に、仕様を作らせる進め方

インストールは済んで、依頼を投げれば何かは返ってくる。ただ、返ってきたものが 自分の意図とずれていることが多い ―― この記事はそこを抜けるための話です。

1. なぜ「動くけど違うもの」が出てくるのか

Claude Code を数日使うと、多くの人が同じ壁に当たります。

• 依頼したものは動く。でも求めていたものとは違う
• 途中で関係ないファイルまで書き換えられていた
• 出来上がりを毎回自分で開いて確認していて、それが一番時間を食っている

こうなったとき、たいていは「プロンプトの書き方が悪いのだろう」と考えます。それで 表現を変えたり、指示を長くしたりする。ただ、原因はそこではないことが多いです。

コード補完ではなく、「実行者」に仕事を渡している

Claude Code は入力を補ってくれるツールではありません。ファイルを読み、ターミナルの コマンドを実行し、コードを書き換えるところまで自分で進めます。こうしたツールは 一般に「エージェント型」と呼ばれます。

この違いは、依頼の仕方に直接影響します。補完ツールなら、出てきた候補を人間がその場で 見て採否を決められます。実行者に渡す場合はそうはいきません。人間が見ていない間に 判断が積み重なり、気づいたときには方向がずれています。

Claude Code そのものが何をするツールなのかは、Claude Codeとは？ で整理しています。まだ導入していない場合は、先にそちらを読んでください。

足りないのは、プロンプトの巧さではなく「範囲」と「完了条件」

人に仕事を頼むときのことを考えてみます。新しく入った人に「認証まわりを直しておいて」 とだけ伝えたら、どうなるでしょうか。おそらく、関係しそうなコードを片っ端から 読み始めます。そして「直った」と言える基準がわからないまま、何かを提出してきます。

足りていないのは能力ではありません。**どこまでを見ればいいのか（範囲）**と、 **何ができたら終わりなのか（完了条件）**の2つです。

Claude Code でも同じです。この記事で扱うのは、この2つを渡す方法だけです。

2. 範囲を決める：探索 → 計画 → 実装に分ける

いきなり「実装して」と頼むのが、いちばん手戻りを生みます。書かせる前に、 読ませる段階と計画させる段階を挟みます。

このとき使うのがプランモード（Plan Mode）です。プランモードの間、Claude Code は ファイルを読んだり調べたりはしますが、書き換えは行いません。安全に現状を把握させる ための状態です。

探索：読み取り専用にして、現状を読ませる

プランモードに入るには、入力欄で Shift+Tab を押します。押すたびにモードが 切り替わるので、画面の表示がプランモードになっているのを確認してください。 最初からこの状態で起動したい場合は、次のように立ち上げます。

claude --permission-mode plan

この状態で、まず読ませます。ポイントは、範囲を自分で指定することです。

@src/auth 以下を読んで、このプロジェクトがログインとセッションを
どう処理しているか説明してください。
あわせて、環境変数で秘密情報をどう管理しているかも確認してください。

@ に続けてファイルやディレクトリを指定すると、そのファイルを直接読ませられます。 「プロジェクト全体を見て」と頼むのとは、結果がかなり変わります。

探させれば探した分だけ、余計な読み込みが積み上がります。ファイルを名指しすれば、 Claude Code は探す往復を飛ばして本題に入れます。この差は /context で使用量を 見比べれば、自分の手元でも確認できます。

実装の依頼でなくても構いません。「この関数は何をしているか」「この処理はどこから 呼ばれているか」を聞くだけでも、プランモードは使えます。

計画：変更するファイルとリスクを、先に出させる

現状を把握させたら、次に計画を出させます。実装させる前に、頭の中を見せてもらう 段階です。

Google OAuth によるログインを追加したいです。
どのファイルを変更する必要がありますか。
処理の流れはどうなりますか。想定されるリスクも挙げてください。
まず計画だけ出してください。

出てきた計画は、そのまま受け入れる必要はありません。むしろ、ここで直すのが いちばん安く済みます。

• 対象ファイルに、触ってほしくないものが入っていないか
• 既存の処理と重複する実装をしようとしていないか
• 自分が想定していた方針と違わないか

違っていれば、その場で伝えて直させます。「認証部分は既存の AuthService を 使ってください」のように、具体的に指定するほうが早いです。

実装：計画に沿って実行させ、検証で締める

計画に納得できたら、プランモードを抜けて実装させます。

その計画に沿って OAuth の処理を実装してください。
コールバック処理のテストも書いて、テストを実行し、
失敗しているものは修正してください。

最後の一文が重要です。これが次の章で扱う「完了条件」です。ここを省くと、探索と計画を きちんとやっても、結局は人間が出来上がりを確認する作業に戻ります。

実行中に方向がずれていることに気づいたら、Esc でいつでも止められます。止めてから 計画に戻ったほうが、走り切らせてから直すより早く済みます。

計画を省いていい変更、省くと痛い変更

毎回3ステップを踏む必要はありません。判断の目安はこうです。

プランモードの価値は、慣れないコードや方針が固まっていない作業にあります。 一文で頼めることに使うと、単に手間が増えるだけです。

計画は、ファイルに残す

見落としやすい点があります。会話を仕切り直すと、計画も一緒に消えます。

Claude Code はセッションが長くなるほど、それまでのやり取り全体を毎回読み直します。 そのため、別の作業に移るタイミングでは /clear で仕切り直します。ただ、そのとき せっかく作った計画も消えてしまいます。

そこで、計画は会話の中に置いたままにせず、ファイルに書き出させます。

いまの計画を PLAN.md に書き出してください。
変更対象のファイル、処理の流れ、確認手順の順でまとめてください。

こうしておけば、/clear した後に @PLAN.md と渡すだけで再開できます。長い作業を 何日かに分けるときにも効きます。

セッションが重くなる仕組みと、/clear や /context の使い分けは Claude Code コマンド整理術で詳しく扱っています。

3. 完了条件を渡す：Claude Code が自分で合否を判定できる形にする

Claude Code が「終わった」と判断する基準は、何も指定しなければ「できたように 見えるかどうか」です。自動で実行できる確認手段がなければ、合否を判定するのは 人間しかいません。つまり、自分が検証係になります。

これを変える方法は1つです。依頼の中に、Claude Code 自身が実行できる確認手段を 入れておくことです。

伝わらない依頼と、伝わる依頼

同じ内容でも、書き方でここまで変わります。

右列に共通しているのは、期待する結果が具体的に書かれていて、それを確かめる手順が 最後にあることです。長い文章を書く必要はありません。確認手段の一文があるかどうかです。

検証手段は「合否が返るもの」なら何でもいい

「検証」と聞くとテストを思い浮かべますが、そこに限る必要はありません。実行すると 成功か失敗が返るものなら、何でも使えます。

自分のプロジェクトで確実に動くものを1つ選んで、それを毎回の依頼の末尾に付けます。 まずはこれだけで十分です。

テストがないプロジェクトではどうするか

現実には、テストが整っていないプロジェクトのほうが多いはずです。その場合の順番は こうなります。

1. すでにあるものを使う。 ビルド、型チェック、lint のどれかは動くことが多いです。 これらは「壊れていないこと」の確認としては十分に機能します。
2. 手で確かめている手順を、そのまま渡す。 「ローカルで起動して、この画面を開いて、 ログインできることを確認してください」でも、確認手段として成立します。
3. テストを1本だけ書かせる。 今回触る範囲に限って書かせます。 「この関数のテストだけ先に書いてください」と頼めば、以降の依頼で使い回せます。

最初から網羅的なテストを整える必要はありません。今回の変更が正しいかを判定できる 最小の1つがあればいい、という考え方です。

「エラーを消す」ではなく「原因を直す」と書き添える

確認手段を渡すと、別の問題が出ることがあります。合否だけを見てしまい、テストの 期待値を書き換える、警告を抑制する、例外を握りつぶす、といった形で「通った状態」を 作ってしまうケースです。

これを避けるには、一文足します。

エラーを抑え込むのではなく、原因を直してください。
テストの期待値を変える必要があると判断した場合は、変更前に理由を説明してください。

「原因を直す」という指示と、「勝手に基準を動かさない」という制約の2つが入っている のが要点です。

4. 大きい機能は、実装の前に仕様を作らせる

ここまでは1回の依頼の話でした。数日かかる機能では、実装の前にもう一段階、準備を 挟みます。

要件を投げつけず、質問させる

やりがちなのは、自分の頭にある要件を長文で一気に渡すことです。うまくいかない理由は はっきりしています。渡した時点で、自分が考えていない論点は書かれていないからです。

そこで順番を逆にします。まず質問させます。

[作りたいものを2〜3行で説明]を作りたいです。
実装に入る前に、私に質問してください。
技術的な実装方法、画面と操作の流れ、例外的なケース、
気にしている点、判断が必要なトレードオフについて聞いてください。
答えが明らかな質問は飛ばして、私が見落としていそうな点を掘ってください。
質問が終わったら、内容を SPEC.md にまとめてください。

原記事では、この用途に AskUserQuestion という質問用のツールを名指しする例が 挙げられています。使える環境なら選択肢形式で聞いてくれるので、答えるのが楽になります。 使えない場合でも、上の依頼文だけで一問一答は始まります。

やってみるとわかりますが、だいたい2〜3問目で「そこは決めていなかった」という論点が 出てきます。実装が半分進んだ後にそれが出るより、ここで出たほうが安いです。

使える仕様の3条件

出てきた仕様が使えるかどうかは、次の3点で判断できます。

1. 対象が名前で書かれている。 触るファイル名、関数名、テーブル名が具体的に 挙がっているか。「認証部分」のような書き方で終わっていないか
2. やらないことが書かれている。 範囲の外側が書かれていないと、実装中に広がります
3. 最後に通しの確認手順がある。 「この操作をして、こうなれば完成」が書かれているか

3番目は、第3章の完了条件を仕様のレベルで書いたものです。ここが書けていれば、 実装の各段階でそのまま検証に使えます。

「仕様を書く時間のほうが、実装を見張る時間より安い」というのは原記事の著者の 主張で、数値の裏付けがあるわけではありません。ただ、実装が始まった後の方針変更は 会話をさかのぼってやり直す作業になるので、感覚としては一致します。

仕様を先に決める進め方をより体系的にやるなら、 OpenSpecで仕様駆動開発を始めるも参考になります。

5. 調査はサブエージェントに出して、本体を汚さない

もう1つ、範囲に関わる仕組みがあります。サブエージェントです。

1つの会話の中に、複数の作業場所がある

サブエージェントは、別の作業場所で調べ物をしてくる仕組みです。重要なのは、 サブエージェントが読んだファイルやコマンドの出力は、こちらの会話に流れ込まない ことです。戻ってくるのは結論だけです。

たとえばビルドログの調査をサブエージェントに出したとします。1万行のログを読んだ としても、こちらの会話に入るのは「原因はこの依存の重複です」という数行だけです。 自分で読ませていたら、そのログ全体がその後のやり取りに残り続けます。

調査やログ解析を外に出す

向いているのは、読む量が多くて、結論が短い仕事です。

サブエージェントを使って、このプロジェクトの認証がトークンの更新を
どう処理しているか調べてください。
あわせて、再利用できる OAuth 関連の実装があるかも確認してください。
結果は要点だけ報告してください。

逆に、こちらと相談しながら進めたい作業には向きません。判断の途中経過が こちらに見えないので、方向がずれたときに止められないからです。

書き手と読み手を分ける

もう1つの使い方が、レビューです。実装した本人にレビューさせると、自分の答案を 自分で採点する形になります。実装の過程を見ているぶん、「これは意図通り」と 判断してしまいます。

そこで、レビューは別の作業場所でやらせます。

サブエージェントを使って、いまの変更内容をレビューしてください。
指摘は、動作が正しくない箇所と、依頼した内容を満たしていない箇所に
限ってください。設計の好みの話は不要です。

指摘範囲を絞るのが大事です。制限しないと、動いているコードに対する 「こうも書ける」という指摘が並びます。

環境によっては、レビュー用のコマンドがあらかじめ用意されていることもあります。 自分の環境で使えるかは /help で確認してください。

6. うまくいかないときのチェックリスト

手戻りが増えたときは、だいたい次の5つのどれかです。

「2回でだめなら仕切り直す」という回数は、原記事の著者の経験則です。自分の 作業に合わせて調整してください。判断の基準は回数そのものではなく、 同じ説明を繰り返している状態になっていないかどうかです。

出てきたコマンドの一覧と使い分けは Claude Code Commands完全ガイドにまとめています。

まとめ：今週やることを3つに絞る

ここまでの内容を一度に取り入れる必要はありません。効果が出やすい順に3つです。

1. 一文で説明できない変更の前に、Shift+Tab を押す。 まず読ませて、計画を 出させる。それだけで方向のずれが実装前に見つかります
2. 依頼の最後に、確認手段の一文を足す。 「テストを実行して失敗を修正してください」 でも「ビルドが通ることを確認してください」でも構いません
3. 計画をファイルに残す。 PLAN.md に書き出させておけば、会話を仕切り直しても 続きから進められます

この3つは、どれも「範囲」と「完了条件」を渡すための操作です。Claude Code に必要な のは、うまい言い回しではなく、どこまで見ればよくて、何ができたら終わりなのかの 2つだけです。