Claude Code活用 #3 原因がわからなかったエラーが、ここまでクリアに分かった

「なぜか特定の操作だけ失敗する」――原因がつかめないエラーは、調査に時間が溶けがちです。今回、弊社が保守を担当している業務システムでまさにそういうエラーが起きたのですが、Claude Code に調査を任せたところ、原因がここまでクリアに分かりました。コードを書く道具としてだけでなく「原因調査の相棒」としての Claude Code の実力が伝わる一例として、実際の流れをご紹介します。

起きていたこと

お客様から、こんな問い合わせがありました。

• ある PDF を契約書に添付しようとすると「作成エラー」になる
• そのファイルを削除しようとしてもエラーになり、操作が戻せない

「特定の操作だけ失敗する」「削除すらできない」という、原因が見えにくいタイプの不具合です。本来ならエンジニアがログを追い、コードを読み、ファイルの中身を調べて……と、どこに原因があるのか見当がつくまでに半日仕事になってもおかしくありません。

Claude Code にやってもらった調査

ここで Claude Code に調査を任せました。最初は何が原因かまったく見えていませんでしたが、やってくれた次の3ステップで、もやもやした不具合が一本の筋道としてクリアになっていきました。

1. ソースコードを読んで「どこで落ちるか」を特定

まず関連するコードを読み、添付・削除・保存のどの操作でも最後に必ず「全ファイルを1つの PDF に結合する処理」が走ることを突き止めました。つまり壊れたファイルが1枚混ざっているだけで、何をしても結合処理でエラーになる、という構造が見えてきます。

2. 本番ログと突き合わせて「推測ではなく事実」で裏取り

ここが地味に重要でした。Claude Code は仮説で止めず、本番環境のログを照合して「問題のファイルを持つ契約だけが落ち、持たない契約は正常に完了している」ことを確認します。心当たりベースの推測ではなく、ログという事実で裏を取ってくれるので、結論の確度が一気に上がります。

3. 正常な PDF と問題の PDF を解析して根本原因を断定

最後に、エラーになる元の PDF と、いったん印刷し直した PDF を qpdf や pdfinfo といったコマンドで構造比較してもらいました。すると決定的な違いが見つかります。

問題の PDF は AES-256 で暗号化（コピー・編集制限）されていたのです。システムが PDF 結合に使っているライブラリがこの暗号化を復号できず、暗号化されたままのデータをうまく読み込めずにエラーで処理が止まる――これが根本原因でした。「印刷して PDF として保存し直すと直る」のも、その操作で暗号化が外れるから、と理屈まできれいに説明がつきました。

調査で Claude Code が効く理由

今回の流れを振り返ると、Claude Code が調査で強い理由がよく分かります。

• コード・ログ・ファイルの中身を横断して一気に追える：ふだんは別々のツールを行き来する作業を、ひとつの対話の中でつないでくれる
• 推測で終わらせず裏を取る：ログや実ファイルで仮説を検証してから結論を出す
• 原因だけでなく対処まで出してくれる：その場の回避策（印刷し直す）と、再発させないための恒久対応（暗号化したファイルを配布しない／システム側で弾く）まで提案してくれる

以前は「PDF のメタデータが悪さをしているようです」程度しか言えなかったエラーが、終わってみれば「PDF の暗号化が結合ライブラリと相性が悪い」と一文で説明できるところまでクリアになりました。コードを書く相棒としてはもちろん、「何が起きているのか分からない」を解きほぐす調査の相棒としても、Claude Code はとても頼りになります。原因不明のエラーに時間を溶かしている方は、一度デバッグ用途で試してみてください。

なお、本シリーズの過去回もあわせてどうぞ。#1 増えるMarkdownを mo でブラウザプレビューする／#2 セキュリティ試験まで AI に任せる。