Claude Codeのプロンプトが効かない時に試す5つの応用テク

「このコンポーネント、いい感じにリファクタしといて」

そう投げた30分後、Claude Codeは確かにリファクタしてくれていました。命名もきれいだった。ただ、頼んでもいない隣のファイルのimport順まで“ついでに”整えていて、レビューで差分が200行に膨らんでいたんです。

僕は最初、これをモデルのせいにしていました。「指示を勝手に拡大解釈する」と。でも何度もやらかすうちに気づきました。悪いのはモデルじゃなくて、僕の頼み方だったんです。

基礎のコツ（具体性・文脈・出力形式・例示・反復）は別記事の良いプロンプトを書く5つのコツにまとめました。この記事はその先、実務でプロンプトが「効かない」瞬間にだけ刺さる応用テクを5つに絞ります。曖昧さを消す、ファイルで文脈を渡す、段階的に検証させる、出力形式を固定する、失敗から立て直す。全部、僕が事故って覚えたものです。

この記事の要点

• プロンプトの精度は「言葉選び」ではなく「境界の固定」で決まる。触る範囲・触らない範囲を先に書くと差分が暴れない。
• 文脈はチャットに貼るよりファイル名で渡す。「先に〇〇を読んで」が、想像で書くのを止める一番効く一言。
• 一発で全部やらせず、読む→計画→編集→検証→報告の順を指定する。特に「先に計画だけ出して」で事故が激減する。
• 出力形式（差分の出し方、報告の型）を固定すると、レビューが速くなりやり直しが減る。
• 失敗時は同じ指示を投げ直さない。何を試して何がダメだったかを渡して、原因の切り分けから頼む。

Claude Codeがコードベースを読み、ファイルを編集し、コマンドを実行するエージェントである点は公式のClaude Code overviewで確認できます。「文章を返すAI」ではなく「作業をするAI」だからこそ、頼み方の精度がそのまま事故率に直結します。

テク1: 「いい感じ」を消す——曖昧さは具体的な禁止で潰す

一番多い失敗が、評価語をそのまま渡すことです。「いい感じ」「きれいに」「ちゃんと」「最適化して」。人間同士なら通じる言葉ですが、Claude Codeにとっては判定不能の指示です。何をもって“いい感じ”なのか基準がないので、モデルは推測で動きます。推測した瞬間、冒頭の200行事故が起きます。

効くのは、やってほしいことと同じくらいやってほしくないことを書くことです。許可範囲だけだと「他は何をしてもいい」と読まれます。

Before（曖昧で範囲が無い）:

このコンポーネントをいい感じにリファクタして、ついでに見やすくして。

After（基準と境界がある）:

src/components/UserCard.tsx を読みやすくリファクタしてください。

やること:
- 60行を超える関数を、責務ごとに小さく分割する
- props の型に不足があれば補う

触らないこと:
- src/components/UserCard.tsx 以外のファイルは編集しない
- import の並び替えなど、見た目だけの変更はしない
- 公開している props の名前は変えない（呼び出し側が壊れる）

ポイントは「import を並び替えない」のような、一見細かい禁止です。僕の200行事故は、まさにこの一行が無かったから起きました。否定形を足すのは縛りつけるためじゃなく、モデルが“良かれと思って”踏み込む余地を消すためです。広すぎる削除や本番への適用を止める設計は、「全部やって」が禁句な理由にもまとめています。

テク2: 文脈はチャットに貼らず、ファイル名で渡す

「想像で書かれた」と感じたことはありませんか。実在しない関数を呼んだり、すでにあるユーティリティを再発明したり。これはたいてい、Claude Codeに必要な文脈が届いていないせいです。

やりがちなのが、参考コードを丸ごとチャットに貼ること。これは逆効果になりやすい。貼った瞬間に文脈が固定され、最新のファイルとズレますし、長文を貼るほど肝心の指示が埋もれます。

代わりに、ファイル名で「先に読んで」と渡します。Claude Codeは自分でファイルを開けるので、最新の中身を見たうえで作業します。

実装の前に、まず次の順番で読んでください。

1. src/lib/api-client.ts （既存のfetchラッパー。これを必ず使う）
2. src/features/orders/orderList.tsx （似た一覧画面。構成と命名をこれに合わせる）
3. src/types/order.ts （型定義。新しい型を勝手に作らない）

そのうえで、注文詳細画面 src/features/orders/orderDetail.tsx を実装してください。
api-client.ts の関数だけを使い、独自の fetch は書かないでください。

「先に読んで」のひと言が効くのは、想像で書く前に事実を見させるからです。さらに「似た実装を1つだけ参照基準にする」と書くと、文体や構成が既存コードに揃います。逆に参考資料を10個も渡すと、どれを優先すべきか分からず探索だけで時間を溶かします。読む順番と、採用してよい基準を絞るのがコツです。

