この記事の対象読者
- AIコーディングエージェントを使い始めた人
- 「原因調べて」と投げたら、少し怪しい回答が返ってきたことがある人
- ログ調査をAIに手伝ってもらいたい人
本題に入る前に
この話は、AIコーディングエージェントに不具合調査やログ調査を手伝ってもらう人を想定しています。調査範囲や出力形式をうまく伝えたい開発担当者に向けた内容です。
最近、AIコーディングエージェントに調査を手伝ってもらう場面が増えています。コードを横断して読んだり、ログから怪しい箇所を整理したりするには便利です。一方で、何を見てよいかを伝えないまま依頼すると、期待と違う方向に進むこともあります。
たとえば、予約が反映されない、通知が届かない、管理画面の数字が合わない、みたいな相談を受けたとします。急いでいるとつい「原因調べて」と投げたくなりますよね。。でもAIにとっては、どのログを見てよいのか、どこまでコードを触ってよいのかが分からない状態です。
業務の調査では、触ってよい範囲、見てよいログ、修正してよいかどうかを最初にそろえる必要があります。これは人に頼むときもAIに頼むときも同じです。この記事では、AIに丸投げせず、調査の下書きを作ってもらうための依頼文を考えます。
AIに渡す前に調査範囲をそろえる
不具合調査では、ログを探す、関係ありそうなコードを読む、時系列を整理する、追加で確認することを洗い出す、といった作業があります。
慣れている人なら自然にできますが、慣れないうちは「どこから見ればいいのか」だけで止まりがちです。AIコーディングエージェントは、こうした調査の入口を一緒に整理してくれる相棒として使えます。
ただし、AIは事情を勝手に知っているわけではありません。雑に「原因調べて」とだけ渡すと、見てよい範囲も、やってよい作業も、出してほしい粒度も分からないまま動いてしまいます。
先輩に調査をお願いするときも、「対象ユーザーはこの人です」「この時間帯です」「まだ修正はしないでください」と伝えますよね。AIにも同じように、前提と制約を渡す必要があります。
この記事では、AIに答えを丸投げする方法ではなく、調査メモの下書きを作ってもらうための頼み方を考えます。
AIツールにはいろいろありますが、この記事ではCodexのPromptingなど、コーディングエージェント全般に使える考え方として書きます。特定ツールの魔法の呪文ではなく、先輩や同僚に調査を頼むときと同じように、前提をそろえることが大事です。
悪いプロンプト例
予約同期が反映されないらしい。原因調べて。
これだけだと、AIは何を見てよいのか分かりません。
ログを見ていいのか、コードを触っていいのか、推測だけで答えていいのかも曖昧です。
良いプロンプト例
架空の問い合わせ調査を手伝ってください。
事象:
- ユーザーから「予約同期が反映されない」と問い合わせがありました。
- 対象時刻は 2026-07-01 10:00〜10:30 です。
- 対象ユーザーIDは user_001 です。
見てよいもの:
- ローカルに置いたサンプルログ
- 関連する同期処理のコード
してほしいこと:
- 事実としてログから分かること
- 推測にすぎないこと
- 追加で確認したいこと
を分けてください。
制約:
- コード修正はまだしないでください。
- 実在する会社名や社内情報は出さないでください。
出力形式:
1. 調査結果の要約
2. 根拠になったログ
3. 可能性のある原因
4. 次に人間が確認すること
入れておくとよい項目
プロンプトには、次の項目を入れると調査が進めやすくなります。
| 項目 | 例 |
|---|---|
| 事象 | 何が起きているか |
| 対象範囲 | ユーザーID、時刻、操作 |
| 見てよいもの | ログ、コード、ドキュメント |
| 禁止事項 | 修正しない、外部送信しない |
| 出力形式 | 事実、推測、次の確認 |
AIの回答を見るとき
AIがそれっぽい原因を言ってきても、すぐ信じないほうがよいです。
特に次を確認します。
- ログに実際に書いてある事実か
- コード上の根拠があるか
- 推測を断定していないか
- 再現条件が説明されているか
- 次に人間が確認できる形になっているか
AIは調査の相棒としては便利ですが、最終判断は人間がログやコードで裏取りします。
調査メモはレビューしてから使う
AIが作った調査メモは便利ですが、そのまま結論として扱うのは危ないです。
特に、問い合わせ対応中にきれいな文章が出てくると、少し安心してしまいますよね。でも業務では「それっぽい説明」よりも、「ログで確認できた事実」と「まだ推測のこと」を分けるほうがずっと大事です。
AIが書いたものを見るときは、次の観点で確認します。
| 観点 | 見ること |
|---|---|
| 事実 | ログやコードに本当に書いてあるか |
| 推測 | 推測を断定していないか |
| 範囲 | 対象時刻やユーザーが合っているか |
| 再現性 | もう一度確認できる手順か |
| 次の行動 | 人間が何を確認すればよいか |
これはコードレビューに少し似ています。
コードレビューでは「動きそう」だけでなく、意図した仕様を満たしているか、余計な副作用がないかを見ます。AIの調査メモも同じで、文章が自然かどうかより、根拠に戻れるかを見ます。
危ないメモの例
AIの調査メモで怖いのは、文章として自然なのに根拠が薄いケースです。
原因は外部APIのタイムアウトです。
これだけだと、どのログを見てそう言っているのか分かりません。実際にはタイムアウトのログが1件出ていただけで、ユーザー影響の原因とはまだ言えないかもしれません。
レビューするときは、次のように直せるかを見ると安全です。
事実:
- requestId=req_001 で EXTERNAL_API_TIMEOUT が出ている
まだ分からないこと:
- そのエラーがユーザーの事象と同じ時刻か
- 同じユーザーの処理が最終的に成功したか
次に確認:
- requestId=req_001 の前後ログを見る
「原因です」ではなく、「原因の可能性があります」「次にここを確認します」と書けているかが大事です。
そのまま共有してよい形にする
AIに調査を手伝ってもらうときは、最初から共有しやすい形で出してもらうのがおすすめです。
事実:
- requestId=req_001 で外部APIタイムアウトが出ている
推測:
- 予約反映遅延の原因である可能性がある
次に確認:
- 同時間帯に同じエラーが他ユーザーでも出ているか
この形なら、人間がログを見直すときも、チームに共有するときも扱いやすいです。
まとめ
AIコーディングエージェントに調査を頼むときは、「何をしてほしいか」だけでなく「何をしてはいけないか」も書くと安定します。
ログ調査では、事実と推測を分けて出してもらい、人間が根拠を確認してから使う。これだけでも、かなり安全にAIを使いやすくなります。