Claude Codeでエラー調査をするときのプロンプト設計

Claude Codeにエラー修正を頼むときは、最初から「直して」と伝えるより、再現条件・観察できた事実・変更してよい範囲・合格条件を分けて渡すと、原因を追いやすくなります。まず調査だけを依頼し、根拠が集まってから最小修正へ進みましょう。Anthropicの公式ワークフローも、再現commandやstack trace、発生手順を共有して原因を絞る流れを案内しています。

最初に渡すのはエラー全文と再現条件

エラー調査で情報が足りなくなりやすいのは、最後の一行だけを貼るケースです。スタックトレースの上部に呼び出し元、下部に失敗した処理が出ていることもあります。省略せず、少なくとも次をまとめます。

• 実行したcommand、操作、URL

• エラー全文とスタックトレース

• 発生日時や頻度（毎回か、特定条件だけか）

• 期待した結果と実際の結果

• OS、言語・runtime、主要なversion

• 直前に変更した内容、再現用の入力

• すでに試したことと、その結果

ただし、logを貼る前にAPI key、cookie、個人情報、顧客データを伏せてください。エラーの識別に必要なfile pathや型名は残し、secret値だけ置換するのが基本です。再現に必要な情報を丸ごと削ると原因を見失うため、<API_KEY>のような説明付きplaceholderへ置き換えます。

「動きません」ではなく、「npm test -- src/auth.test.tsで、空のtokenを渡したケースだけ失敗する。期待値は401、実際はTypeError」と書けば、調査対象が絞れます。再現手順は、他の人がそのまま実行できる程度に具体化してください。AnthropicのCommon Workflowsも、再現command、stack trace、再現手順を伝えるよう案内しています。

調査と修正を別の依頼にする

最初の依頼は、コードを変えずに仮説と根拠を集める形にします。例えば次のように頼みます。

まだファイルは変更しないでください。上記の操作を再現し、失敗箇所までの呼び出し経路を追ってください。原因候補を最大3つに絞り、それぞれについて、根拠となるファイルと行、確認したlogまたはtest、反証になる情報を示してください。再現できなければ、その事実と次に必要な情報を返してください。

候補数を制限するのは説明を短くするためではありません。候補ごとに根拠・不足情報・次に行う確認を書かせ、同じ現象を別の言葉で繰り返すのを防ぐためです。原因候補が複数残るときは、どの観測結果なら候補を切り分けられるかを聞きます。原因が分からないままpatchへ進まず、追加log、環境差、最小再現testのどれが必要かを先に決めてください。

調査結果の後で、根拠と再現条件がそろったら修正を頼みます。Claude Code公式例では、エラーを共有し、具体的な修正案を検討し、その後に適用する流れが示されています。調査と編集を必ず別turnにする必要はありませんが、少なくとも変更前に「まだ編集しない」という境界を明示すると、何が分かってから修正へ進むのかがはっきりします。

使い回せる調査依頼の型

次の枠を埋めると、状況説明が具体的になります。すべてを埋められない場合は「不明」と書き、推測を事実として扱わないようにします。

表は横にスクロールできます

欄	書く内容	例
目的	何ができればよいか	tokenなしなら401を返す
発生条件	どの入力・操作か	POST /api/sessionに空token
実際	観測した結果	500とTypeError
期待	正常な結果	401とエラーJSON
再現方法	command・手順	対象の認証testを実行
制約	変更してよい範囲	public response shapeは維持
完了条件	何を検証するか	再現testと関連testが通る

表の内容はpromptの組み立て例で、実際のエラーを試した記録ではありません。実際のproject名やAPIを自分の環境に置き換えてください。機密を含む値は、再現可能性を残しながら匿名化します。secretをそのまま渡す必要があるか迷ったら、まずは渡さず、何が不足するかを確認します。

根拠が集まったら変更範囲を固定する

原因が絞れた後も、「直して」だけに戻らず、触ってよい範囲と変えてはいけないものを伝えます。

原因は空tokenのvalidation前にdecodeを呼んでいることだと確認できました。既存のAPI response shapeとerror handlingを確認し、validationをdecodeより前に置く最小変更を提案してください。public API、dependency、無関係なformatには触れないでください。変更後は再現testと関連test、必要なtypecheckを実行し、実行できなかった確認も理由とともに列挙してください。

