AIエージェントに「原因調査だけ」を任せる依頼テンプレート

結論: 「診断」と「修正」を別の依頼にする

AIエージェントに不具合を調べてもらうとき、最初から「直して」と頼む必要はありません。第1段階を原因調査だけに限定し、再現条件・観測事実・原因候補・反証・影響範囲を報告させてから、第2段階で修正を承認する方が安全です。

OpenAIのCodexベストプラクティスは、依頼に目標、関連する文脈、制約、完了条件を含めることを勧めています。またAnthropicのClaude Codeベストプラクティスも、探索・計画・実装を分け、テストや期待出力で検証可能にすることを重視しています。製品は違っても、診断依頼の要点は共通です。

この記事は、Codex、Claude Codeなどのコーディングエージェントへ、変更を伴わない原因調査を依頼したい開発者向けです。特定ツールのコマンド集ではなく、どのリポジトリでも使える依頼文と受け入れ基準に絞ります。

なぜ「調査し、そのまま修正」が危ないのか

不具合調査は、観測と推論を何度も往復します。ところが「原因を調べて直して」という1文だけでは、エージェントは最初に見つけた怪しい箇所を変更し、その変更後の状態を証拠として扱うことがあります。これでは、元の症状が本当に再現したのか、修正が原因に効いたのか、たまたま症状が隠れたのかを分けられません。

特に次の状況では、診断と修正を分離する価値が高くなります。

• 未コミットの作業があり、勝手な整形や設定変更を避けたい
• 本番障害で、ログや外部サービスの状態が時間とともに変わる
• セキュリティ、課金、データ消失に関係する
• 原因候補がアプリ、ネットワーク、認証、CIなど複数層にまたがる
• 修正権限を持つ人と、調査を依頼する人が異なる

GitHubのデバッグ用カスタム指示例も、まず一貫して再現し、エラーメッセージを読み、入出力を追い、変更は一度に1つずつ試す流れを示しています。大事なのは、AIに長く考えさせることではなく、何を証拠として残すかを先に決めることです。

そのまま使える原因調査プロンプト

次のテンプレートをコピーし、角括弧の部分を置き換えて使えます。長く見えますが、重要なのは「変更禁止」「調べる範囲」「成果物」「停止条件」の4点です。

次の不具合について、原因調査だけをしてください。修正はまだしません。

## 症状
- 期待する動作: [期待値]
- 実際の動作: [症状]
- 発生条件: [OS、バージョン、入力、操作、頻度]
- 最後に正常だった時点: [分かれば記載]

## 調査範囲
- 優先して読む場所: [ディレクトリ、ログ、関連する設定]
- 実行してよい確認: [テスト、lint、read-onlyコマンド]
- 調査対象外: [本番環境、外部送信、別リポジトリなど]

## 禁止事項
- 製品コード、設定、依存関係、ロックファイルを変更しない
- git add / commit / push / reset / checkoutを行わない
- 本番操作、外部送信、秘密情報の表示を行わない
- エラーを握りつぶす回避策を「原因」としない

## 報告してほしいこと
1. 症状を再現できたか。使った手順と結果
2. 観測した事実。ファイル名、行、ログ、コマンド結果を添える
3. 原因候補を確信度順に最大3件
4. 各候補を支持する証拠と、否定する証拠
5. 最有力原因と、まだ分からない点
6. 影響範囲と、最小の修正案。ここでは実装しない
7. 修正後に必要な回帰テスト

## 停止条件
- 再現できない、権限が足りない、追加情報が必要な場合は推測で変更せず止める
- 書き込みや外部アクセスが必要になったら、目的と対象を示して承認を待つ

単に「読み取り専用で」と書くだけでは、テストがキャッシュ、スナップショット、ビルド成果物を書き換える場合があります。書き込みを完全に避けたいなら、実行可能なコマンドも限定してください。反対に、一時的な再現テストを許可するなら、tmpなどの書き込み先と後片付けの方法を明示します。

良い診断報告の受け入れ基準

診断の品質は、原因名がもっともらしいかではなく、第三者が追試できるかで判断します。次の7項目を満たすまで、修正フェーズへ移さないのが安全です。

1. 期待値と実測値が分かれている 「動かない」ではなく、入力、期待した出力、実際の出力が並んでいる。
2. 再現性が書かれている 何回中何回起きたか、再現しなかった条件は何かが分かる。
3. 事実と推測が区別されている ログやコードから確認できる事実と、そこから導いた仮説を混ぜていない。
4. 代替仮説が検討されている 最有力候補だけでなく、ネットワーク、設定、データ、タイミングなど別の説明も確認している。
5. 反証がある 仮説が誤りなら何が観測されるか、その確認結果が書かれている。
6. 影響範囲が限定されている どの入口、利用者、データ、環境に影響し、何には影響しないかが分かる。
7. 修正後の検証方法が具体的である 「テストする」ではなく、実行コマンド、期待結果、回帰対象が示されている。

