Claude Codeに慣れていないうちは、指示文を短くしがちです。
「直して」 「いい感じにして」 「このアプリ作って」
これでも返事は返ってきます。ただ、返ってくるものが自分の期待とズレることがあります。Claude Codeは、足りない情報をかなり補って動けます。だからこそ、依頼が短いと、作業範囲も、変更してよいファイルも、完了の基準もClaude Code側の推測に寄ります。
tomo短い依頼で困るのは、Claude Codeが何もできないことではありません。むしろ動けてしまうので、あとから「そこまで頼んでいない」となりやすいところです。
この記事では、Claude Codeへの指示文をどう書けばよいかを、初心者向けに整理します。難しいプロンプト技術の話ではありません。目的、対象、作業範囲、やらないこと、完了条件を入れて、Claude Codeの推測を減らすための書き方です。
短い指示ほどClaude Codeは推測する
Claude Codeは、コードを読んで、必要な変更を考えて、ファイルを編集できます。便利です。ただし、そこには「何を正解とするか」を渡す必要があります。
たとえば「READMEをいい感じにして」とだけ頼むと、Claude Codeは次のようなことを推測します。
- READMEの目的
- 読む人
- どこまで詳しくするか
- インストール手順を追加するか
- 既存の文章をどこまで書き換えるか
- 実行コマンドを確認するか
人間同士でも、これだけではズレます。Claude Codeに頼むときも同じです。
「いい感じに直して」がズレやすい理由
「いい感じ」は、書き手の頭の中にはあります。でも、Claude Codeから見ると候補が多すぎます。
バグ修正なのか、見た目の調整なのか、文章の整理なのか、設計の見直しなのか。どれも「直す」に入ります。Claude Codeがよかれと思って広めに動くと、こちらの意図から外れます。
特に初心者のうちは、短い依頼で一気に作らせるより、調査、計画、編集を分けたほうが失敗しにくいです。
まず一文でゴールを書く
最初の一文は、作業のゴールにします。
悪い例です。
この画面を直して。良い例です。
設定画面で保存ボタンを押しても反応が分かりにくいので、
保存できたことがユーザーに伝わるようにUIを修正してください。この時点で、Claude Codeは「保存処理そのもの」ではなく「保存後の見え方」に意識を向けやすくなります。
最初の一文は、作業名ではなく「何がどうなればよいか」で書きます。ここが決まると、後ろに続く条件も書きやすくなります。
指示文に入れる基本セット
Claude Codeへの依頼は、長ければよいわけではありません。ただ、最低限入れたい項目はあります。
次の5つです。
- 目的
- 対象
- 作業範囲
- やらないこと
- 完了条件
この5つを入れるだけで、Claude Codeの返答はかなり扱いやすくなります。
目的を書く
目的は、なぜその作業をするのかです。
ユーザーが入力エラーの理由をすぐ分かるようにしたいです。社内メンバーがローカル環境を迷わず起動できるREADMEにしたいです。目的を書くと、Claude Codeは単なる差し替えではなく、何を優先すべきか判断しやすくなります。
対象を書く
対象は、どこを見るかです。
対象は `src/components/ProfileForm.tsx` と、
関連して必要になる型定義ファイルだけです。ファイル名が分からない場合は、調査から頼みます。
まず、今回の修正に関係しそうなファイルを探してください。
まだ編集はしないでください。初心者ほど、最初からファイル名を正確に指定できないことがあります。その場合は、無理に決め打ちしなくて大丈夫です。先に探してもらえばよいです。
やらないことを書く
やらないことは、地味ですがかなり大事です。
今回はデザイン全体の変更、認証処理の変更、API仕様の変更はしないでください。既存のテストや設定ファイルは、必要がない限り変更しないでください。
変更が必要だと判断した場合は、編集前に理由を説明してください。Claude Codeは、関連していそうな箇所まで直そうとすることがあります。良い面もありますが、初心者のうちは差分が大きいと確認が難しくなります。
完了条件を書く
完了条件は、「どこまでできたら終わりか」です。
完了条件は次の3つです。
- 入力エラー時に、該当項目の下へエラーメッセージが表示される
- エラーがない場合は、今まで通り保存できる
- `npm test` が通る完了条件があると、Claude Codeの報告も読みやすくなります。こちらも確認しやすくなります。
悪い指示を良い指示に直す
ここからは、短い依頼を実際に直してみます。
「動くようにして」を直す
悪い例です。
動くようにして。これだと、どこが壊れているのか、何をもって動くとするのかが分かりません。
良い例です。
ログイン画面でメールアドレスとパスワードを入力して送信すると、
画面が白くなってしまいます。
まず原因を調査してください。
まだファイルは編集しないでください。
確認してほしいことは次の通りです。
- エラーが発生しているファイル
- エラーの原因として考えられる箇所
- 修正する場合に変更が必要そうなファイル
- 先に確認すべきログやコマンド
調査結果を出したあと、修正方針を短く提案してください。最初から修正させず、調査に絞っています。原因が見えてから編集に進めば、余計な変更を減らせます。
「READMEをいい感じにして」を直す
悪い例です。
READMEをいい感じにして。READMEは読み手によって正解が変わります。自分用なのか、社内向けなのか、公開リポジトリ向けなのかで、書く内容が変わります。
良い例です。
社内の開発メンバーが、このリポジトリを初めて触るときに迷わないREADMEへ直してください。
対象は `README.md` です。
まず既存のREADMEと `package.json` を読んで、足りない項目を確認してください。
追加したい内容は次の通りです。
- このプロジェクトの目的
- ローカル起動手順
- よく使うnpm scripts
- 環境変数が必要な場合の説明
- 開発時の注意点
やらないことは次の通りです。
- 実際には存在しないコマンドを書かない
- 推測で環境変数名を作らない
- README以外のファイルを編集しない
編集後に、変更した内容と確認したファイルを報告してください。このくらい書くと、Claude CodeはREADMEを「読み手のための説明」として扱いやすくなります。
「アプリを作って」を直す
悪い例です。
タスク管理アプリを作って。これだと、ログイン、保存、通知、ドラッグ操作、複数人利用、データベースなど、いくらでも広がります。
良い例です。
自分だけがローカルで使う、小さなタスク管理アプリを作りたいです。
最初の版では、次の機能だけで十分です。
- タスクを追加できる
- タスクを一覧で見られる
- タスクを完了済みにできる
- 完了済みタスクを削除できる
今回はログイン、サーバー保存、通知、ドラッグ操作、複数ユーザー対応は不要です。
まず、最小構成の実装計画を出してください。
まだファイル作成や編集はしないでください。
計画には次を含めてください。
- 作成するファイル
- 使う技術
- 画面に置く要素
- ローカルで動かす方法
- 完成後の確認方法新規作成では、いきなり作らせず、計画を先に出してもらうほうが安全です。
調査、計画、編集を分けて頼む
Claude Codeは、調査も計画も編集もできます。だからこそ、1回の依頼に全部入れると、作業が大きくなりすぎます。
初心者のうちは、次のように分けると扱いやすいです。
- 調査だけ
- 計画だけ
- 編集
調査だけ頼む文
調査だけ頼むときは、「編集しない」をはっきり書きます。
この不具合の原因を調査してください。
まだファイルは編集しないでください。
コマンド実行が必要な場合は、実行前に目的を短く説明してください。
状況は次の通りです。
- 画面: ログイン画面
- 起きていること: 送信後に白い画面になる
- 期待すること: エラーがある場合はメッセージを表示し、成功時はダッシュボードへ移動する
- 自分が確認したこと: ブラウザの再読み込みでは直らなかった
出力してほしい内容は次の通りです。
- 原因の候補
- 関係しそうなファイル
- 追加で確認すべきログやコマンド
- 修正する場合の大まかな方針
分からない点は、推測で進めず質問してください。計画だけ頼む文
計画だけ頼むときは、編集禁止に加えて、計画に含める項目を指定します。
次の修正をしたいので、まず実装計画だけを出してください。
まだファイル作成、ファイル編集、コマンド実行はしないでください。
やりたいことは、プロフィール編集画面で保存後に成功メッセージを表示することです。
計画には次を含めてください。
- 読むべきファイル
- 変更が必要そうなファイル
- 変更内容の概要
- 影響しそうな画面や処理
- 実装後の確認方法
- 今回やらないほうがよいこと
計画を出したあと、私が承認するまで実装に進まないでください。承認を挟むと、差分が大きくなる前に止められます。
編集を頼む文
編集を頼むときは、すでに決めた範囲を再度書きます。
先ほどの計画で進めてください。
今回編集してよいファイルは次の範囲です。
- `src/pages/ProfileEdit.tsx`
- `src/components/Toast.tsx`
- 必要な場合のみ、関連する型定義ファイル
やらないことは次の通りです。
- 認証処理は変更しない
- APIのエンドポイントは変更しない
- 画面全体のデザインを作り替えない
- 新しいライブラリは追加しない
完了条件は次の通りです。
- 保存成功後に成功メッセージが表示される
- 保存失敗時の既存エラー表示は壊れない
- 既存の入力項目の動きは変わらない
作業後に、変更したファイル、確認した内容、残っている不安点を報告してください。
tomo「さっきの計画で」だけだと、会話が長くなったときにズレることがあります。編集してよい範囲と、やらないことはもう一度書いておくと安心です。
そのまま貼れる基本テンプレート
ここからは、実際に貼って使える依頼文です。角括弧の中だけ、自分の内容に置き換えてください。
調査だけのテンプレート
[起きている問題] について原因を調査してください。
まだファイルは編集しないでください。
削除、移動、設定変更、パッケージ追加も行わないでください。
状況は次の通りです。
- 何をしたか: [例: ログインフォームで送信ボタンを押した]
- 起きたこと: [例: 画面が白くなった]
- 期待すること: [例: ログイン成功時はダッシュボードへ移動する]
- 自分が確認したこと: [例: ブラウザを再読み込みしても変わらなかった]
- 関係しそうなファイル: [分かれば書く。分からなければ「不明」でよい]
調査で見てほしいことは次の通りです。
- 原因の候補
- 関係しそうなファイル
- 修正が必要そうな箇所
- 追加で確認すべきログやコマンド
- いま分かっていないこと
コマンド実行が必要な場合は、実行前に目的を説明してください。
調査結果を出したあと、まだ実装には進まないでください。調査依頼では、「まだ編集しない」を最初と最後に入れています。しつこいようですが、ここは大事です。
計画だけのテンプレート
[やりたい変更] を進めたいです。
まず実装計画だけを出してください。
まだファイル作成、ファイル編集、削除、移動、コマンド実行はしないでください。
目的は次の通りです。
- [例: ユーザーが保存できたことを画面上で分かるようにする]
対象は次の範囲です。
- 画面: [例: プロフィール編集画面]
- 関係しそうなファイル: [例: `src/pages/ProfileEdit.tsx`。不明なら「調査して候補を出す」]
- 変更してよい範囲: [例: UI表示とメッセージ表示だけ]
やらないことは次の通りです。
- [例: API仕様は変えない]
- [例: 認証処理は触らない]
- [例: 新しいライブラリは追加しない]
計画には次を含めてください。
- 読むべきファイル
- 変更が必要そうなファイル
- 具体的な変更内容
- 影響が出そうな箇所
- 実装後の確認方法
- 不明点や、先に私へ確認したいこと
計画を出したあと、私が承認するまで実装に進まないでください。計画は、Claude Codeに自由に考えさせる場所です。ただし、作業開始の許可とは分けます。
小さな修正を頼むテンプレート
次の小さな修正を実装してください。
目的:
[例: 入力エラー時に、どの項目が問題なのかユーザーが分かるようにする]
対象:
[例: `src/components/SignupForm.tsx`]
変更してよい範囲:
- [例: フォームのエラー表示]
- [例: 必要な場合のみ、同じ画面で使っている型定義]
やらないこと:
- [例: API呼び出しの処理は変更しない]
- [例: バリデーションルール自体は変更しない]
- [例: 新しいライブラリは追加しない]
- [例: 関係のない整形変更はしない]
完了条件:
- [例: 必須項目が空のとき、該当項目の下にエラーが出る]
- [例: エラーがない場合、既存の送信処理がそのまま動く]
- [例: 既存の見た目から大きく変わらない]
作業後に、次を報告してください。
- 変更したファイル
- 変更内容
- 確認したこと
- 確認できていないこと小さな修正では、完了条件を具体的にします。「直った」の判断をClaude Code任せにしないためです。
新規作成を頼むテンプレート
Claude Codeで新しい小さなツールを作りたいです。
まず計画を出し、問題がなければその後に実装してください。
作りたいもの:
[例: Markdown本文を貼ると、文字数、見出し数、コードブロック数を数える小さなWebツール]
使う人:
[例: 自分だけ。社内共有はまだしない]
使う場面:
[例: ブログ記事を公開する前に、本文の量をざっくり確認したい]
最初の版で必要な機能:
- [例: テキストを貼り付ける入力欄]
- [例: 文字数を表示する]
- [例: H2とH3の数を表示する]
- [例: コードブロック数を表示する]
- [例: 入力内容をクリアするボタン]
今回は入れない機能:
- 保存機能
- ログイン
- サーバー連携
- データベース
- 外部API
- 複雑なデザイン
- スマホ専用の作り込み
技術スタック:
[例: まずは `index.html` だけで動く形にする。npmやビルド環境は使わない]
作業場所:
[例: 現在のフォルダに新規作成する。既存ファイルがある場合は上書きせず、先に確認する]
最初に出してほしい計画:
- 作成するファイル
- 画面に置く要素
- 処理の流れ
- 完成後の確認方法
- 今回あえて入れないもの
計画に問題がなければ、そのまま実装に進んでください。
既存ファイルの上書き、削除、外部パッケージの追加が必要になった場合は、実装前に止まって確認してください。
作業後に報告してほしいこと:
- 作成したファイル
- ブラウザで開く方法
- 動作確認した内容
- 次に機能追加するなら触る場所このテンプレートは長めです。新規作成は、短い依頼ほど広がりやすいので、最初から境界線を書いておきます。
指示文を書いた後に見ること
依頼文を書いたら、送る前に少しだけ見直します。
1回で頼みすぎていないか見る
次の言葉がたくさん入っていたら、1回の依頼として大きいかもしれません。
- 認証
- データベース
- 管理画面
- 通知
- 決済
- 外部API
- テスト
- デプロイ
- リファクタリング
もちろん必要なときはあります。ただ、初心者が最初から全部入れると、差分の確認が難しくなります。
「ついでに」追加したものほど、あとから確認が苦しくなります。最初の依頼では、なくても困らないものを削るほうが進めやすいです。
Claude Codeが返した計画を削る
Claude Codeが出した計画が大きいときは、そのまま承認しないでください。
たとえば、最初は入力画面だけ欲しいのに、計画にログイン、履歴保存、CSV出力、ダークモードまで入っていたら削ります。
計画が初回版としては大きいです。
今回は、入力画面と結果表示だけに絞ってください。
次のものは外してください。
- ログイン
- 保存機能
- CSV出力
- ダークモード
- テスト追加
ファイル数も最小限にして、計画を出し直してください。
まだ実装には進まないでください。Claude Codeの計画は、最初の答えが完成形ではありません。人間が削って、扱える大きさに戻してから進めます。
指示文は作業の幅を決める道具
Claude Codeへの指示文は、きれいな文章である必要はありません。
大事なのは、次の5つです。
- 何のためにやるか
- どこを対象にするか
- どこまでやるか
- 何をやらないか
- 何ができたら完了か
短い依頼でも動くことはあります。でも、作業がズレたときに直すほうが大変です。最初に少しだけ具体的に書くと、Claude Codeの返事も、差分も、確認作業も扱いやすくなります。
迷ったら、まず調査だけ。次に計画だけ。最後に編集。
この順番にすると、Claude Codeに任せるところと、自分が判断するところを分けやすくなります。