これは依頼の例で、特定repositoryの実装やAPIを示していません。「依存追加禁止」「外部APIを呼ばない」「既存schema維持」のような条件は、必要に応じて加えます。既存contractとの整合が分からないなら、AIに補完させず、利用箇所や仕様の調査を先に依頼します。

複数案がある場合は、変更範囲、失敗時の影響、戻しやすさを比べてから決めます。特にdata migration、permission、外部serviceへの副作用がある場合は、実行前に止まる条件を明記してください。プロンプトに書かなかった広い権限を与えたことにはなりません。Claude Codeの操作権限や確認動作は、surfaceや組織設定によって異なるため、特定の確認画面が常に出る前提にしないでください。

まずは使ってみる

記事の文脈に合うToolへ進めます。報酬の有無で見た目は変えていません。

• 

  Claude Code

  公式サイトを見るTool詳細を見る比較を見る

調査結果は証拠と推測を分けて読む

AIの説明は、コードに書かれた事実と原因の推定を分けて確認します。「この関数で例外が発生した」はstack traceで確かめられる事実ですが、「前回のrefactorが原因」は履歴比較がなければ仮説です。報告に以下の区分があると判断しやすくなります。

• 観測事実：実行したcommand、出力、再現の有無

• コード上の根拠：file、function、条件分岐、呼び出し関係

• 仮説：事実から考えた原因と、断定できない部分

• 未確認：実行環境がなく調べられなかったこと

• 次の確認：どのtestやlogで確定できるか

出力の自信の強さではなく、再現と反証可能な根拠を評価します。testが通ったことも、すべての環境で直った証明ではありません。変更が関係するroute、input、permissionなど、境界条件を見ます。

合格条件は修正前に決めておく

「エラーが消える」だけだと、例外を握りつぶしたり、処理自体を飛ばしたpatchも通ってしまいます。変更前に成功条件・失敗条件・副作用を決めてください。

表は横にスクロールできます

チェック	例	合格の見方
再現test	空tokenを送る	500ではなく契約どおりの401
正常系	有効tokenを送る	既存の成功結果を維持
境界値	null、空文字、形式不正	意図したerror response
回帰	関連API / unit test	既存挙動が壊れていない
diff	変更fileと周辺	原因に関係する変更だけ
実行記録	commandとexit code	実行したものだけ完了扱い

testが存在しない場合は、最低限の再現testか手動確認の手順を決めます。実行できないtestを「PASS」と書かせず、未実行・環境不足として残すことが大切です。testと同時に期待値を変えた場合は、仕様に沿った変更かも確認します。

調査が長引くときの切り分け

一度の修正で直らない場合、同じ依頼を強く繰り返すより、失敗条件を一つずつ分離します。例えばローカルでは再現するがCIではしない場合、runtime version、環境変数、timezone、file system、並列実行を比較します。特定dataだけで発生するなら、そのdata shapeだけに絞ったfixtureを作ります。

logが不足している場合は原因を断定せず、「次の一回で何を記録すれば候補を分けられるか」を設計します。productionで再現する問題は、個人情報やsecretを含むlogを無造作に複製しないでください。必要な項目だけ匿名化して共有します。

変更を取り消す必要がある場合も、force resetや大量削除をいきなり指示しません。working tree、未保存の変更、戻し方を確認し、復元できない操作を説明させます。履歴を消す・遠隔へ書くといった操作は、通常の修正と同じ許可で実行できるとは限りません。

AIものさしの判断

エラー解析promptの質は、長さや「原因を説明して」と書いたかでは決まりません。調査開始時に再現条件と観測事実が十分か、調査と変更の境界があるか、終了条件がtestで確かめられるかを見ます。

まず調査だけで原因と根拠をそろえ、確定後に変更範囲を指定する。修正後は同じ再現条件と正常系・境界値を確認し、できたことと未確認を分ける。この順なら、症状を隠すpatchや不要な広範囲変更を見つけやすくなります。

検索者がすぐ使える最小形は「再現手順 / 実際と期待 / まだ変更しない調査 / 根拠fileと仮説 / 変更制約 / 合格条件」です。riskが小さく原因も明快なケースでは一度の依頼で調査・修正を続けても構いません。原因不明、広範囲変更、data損失のおそれがある場合は、調査を先に分けてください。