Claude Codeを使い始めたけど指示の出し方で結果がブレる実感がある人向け
「バグ直して」「いい感じにして」みたいなふわっとした頼み方をして、的外れな結果が返ってきたり何度も直させたりしている場面で、症状・見るべきファイル・検証手段を最初から盛り込んで指示を立て直したいときに思い出す考え方
Claude Codeに「ログイン機能のバグ直して」と打つと、たいてい的外れな直し方が返ってきます。会員のセッションが切れる話なのに、入力欄の見た目をいじり始めたりする。指示がふわっとしてると、Claudeは「たぶんこういうことだろう」で勝手に走るからです。
Effective Prompting は、その「ブレ」を減らすための指示の出し方をまとめた公式の考え方です。どのファイルを見ろ、どんな条件を守れ、できたかどう確かめろ、をプロンプト（Claudeへの指示文）に最初から書いておく。これだけで、後から何度も直させる手間がごっそり減ります。
公式ガイドはこう言い切っています。「指示が正確であればあるほど、後で直す回数は減る」と。
噛み砕くと
新しく入った職場の同僚に仕事を頼む場面を想像してみてください。「あの件、いい感じにやっといて」だけだと、相手は何を指すのか分からず、見当違いの成果物を持ってくる。料理ブログの開発でも同じことが起きます。
逆に「会員ページの src/auth/ あたりを見て、ログイン30分後に切れる不具合を、まず再現するテストを書いてから直して」と渡せば、相手は迷いません。場所・条件・ゴールが全部入ってるからです。
Effective Prompting はこの「迷わせない頼み方」を3本柱で整理しています。具体的な文脈を与える、素材そのものを渡す、できたか確かめる手段を渡す。とくに3つ目が効きます。
3本柱の中身：とくに「確かめる手段」が効く
公式は具体的な文脈の与え方として、4つのやり方を挙げています。作業の範囲を絞る、答えのありかを指し示す、既存の書き方をお手本に出す、症状を説明する。どれも「ふわっとした頼み方」を「迷わせない頼み方」に変える型です。
素材の渡し方も5つあります。@ でファイルを指す、画像をそのまま貼る、ドキュメントのURLを渡す、データを流し込む、Claude自身に必要な情報を取りに行かせる。「どこそこにこういうコードがある」と言葉で説明するより、現物を渡すほうが速いです。
そして核心が「確かめる手段を渡す」。公式はこれを「あなたができる最も効果の大きい一手」と書いています。テストや期待する出力、スクリーンショットを一緒に渡すと、Claudeが自分で答え合わせしながら進める。これがないと、あなただけが唯一のチェック係になって、間違いのたびに手が止まります。
「料理レシピ投稿サイト」で、ふわっと指示と具体指示を並べてみる
料理レシピを投稿・検索できるブログを作っている前提で進めます。ここで実際に、同じ要望を「ふわっと版」と「具体版」で打ち比べてみます。差が一番出るやつです。
ステップ1: ふわっと指示で頼んでみる
まず会員ログインの不具合を、ありがちな雑な頼み方で投げます。
ログイン機能のバグ直してこれだとClaudeはどのファイルを見ればいいか分からず、ログイン画面まわりを片っ端から読み始めます。会話の記録がどんどん埋まっていって、しかも直したのが本当の原因かどうか誰も確かめられない。
ステップ2: 場所・条件・ゴールを足して具体指示にする
同じ要望に、症状・見るべき場所・「直った状態」を足します。公式の「症状を説明する」型そのままです。
会員ログインがログイン後30分でセッション切れすると失敗する。
src/auth/ の token refresh 周りを見て、まず失敗を再現するテストを
書いてから直して。原因に対処して、エラーを握りつぶさないでこれでClaudeは src/auth/ に直行します。先に「失敗するテスト」を書くので、何が壊れてるか目で見えるようになる。直したあとそのテストが通れば、直った証拠が残ります。
ステップ3: お手本を指し示して新機能を頼む
次はレシピ検索の追加。ここで初心者がやりがちな勘違いがあります。「レシピ検索を追加して」とだけ言うと、Claudeは既存のブログの書き方を無視して、自己流のまったく違う作りで実装してくる。あとで全部直すはめになります。
なので、既にあるお手本を指し示します。公式の「既存の書き方をお手本に出す」型です。
home画面の既存ウィジェットの作り方（例: RecipeCard の実装）を読んで
同じ書き方に合わせて。月別で絞り込めて前後にページ送りできる検索を、
既存で使ってるライブラリだけで作ってステップ4: 公式の原文プロンプトと照らし合わせる
ステップ3は公式の英語サンプルを料理ブログに翻案したものです。一次ソースの原文はこうなっています。
look at how existing widgets are implemented on the home page to
understand the patterns. HotDogWidget.php is a good example. follow
the pattern to implement a new calendar widget that lets the user
select a month and paginate forwards/backwards to pick a year. build
from scratch without libraries other than the ones already used in
the codebase.骨格は同じです。お手本のファイル名を出す、何ができればいいかを具体的に言う、追加で持ち込む道具を縛る。固有名詞をRecipeCardに差し替えただけ。
ステップ5: 検証基準を最初から渡す
レシピ投稿フォームのメール欄を検証する関数を作らせます。ここで「実装して」だけだと、それっぽいけど穴のあるコードが返ってくる。だから合否の例を最初から渡します。
validateEmail 関数を書いて。テスト例: user@example.com は true、
invalid は false、user@.com は false。実装したらテストを実行してこれで「user@.com みたいな半端な文字列を弾けてるか」までClaudeが自分で確かめます。あなたが一つ一つ目視する必要がなくなる。
ステップ6: 見た目はスクリーンショットで答え合わせさせる
レシピ一覧の見た目を整えたいとき。「いい感じにして」では何が正解か誰も分かりません。完成イメージの画像を貼って、結果と見比べさせます。
[完成イメージの画像を貼る] このデザインで作って。
できあがりのスクリーンショットを撮って元画像と見比べて、
違うところを一覧にして直してClaudeが自分で撮って比べて直す。これも検証手段を渡すパターンの一つです。
最後に、冒頭で挙げた素材の渡し方の5つ目「データの流し込み」も具体例を出しておきます。ターミナル（文字でコマンドを打つ画面）で cat error.log | claude のように打つと、ファイルの中身を直接Claudeに送れます。| は前のコマンドが出した結果を次のコマンドへ渡す記号です。大量のエラーログを丸ごと一括で渡したいときに便利です。この流し込みだけを掘り下げた項目は、末尾の関連項目に置いています。
つまり Effective Prompting は何をしてくれるのか
- やってくれる: ファイル指定・条件・検証基準を盛り込むと、Claudeが見当違いを減らして自分で答え合わせしながら進む
- やってくれない: 魔法のテンプレを暗記すれば勝手に賢くなる、ではない。何を作りたいかを言葉にするのはあくまであなた側
- 意味が薄い場面: 「このファイル何か改善点ある？」のように、わざとふわっと聞いて気づきを引き出したい探り段階。公式も「軌道修正できる前提なら曖昧な指示も役に立つ」と認めています
使いどころ3シナリオ（料理ブログで再現）
シナリオ1: レシピの保存が時々失敗すると報告が来たとき
「保存できないことがある」だけ受け取って投げると沼ります。症状・起きる場所・直った状態をセットで渡します。「人気レシピを連続で5回保存すると失敗する。データ書き込み周りを見て、まず再現するテストを書いてから直して、原因をつぶして」と。再現テストが残るので、同じ不具合がぶり返したらすぐ気づけます。
シナリオ2: なぜこのコードが変な作りなのか知りたいとき
レシピ並び替えの処理が妙に複雑で、理由が分からない。ここで自分の推測を聞いても意味がない。答えのありかを指し示します。「この並び替え処理の変更履歴をたどって、なぜこの作りになったのか経緯をまとめて」。Claudeが履歴を読んで、いつ・なぜこうなったかを説明してくれます。憶測でなく記録に基づく答えが返る。
シナリオ3: ビルドが通らなくなって作業が止まったとき
「ビルドが失敗する」とだけ言うと、Claudeはエラーを握りつぶす小手先の対処をしがちです。エラー文を丸ごと貼って、根っこを直すよう縛ります。「ビルドがこのエラーで落ちる: [エラー文を貼る]。直してビルドが通るのを確認して。エラーを握りつぶさず、根本原因に対処して」。表面を取り繕うのでなく、本当の原因に手を入れさせます。
初心者が踏みやすい落とし穴
- 「いい感じにして」で頼む。何が正解か決めずに投げると、それっぽいけど中身が動かないものが返り、結局あなたが全部チェックする羽目になります。
- 検証基準を渡し忘れる。テストや期待する出力がないと、Claudeは「合ってるか」を自己判断できません。公式いわく、これを渡すのが最も効果の大きい一手です。
- お手本を指さない。既存の書き方に合わせてほしいなら、見るべきファイルを名指しする。指さないと自己流で作られて、後から書き直しになります。
- 場所をぼかす。「どこかにあるバグ」ではなく「src/auth/ 周り」と当たりをつけて渡す。ぼかすとClaudeが大量のファイルを読み込んで、会話の記録がムダに膨らみます。
- 言葉で説明しすぎる。「あのファイルにこういうコードがあって」と書くより、
@でファイルそのものを指したほうが正確で速いです。 - エラーを握りつぶす対処で満足する。「とりあえず動けばいい」で頼むと表面だけ直る。「根本原因に対処して」と一言足すだけで、ぶり返しが減ります。
- 具体的に書けば常に良いと思い込む。探り段階では、わざとふわっと「ここ何か改善できる？」と聞いたほうが、自分では思いつかなかった指摘が出てきます。場面しだいです。
書き方
（コマンドではなく頼み方の型）
症状はこう + このファイルを見て + できたかこう確かめて、を1つの指示にまとめるやってみるとこうなる
入力
会員ログインがログイン後30分でセッション切れすると失敗する。src/auth/ の token refresh 周りを見て、まず失敗を再現するテストを書いてから直して。原因に対処して、エラーを握りつぶさないで出力例
Claudeが src/auth/ に直行し、先に失敗するテストを書いて不具合を目に見える形にしてから修正。直したあとそのテストが通ることで「直った証拠」が残る。場所をぼかした頼み方と違い、関係ないファイルを大量に読み込まずに済むこのページに出てきた言葉
- プロンプト
- AIへの指示文のこと。「これをやって」と打ち込む文章そのもの
- 検証基準
- 「この入力ならこの結果になるはず」という合否の目安。テスト例や期待する出力、完成イメージの画像など。これを渡すとClaudeが自分で答え合わせできる
- テスト
- 「この入力ならこの結果になるはず」を機械的に確かめる小さなプログラム
- token refresh
- ログイン状態を保つ合言葉を期限切れ前に自動更新する仕組み。失敗するとログイン中なのに突然はじき出される
- ビルド
- 書いたコードを実際に動く形のアプリやサイトに組み立てる工程。失敗するとサイトが立ち上がらない
- ライブラリ
- よく使う機能をまとめた他人作の部品集。一から作らずこれを呼び出すと開発が速くなる
- @（アットマーク）
- Claude Codeの指示文で <code>@ファイル名</code> と書くと、その中身を説明せずそのままClaudeに読ませられる書き方