ちなみに、毎回手で書くのが面倒な「常時守ってほしいこと」（ビルドコマンド、命名規則、禁止領域）は、チャットではなくCLAUDE.mdに置きます。公式のMemoryでも、CLAUDE.mdは毎セッション読み込まれる文脈として説明されています。粒度の決め方はCLAUDE.mdは「何を書かないか」で決まるに分けました。

テク3: 一発で全部やらせず、段階的に検証させる

賢いモデルほど、頼むと一気に最後まで走ろうとします。これが曲者で、途中の前提がズレていると、間違った方向に全力疾走した結果だけが返ってきます。差分を見たときにはもう手遅れ、というやつです。

効くのは、実行する前に一度止める指示です。僕が一番使うのは「先に計画だけ出して。OKと言うまでコードは変えないで」のひと言。これだけで、的外れな大改修が激減しました。

応用すると、作業そのものを段階に割ります。

次の手順で進めてください。各ステップが終わったら一度止まり、僕の「次へ」を待ってください。

ステップ1: 対象ファイルと、影響しそうな呼び出し元を洗い出して一覧で報告（まだ編集しない）
ステップ2: 変更する関数と、変更理由を短く箇条書きで提示（まだ編集しない）
ステップ3: 承認後にスコープ内だけ編集
ステップ4: npm test を実行し、結果（PASS/FAIL）をそのまま貼る
ステップ5: 変更ファイルと残った懸念を報告

「各ステップで止まる」が手間に見えるなら、せめてステップ1だけは必須にしてください。影響範囲の一覧を先に出させるだけで、想定外のファイルが混ざるのを早期に見つけられます。

検証を「できれば」で頼むと、忙しい日に必ず飛ばされます。npm test のように具体的なコマンド名を書き、結果を貼らせる。実行できなかった場合も「何を実行できなかったか」を報告させると、こちらが判断できます。この「自己申告を鵜呑みにしない」考え方はClaude Codeの「できました」を信じないに詳しく書きました。

テク4: 出力形式を固定して、レビューを速くする

同じ作業でも、報告のされ方がバラバラだとレビューが遅くなります。「だいたいできました、たぶん大丈夫です」みたいな返事は、結局こちらが全部確認し直すことになる。

出力形式を先に渡すと、毎回同じ粒度で返ってきます。レビューが「型に沿って読むだけ」になり、見落としも減ります。

作業後、必ず次の形式だけで報告してください。前置きや感想は不要です。

## 変更したファイル
- （パスを列挙）

## 変更内容（1ファイル1行）
- path: 何を、なぜ変えたか

## 実行したコマンドと結果
- コマンド → PASS / FAIL（FAILなら該当ログ末尾を5行）

## 確認できていないこと
- （手で見るべき箇所、実行できなかった検証）

コードレビューを頼むときは、出力形式がさらに大事です。「全体的に見て」だと感想文が返ってきます。致命度・ファイル名・行番号・修正案を必ず含む表で出させると、実務のレビューに近づきます。

指定する項目	書く理由
致命度（高/中/低）	直す順番を決められる
ファイル名と行番号	どこの話か即座に追える
再現条件	本当に問題か検証できる
修正案	「指摘だけ」で終わらせない

「セキュリティ・データ破壊・公開APIの変更・テスト不足を優先して」のように観点を指定すると、薄い指摘の羅列ではなく、効くレビューになります。

テク5: 失敗したら、同じ指示を投げ直さない

ここが一番もったいないポイントです。Claude Codeの出力がイマイチだったとき、つい同じプロンプトをもう一度送りがちです。でも入力がほぼ同じなら、出力もほぼ同じ。永遠に同じ壁に頭をぶつけることになります。

立て直すコツは、今どうなっているかと何がダメかを具体的に渡し、推測ではなく原因の切り分けから頼むことです。

Before（ただの投げ直し）:

うまく動かない。直して。

After（現状と症状を渡して切り分けから頼む）:

さっきの変更後、npm test の orderDetail のテストだけ落ちています。

- 失敗テスト: tests/orderDetail.test.ts の "renders total price"
- エラー: Expected "¥1,200" but received "1200"
- 直近の変更: 価格表示のフォーマット処理

修正の前に、原因の候補を2〜3個、可能性が高い順に説明してください。
そのうえで、いちばん小さい差分で直してください。テストは消さないこと。

「修正の前に原因候補を説明して」を入れると、Claude Codeが見当違いの場所をいじって別の所を壊す、という連鎖を止められます。失敗ログは末尾の1行だけ見て早とちりしがちなので、こちらが症状を整理して渡すほど立て直しが速くなります。

