Claude Codeを使い始めた人がつまずく場所は、驚くほど共通しています。そして、その多くはモデルの性能ではなく「仕事の渡し方」に原因があります。裏を返せば、依頼文に一言足すだけで防げるものがほとんどです。
この記事では、使い始めて早い段階で出会いやすい失敗を5つ取り上げ、それぞれを防ぐための依頼文を紹介します。どれも今日からそのまま使えます。
- テストが通った。ただし、テストのほうを書き換えて
落ちているテストを直すように頼むと、「テストが通りました」と報告が返ってくる。ところが差分を見ると、実装ではなくテストの期待値が変わっている。
Claude Codeに悪気があるわけではありません。「テストを通す」というゴールを渡されたら、いちばん近い道はテストを変えることです。その道は、依頼の時点で塞いでおきます。
テストが通るように parseDuration を実装してください。
テストの内容は変更しないでください
修正を頼むたびにこの一文を添えるのが基本です。毎回書くのが面倒なら、CLAUDE.md の禁止事項に「テストの期待値を変えて通さない。実装側を直す」と書いておきます。差分をレビューするときは、テストファイルが変わっていないかを必ず確認してください。
- 存在しないAPIを自信たっぷりに使う
もっともらしいコードができあがり、最初の実行で落ちる。呼んでいる関数やオプションが実在しない、あるいはライブラリの古いバージョンのものだった、というパターンです。
モデルの知識が古かったり、利用者の少ないライブラリで知識が薄かったりすると起きます。対策は「書く前に読ませる」ことと、型チェックを完了条件に入れることです。
node_modules/xxx/README.md を読んでから実装して
完了条件: npm run typecheck と npm test が通る
存在しないAPIは型エラーとして表に出てくるので、Claude Code自身が完了条件を満たそうとする過程で気づいて直します。
- 同じ修正を延々と繰り返す
直す、テストが落ちる、また直す、また落ちる。同じような試行が延々と続きます。
こういうとき、本当の原因は修正している場所の外（実行環境、設定ファイル、テスト自体の誤り）にあることが多いです。あるいは、仮説が切り替わらないまま同じ手を打ち続けています。始める前に、出口を依頼に書いておきます。
3回試して通らなければ、止まって原因の仮説を報告すること
すでにループに入ってしまったら、Escで止めて、状況を整理させます。
これまで試したことと、まだ試していない仮説を列挙して
4. 昨日直させたミスを、今日もまたやる
指摘して直してもらったのに、次の日のセッションで同じことをする。
会話の中で伝えたことは、そのセッションが終われば残らないからです。ルールは一つで、同じ指摘を2回したら CLAUDE.md に書く。その場で頼めば、Claude Code が追記してくれます。
今の指摘をCLAUDE.mdに追記して
/memory コマンドから CLAUDE.md を開いて自分で編集することもできます。
ただし、CLAUDE.md に書いたルールは「守られやすくなる」ものであって、絶対ではありません。フォーマッタの実行や危険なコマンドの禁止のように、機械的に判定できて絶対に守らせたいものは、フックで強制するほうが確実です。
- 「たぶんできました」で終わる
何をもって完了とするかを伝えずに機能追加を頼むと、自信のある報告は返ってきますが、それが正しいかを確かめる手段がありません。
最後まで任せきれる依頼には、目的・制約・完了条件の3つが揃っています。
ユーザーがプロフィールに自己紹介文（最大500文字）を登録できるようにしてください。
制約:
- 既存の GET /api/users/:id のレスポンス形式は変えない（フィールド追加のみ可）
- ORMのマイグレーション機能を使い、手書きSQLは避ける
完了条件:
- npm run typecheck と npm test が通る
- 新しいエンドポイントに対するテストを追加する
- 最後に変更したファイル一覧と要点を報告する
長く見えますが、途中で何度も口を挟まずに済むことを考えれば安い投資です。完了条件が書いてあれば、Claude Code は自分で検証し、通るまで修正を続けます。
うまくいかなかったときの3つの問い
5つの失敗に共通する原因は、「情報不足」「指示の曖昧さ」「安全網の不在」のどれかです。何かがうまくいかなかったときは、次の3つを自問すると原因にたどり着きやすくなります。
Claude Codeが知っておくべきことで、伝えていないことはなかったか（CLAUDE.md、ドキュメント）
依頼に目的・制約・完了条件が揃っていたか
この失敗を検出・防止できる仕組みがあったか（テスト、型、権限、フック、レビュー）
答えが見つかったら、それを会話の中で直すだけでなく、CLAUDE.md や設定に組み込みます。そうすれば同じ失敗は二度と起きず、環境が一段ずつ賢くなっていきます。
おわりに
この記事は、Kindleで出している拙著『Claude Code実践ガイド AIエージェントに開発を任せる技術』の内容をもとに、記事用に書き直したものです。
本では、ここで紹介した失敗パターンの残り（頼んでいない変更、大きすぎる差分、レガシーコードでの迷走など）に加えて、CLAUDE.md の設計と育て方、権限モードと安全対策、スキル、フック、MCP、サブエージェントと並列開発、ヘッドレス実行とCI連携、コスト管理、ゼロからWebアプリを作るケーススタディまでを扱っています。巻末には CLAUDE.md・settings.json・SKILL.md のテンプレートも収録しました。
Kindle Unlimited でも読めます。