記事

Claude Codeでやりがちな悪い依頼文と改善例：曖昧／丸投げ／検証なしを避ける7パターン

Claude Codeで失敗しやすい依頼文を7パターン（曖昧・丸投げ・無検証・無参照・症状だけ・kitchen sink・修正ループ）に分類し、それぞれに公式Best Practicesに沿った改善例を対比表で提示します。投げる前の30秒チェックリスト付き。

結論：失敗するプロンプトは「曖昧・丸投げ・検証なし」の組み合わせで起きる

Claude Codeで「思ったとおりに動いてくれない」「途中で迷走する」と感じる依頼文は、ほぼ次の3要素のいずれかが欠けています。

具体性（どのファイルか／何のシナリオか）
完了条件（どう確認できれば終わりか）
検証手段（テスト・スクリーンショット・期待出力）

公式のBest Practicesも冒頭で**「Include tests, screenshots, or expected outputs so Claude can check itself. This is the single highest-leverage thing you can do.」**と書いており、Claude自身が自分の仕事を検証できる材料を渡せるかが品質の最大の分岐点です。

本記事では、よくある悪い依頼文を7パターンに分けて、それぞれに改善例を対比で示します。依頼文の全体構造（目的・背景・制約・出力・完了条件・禁止事項）はClaude Codeに伝わるプロンプトの基本構造、完了条件の書き分けは成功率を上げる制約条件と受け入れ条件の作り方で扱っているので、本記事は**「投げる前の30秒で踏みやすい地雷」**に絞ります。情報は2026年5月1日時点の公式ドキュメントに沿って整理しました。

パターン1：「いい感じに」系の曖昧依頼

最も多い失敗です。

❌ 悪い例	✅ 改善例
ダッシュボードをいい感じにして	`[スクリーンショット添付] このデザインを実装して。実装後にスクリーンショットを撮り、元画像と差分を列挙して直して`
ログインのバグを直して	`セッションタイムアウト後にログインが失敗するという報告が出ています。`src/auth/`、特にトークン更新処理を確認してください。再現する失敗テストを先に書いて、それを通すように修正してください`
メールバリデーションを書いて	`validateEmail関数を書いて。サンプルテスト：user@example.com → true、invalid → false、user@.com → false。実装後にテストを実行して`

「いい感じ」「ちゃんと」「最適に」のような形容詞は人間にしか伝わらない指示です。Claudeは「いま選んだ実装が『いい感じ』であるか」を判定する基準を持たないため、合理的に見える適当な実装を返します。目に見える比較対象（スクリーンショット、テスト、期待出力）を必ず添えてください。

パターン2：「全部やって」系の丸投げ

大きすぎる単一依頼は、計画フェーズが省略されて間違った問題を全力で解く事故につながります。

❌ 悪い例	✅ 改善例
認証システムをOAuthに移行して	`Plan Modeで`src/auth`のセッション管理と環境変数の扱いを読んで。Google OAuthを追加するための変更ファイル一覧と、セッションフローを計画として出して`
全テストを通して	`失敗しているテストを1つだけ`npm test — foo.test.ts`で確認。エラー文を貼り、再現する最小修正を計画してから実装して`

Best Practicesは**「Explore first, then plan, then code」として、Explore → Plan → Implement → Commitの4フェーズを推奨しています。大タスクはPlan Modeで計画を出させてから**実装に進めるのが鉄則です。詳しい分解方法は大きな開発タスクをClaude Codeに渡す前の分解方法を参照してください。

パターン3：検証手段がない依頼

公式が**「単一の最大レバレッジ」と書いた論点です。Claudeが自分の仕事を確認するための材料**がないと、「もっともらしいが動かない」コードが返ってきます。

❌ 悪い例	✅ 改善例
ビルドが落ちている。直して	`ビルドが落ちます。エラー文：[貼り付け]。直してビルド成功を確認して。症状ではなく根本原因を直して`
ボタンをクリック可能にして	`ボタンが反応しません。Playwrightで`[data-testid=submit]`をクリック→成功トーストが出ることを確かめるE2Eを先に書いて、通るように直して`
パフォーマンスを改善して	“/api/list`のp95を800ms以下にしたい。`autocannon`で計測コマンドを使い、修正前後の数値を出して比較して`

検証手段はテスト、リンター、Bashコマンド、ブラウザ自動化など何でも構いません。**「Invest in making your verification rock-solid.」**と公式が書いているとおり、検証部分の整備に時間を使うほど、本体実装は速くなります。

パターン4：参照を渡さない依頼

Claudeはあなたのコードを最初から完全には知りません。「リポジトリの規約に合わせて」だけでは推測になります。

