AIが言う原因を疑う順番

Claude Codeが示す原因は、間違いのこともある。対照、環境、成果物の鮮度、測定系の順に疑えば、深追いせずに済む。

エージェントは、原因を自信のある口調で言い切ります。「原因はこれです」と言われ、筋も通っていると、そのまま修正に進みたくなります。けれども編集部の検証環境では、その見立てが外れていたことが何度もありました。外れ方には型があり、疑う順番を決めておくと早く気づけます。この記事は、その順番をまとめたものです。

修正が効かないときに手を止める手順は「同じ修正を3回させない」に書きました。こちらは、手を動かす前に「その原因は本当か」を確かめる話です。

最初に対照を取る

まず確かめるのは、比べる相手があるかどうかです。

ある Web アプリの表示崩れで、「3つの環境で再現したので、アプリのバグです」という見立てをもらいました。3環境で再現したなら確かそうに見えます。ところが、3つとも同じ人の同じブラウザで見ていました。つまり、比べる相手（対照）が0件でした。素のブラウザで開くと正常で、アプリのコードに原因はありませんでした。

「何回再現したか」より先に、「再現しない環境を1つでも見たか」を聞きます。対照が無い再現は、何回重ねても証拠になりません。

次に環境を疑う

アプリのコードを読む前に、環境の側に原因が無いかを切り分けます。手元で踏んだ例を、特定の製品名を外して挙げます。

キーボードのショートカットが全部効かない → 常駐ソフトのグローバルなホットキーが先に横取りしていた
音声が途切れる → 大量のデータ転送とオーディオ機器が、同じ USB のコントローラを共有していた
ビルドが急に落ちる → 開発ツールの更新で、必要な部品が消えていた

どれも、エージェントは最初にアプリのコードを疑いました。コードは目の前にあり、環境は見えないからです。

手元では通るのに CI だけで落ちるときの、環境の差の探し方は「ローカルは通るのにCIで落ちる」に書きました。

成果物の鮮度を疑う

「数日前と挙動が違う」という相談で、エージェントはコードの差分を追い始めました。実際には、コードの変更はゼロでした。古いビルド成果物を使い続けていただけです。

廃止したはずのログが出る、直したはずの表示が戻る。そういうときは、コードを追う前に、動いているものがいつ作られたかを確かめます。編集部では、ビルドや起動のコマンドの前に、作業ディレクトリ・ブランチ・コミットを表示させています。

echo "CWD=$(pwd) BRANCH=$(git branch --show-current) HEAD=$(git rev-parse --short HEAD)"

測定系を疑う

数値がおかしいときは、対象より先に、測り方が同じかを確かめます。

URL の疎通確認を並列16で回したら、多くの URL が「無効」と出たことがあります。直列で試し直すと全件正常でした。原因は、確認する側の DB 接続プールが足りず、待ちの時間切れを「無効」と数えていたことです。対象は壊れておらず、壊れていたのは測る側でした。

手元で、ダミーの URL とダミーの処理で再現しました。対象は全件正常で、プールは4本、取得の待ちは0.2秒までとしています（値はすべて仮のもの）。

並列1: ok=30 invalid=0
並列16: ok=12 invalid=18

対象は何も変えていないのに、並列の数を変えるだけで「無効」が出ます。1回だけの実行で、件数はタイミングで変わりうるので、数字そのものより「並列にすると出る」という形を見てください。

測定系の食い違いは、仮説を積むほど深みにはまります。別の件では、測定値の食い違いの説明を続けて外し、最後には「原理的に不可能だ」という理屈を根拠に、元に戻せない技術選定まで提案されかけました。矛盾に気づいた時点で仮説を足すのをやめ、30行ほどの小さな確認用スクリプトを書いて測り直すほうが早く済みます。

時計と応答の鮮度を疑う

スリープから復帰した直後のマシンで、date が7時間遅れていたことがあります。curl も古い応答を返しました。200 OK で、中身も整合した JSON だったので、見ただけでは気づけません。エージェントはそれを根拠に「新しい通知はありません」と断言しました。

時刻や「最新の状態」が判断の材料になるときは、取り直してから信じます。

「全部」が本当に全部かを疑う

エージェントが「全件を調べました」と言うとき、その全件はどこから来たかを確かめます。

ログの書き出しを「全数17,041行」として集計したことがあります。実際は、直近48分ぶんを保持するだけの窓でした。母集団は、その250倍ありました。API の limit も同じで、「直近の N 件」であって「未読の N 件」ではありません。窓の外に落ちたものは、結果に出てきません。

状態を記録したファイルも、同じ注意が要ります。ファイルに「未投稿」とあっても、それは書かれた時点の宣言で、いまの観測ではありません。ファイルを信じて同じ通知を何度も送り、実際には投稿済みだったことがあります。

AIに頼むときの書き方

公式のベストプラクティスは、症状を伝えるときに、エラーそのものを貼り、根本原因に対処してエラーを握りつぶさないよう頼む例を挙げています。また、Claude が自分の作業を確かめられる手段（テスト、ビルドの終了コード、スクリプトなど）を渡すことを勧めています（出典：https://code.claude.com/docs/en/best-practices 、2026-10-16確認）。

編集部では、これに「疑う順番」を足して頼みます。

原因を断定する前に、次を順に確かめて結果を書くこと。
- 再現しない環境（対照）を1つでも見たか
- 環境側（常駐ソフト、機器、ツールの更新）の可能性を外したか
- 動いている成果物は、いつ・どのコミットから作られたか
- 測る側（並列数、接続数、タイムアウト）は同じ条件か
- 「全件」は、窓や limit で切られていないか

確かめる手段が「テストが緑になること」だけだと、それ自体が何も検査していないこともあります。その見抜き方は「緑のテストは何も証明しない」に書きました。

まとめ

「何回再現したか」より、「再現しない対照を見たか」を先に聞く。
コードの前に、環境を疑う。エージェントは見えるコードを先に疑いがち。
成果物の鮮度は、作業ディレクトリ・ブランチ・コミットの表示で確かめる。
数値がおかしいときは、対象より先に測る側を疑う。
時刻と「最新」は、取り直してから信じる。
「全件」は窓かもしれない。状態ファイルは過去の宣言として読む。