それでも噛み合わないときは、思い切って文脈をリセットします。長い会話を引きずると、過去のズレた前提を引きずったまま直そうとするからです。新しいセッションで、整理した症状と対象ファイルだけを渡し直すほうが、結果的に速いことが多いです。

コピペで使える：プロンプトの「壊れ」を機械チェックする

応用テクを意識しても、急いでいると「触らない範囲」や「検証コマンド」を書き忘れます。そこで、依頼文をファイル（prompt.md）に書く運用にして、投げる前に最低限の項目が入っているかをスクリプトで点検しています。

次のNode.jsスクリプトは、目標・範囲・禁止範囲・検証コマンド・出力形式が揃っているかを確認します。依存なしでそのまま動きます。

// check-prompt.mjs — 依頼文の抜けを投げる前に検出する
// 使い方: node check-prompt.mjs prompt.md
import { readFileSync } from "node:fs";

const file = process.argv[2] || "prompt.md";
const text = readFileSync(file, "utf8");

// 「これが無いと事故る」最低条件をルール化
const checks = [
  { ok: /(目標|ゴール|Goal)/i.test(text), msg: "目標（何を達成するか）が無い" },
  { ok: /(対象|範囲|Scope|編集してよい)/i.test(text), msg: "触ってよい範囲の指定が無い" },
  { ok: /(触らない|編集しない|変えない|do not)/i.test(text), msg: "触らない範囲（禁止）が無い" },
  { ok: /(npm |pnpm |yarn |node |test|ビルド|実行)/i.test(text), msg: "検証コマンドが無い" },
  { ok: /(報告|出力形式|フォーマット|形式で)/i.test(text), msg: "出力形式の指定が無い" },
];

const failed = checks.filter((c) => !c.ok);

if (failed.length > 0) {
  console.error(`このまま投げると事故りやすいです（${file}）:`);
  for (const f of failed) console.error(`  - ${f.msg}`);
  process.exit(1);
}

console.log("OK: 主要な項目はそろっています。投げて大丈夫そうです。");

実行はこれだけです。

node check-prompt.mjs prompt.md

たった数十行ですが、僕が記事リライトや機能追加で事故るときは、たいてい「触らない範囲」か「検証コマンド」のどちらかが抜けていました。投げる前にこれを通すだけで、やり直しが目に見えて減ります。よく効いた依頼文の保存・テンプレ化は効いたプロンプトを使い捨てないにまとめました。

よくある質問

Q. プロンプトは長く詳しく書くほど精度が上がりますか？ いいえ。長さより構造です。公式のMemoryでも、長い指示ほど守られにくくなり、具体的で簡潔なほど従われやすいと説明されています。だらだら書くより、目標・範囲・禁止・検証を見出しで区切るほうが効きます。

Q. 「触らないこと」を毎回書くのが面倒です。 毎回の作業で共通する禁止（本番DBを触らない、依存を勝手に増やさない等）はCLAUDE.mdに移します。今回の作業だけの禁止は依頼文に書く、と置き場所を分けると重複が減ります。

Q. 段階的に止めさせると、かえって遅くなりませんか？ 小さく安全な作業なら一気にやらせて構いません。段階分けが効くのは、影響範囲が読めない変更や、複数ファイルに波及する作業です。最低限「先に計画だけ出して」のひと言だけでも入れておくと安全です。

Q. 例（お手本コード）を渡すと、それを丸写しされて困ります。 例と制約を混ぜているのが原因です。「このファイルは“構成と命名”の参考にするだけ。中身の処理はコピーしない」と役割を明記します。お手本にしてほしい点と、守ってほしい境界を分けて書くと意図どおりになります。

Q. CLAUDE.mdに「絶対に〇〇するな」と書けば必ず止まりますか？ 止まりません。CLAUDE.mdは強制ではなく文脈として扱われます。本当に止めたい操作（削除・本番適用など）は、公式が案内するPreToolUseフックで機械的にブロックするのが確実です。

実際に試した結果

冒頭の200行事故のあと、僕はプロンプトの「言い回し」を磨くのをやめました。代わりにやったのは、依頼文の頭に毎回「触らないこと」と「検証コマンド」の2行を足すこと。それだけで、想定外のファイルが混ざる事故がほぼゼロになりました。

一番効いたのは、テク3の「先に計画だけ出して」です。これを口癖にしてから、的外れな大改修に時間を奪われることが激減しました。Claude Codeは賢いぶん全力で走るので、走り出す前に一度立ち止まらせる——この一手間が、結局いちばん速い、というのが今の実感です。

応用テクといっても、やっていることは「曖昧さを消して、境界を固定して、検証させる」だけです。まずは次の作業から、依頼文に「触らないこと」の一行を足すところから試してみてください。繰り返し使う型がたまってきたら、教材・テンプレート一覧も覗いてみてください。