❌ 悪い例	✅ 改善例
カレンダーウィジェットを追加して	`ホームの既存ウィジェットの実装パターンを確認して。`HotDogWidget.php`が良い例。同じパターンで月選択と前後の年送りができるカレンダーウィジェットを、依存追加なしで作って`
ExecutionFactoryのAPIが変。なぜ？	`@src/lib/ExecutionFactory.tsのgit historyを見て、現在のAPIになった経緯を要約して`
なんかコード規約に沿わせて	`@CLAUDE.mdと@.eslintrc.jsを見て、命名・import順・コメント方針を要約して。その規約に沿うように直して`

@でファイル参照、画像はドラッグ＆ドロップ、ログはcat error.log | claudeでパイプ流し、と公式が並べているのが効きます。「リポジトリにあるはず」と書く前に、どのファイルにあるかを指で示すのが最短ルートです。

パターン5：症状だけ書く依頼

エラーや不具合の依頼で頻出します。症状・推定箇所・「直った」状態の3点を揃えるだけで、解像度が大きく上がります。

❌ 悪い例	✅ 改善例
落ちる	`本番でNullPointer。スタックトレース：[貼り付け]。`PaymentService.process`の入力検証を疑っています。再現する失敗テストを書いてから直して`
なんか遅い	`/api/searchがp95で2.5秒。`@src/api/search.ts`のN+1を疑っています。クエリログを取って、修正前後でレスポンスタイムを計測して`

「直った」状態をコマンドで検証可能にすると、Claudeは自走しやすくなります。完了条件の書き分けは成功率を上げる制約条件と受け入れ条件の作り方で詳しく扱っています。

パターン6：kitchen sinkセッション

Best Practicesが**「The kitchen sink session.」として明示する失敗パターンです。1セッションに無関係な依頼を混ぜると、過去の文脈で遅くなり、しかも精度が下がります**。

❌ 悪い例	✅ 改善例
ログイン直したついでに、READMEも更新して、CIも見て、あ、依存も上げて	タスクごとに`/clear`して別セッション。または`claude --resume`でセッションを使い分ける
↑のセッションでさらに別の機能を依頼	`/clear`で完全にリセットしてから新しいセッションで投げる

**「Run /clear between unrelated tasks to reset context.」**と公式は明記しています。会話履歴ごと残すと「直前の議論」が次のタスクに干渉します。応答が遅くなる原因にもなります（Claude Codeが遅いときに確認する設定・コンテキスト・ファイル量も参照）。

パターン7：「修正の修正」の連鎖

同じ問題に2回以上修正指示を出している時点で、コンテキストは失敗の試行錯誤で汚れている状態です。

公式の対処は明快で、「After two failed corrections, /clear and write a better initial prompt incorporating what you learned.」 と書かれています。学んだ内容を反映した新しい初期依頼を書き直し、/clearで仕切り直す方が、結果的に速く品質が高くなります。

❌ 悪い例	✅ 改善例
いやそうじゃなくて → ちがう、こう → やっぱり違う	2回目の修正後に`/clear`。学んだ前提（NG例・採用しない手法・既存の制約）を盛り込んで初期依頼を書き直す

複雑なリファクタリングや設計判断ではPlan Modeで計画から作り直すほうが確実です。Plan Modeの使い方はClaude Codeに「計画してから実装」させるプロンプト例で扱っています。

投げる前の30秒チェックリスト

依頼文を送信する前に、次の7項目を頭の中で通すと、上記の地雷をほぼ避けられます。

何のファイル／関数を触るかを1行で書いたか（@で参照したか）
完了条件をコマンド・数値・スクリーンショットなど確認可能な形で書いたか
検証手段（テスト／リンター／E2E／コマンド）を依頼に含めたか
症状だけ・形容詞だけになっていないか
このセッションは関連タスクだけか（/clearが必要ではないか）
大きすぎないか（Plan Modeで計画してからにすべきか）
**「いい感じに」「ちゃんと」「最適に」**を消したか

このチェックリスト自体をCLAUDE.mdの末尾に貼っておくと、本人もチームも事故が減ります。CLAUDE.mdの書き方はClaude Codeで最初に作るべきCLAUDE.mdの書き方を参照してください。

まとめ：3要素を埋めるだけで失敗が激減する

7パターンはすべて、**「具体性」「完了条件」「検証手段」**のどれかが欠けていました。逆に言えば、この3要素を毎回意識して埋めるだけで、失敗の大半は事前に防げます。

公式が**「The more precise your instructions, the fewer corrections you’ll need.」**と書いているとおり、修正回数を減らす最良の方法は、最初の指示を磨くことです。仕上がりの品質はもちろん、消費トークンと作業時間にも直接効きます。

次に読むと、依頼文の精度がさらに上がります。