OpenAIのCodexベストプラクティスは、完了条件としてテスト、期待動作、レビュー方法を提示することを勧めています。AnthropicのClaude Codeベストプラクティスも、テスト、スクリーンショット、期待出力など、エージェント自身が確認できる手段を与えることを重視しています。診断だけの依頼でも、この「検証可能性」が中心です。

失敗しやすい依頼と直し方

「原因を特定して」だけで範囲を決めない

対象が広すぎると、エージェントは大量のファイルやログを読み、重要な証拠が文脈の中に埋もれます。症状が通る入口から始め、関連する2〜3ディレクトリ、直近の変更、失敗したテストへ範囲を絞ります。

原因を1つに決め打ちする

「キャッシュが原因だと思うので調べて」は、確証バイアスを生みます。「キャッシュ説を検証し、成立しない条件も示す。ほかの候補を最大2つ挙げる」と依頼すると、反証を残せます。

調査の途中で“ついで修正”を許す

型エラー、古い依存関係、整形崩れなどを見つけても、今回の症状との因果関係がなければ別課題です。報告書の「関連しない発見」に分け、診断中の差分を増やさないようにします。

再現できていないのに修正案へ進む

再現不能は失敗ではなく、重要な結果です。時刻、アカウント、リージョン、キャッシュ、ネットワーク、データ状態など不足している条件を列挙し、観測を追加する計画へ切り替えます。

診断から修正へ引き継ぐプロンプト

診断報告を確認し、原因と変更範囲に合意できたら、次の依頼で修正フェーズを開始します。

診断報告のうち、[最有力原因]への修正を承認します。

- 変更してよい範囲: [ファイルまたはディレクトリ]
- 変更してはいけない範囲: [既存作業、設定、本番など]
- 採用する修正方針: [方針]
- 必須の再現テスト: [失敗を再現するテスト]
- 必須の回帰テスト: [既存機能を守るテスト]
- 完了条件: [コマンド、期待結果、差分レビュー]

診断と異なる原因が見つかった場合、範囲を広げず報告して止めてください。

この引き継ぎでは、診断報告そのものをコンテキストに含めます。一方、長い調査でログが大量に蓄積した場合は、報告書をファイルへ保存し、新しいチャットで修正を始める方が明快です。仕様を先に固定する考え方は「仕様駆動でAIエージェントに実装させる方法」、依頼全体の組み立ては「AIエージェントに実装を任せる前の指示テンプレート」も参考になります。

実行前チェックリスト

• 期待する動作と実際の症状を別々に書いた
• OS、バージョン、入力、発生頻度を示した
• 読んでよい範囲と対象外を示した
• 書き込み、Git操作、本番操作、外部送信を禁止した
• 実行してよい確認コマンドを列挙した
• 原因候補ごとに根拠と反証を求めた
• 再現不能や権限不足の停止条件を決めた
• 修正案は求めても、実装は別承認にした
• 報告にファイル位置、ログ、コマンド結果を要求した
• 機密値を表示しないよう明記した

よくある質問

原因調査だけを依頼すると、なぜ安全なのですか？

調査中の仮説を、そのままコード変更へ結び付けないためです。再現条件、証拠、反証、影響範囲を先に確認できるので、誤診による不要な修正や既存の未コミット変更への干渉を減らせます。

ログ追加や再現テストの作成も禁止すべきですか？

既存ファイルを一切変えたくない場合は、どちらも禁止します。一時ファイルや新規テストを許可する場合は、書き込み先、削除方法、実行してよいコマンドを明記し、製品コードの変更とは分けて承認してください。

診断が終わったら同じチャットで修正してよいですか？

小さく明確な不具合なら同じチャットでも構いません。ただし、診断で大量のログやファイルを読んだ場合は、報告書を残して新しいチャットへ修正を引き継ぐ方が、不要な文脈や初期仮説の影響を抑えやすくなります。

まとめ

AIエージェントへ原因調査を任せるときは、「修正しない」という制約だけでなく、何を再現し、何を証拠として残し、どの条件で止まるかまで指定します。診断報告が、再現手順、観測事実、複数仮説、反証、影響範囲、回帰テストを備えていれば、人間は修正権限を渡す前に判断できます。

不具合対応を速くする最短経路は、最初からコードを書かせることとは限りません。診断と修正を2つの成果物に分けることで、余計な差分を減らし、「なぜ直ったのか」を後から説明できる状態を作れます。

次に読む:

• Claude Code/Codexで失敗する5つの理由と回避策
• AIエージェントに実装を任せる前に書くべき指示テンプレート
• 仕様駆動でAIエージェントに実装させる方法
• AIエージェントに秘密情報を読ませない