「たまに起きる」「さっきは動いた」──その手の話は、だいたい不具合そのものより先に、話の組み立てが崩れている。Claude Code で詰まるのもそこだ。再現しないまま雑に修正へ飛ぶと、原因と対処がズレる。不具合切り分けと再現性確認を先に固めるだけで、勘違いはかなり減る。
Claude Code は、曖昧な状況説明をそのまま飲み込むと、もっともらしい修正案を出してくる。そこに人間側の思い込みが乗ると、別の場所を直して終わりだ。だから最初にやるべきは「直すこと」ではなく、「再現する条件を削ること」になる。
たとえば、こんな頼み方が効く。
この不具合を再現したいです。まず修正はしないでください。
次の情報を整理してください。
- どの操作で起きるか
- 毎回起きるのか、たまに起きるのか
- 何が起きたように見えるか
- 直前に変えたファイルや設定は何か
- 再現手順を1つずつ最小化するならどこまで絞れるか
必要なら、再現確認用のチェックリストを作ってください。
この頼み方のいいところは、Claude Code を「修理係」ではなく「切り分け係」として使える点だ。いきなりコードを書かせるより、まず観測点を並べさせたほうが、後戻りが減る。
実務では、次の順で聞くとまとまりやすい。
不具合の再現性確認を手伝ってください。
以下の観点で、調査の順番を提案してください。
1. まず試すべき最小の再現手順
2. 環境差を疑うべき点
3. 直前の変更で疑うべき点
4. ログや出力で見るべき箇所
5. 再現しない場合に記録しておくべき情報
断定は避けて、切り分けのための仮説として並べてください。
ここで大事なのは、「原因を当てろ」と言わないことだ。原因当てをやると、Claude Code も人間も飛ぶ。再現しない不具合は、原因の特定より先に「どの条件で消えるか」を押さえたほうが強い。消える条件が分かれば、逆算で狭められる。
筆者も昔、似た話で手戻りしたことがある。表面上はファイル保存の不具合に見えたのに、実際は入力データの文字コード差が混ざっていた。最初は保存処理だけを見ていて、そこそこ大きい差分を作った。けれど再現手順を1段ずつ削っていくと、保存前の取り込み段階で既に壊れていたと分かった。あのとき「再現するかどうか」を先に確認していれば、無駄な修正はかなり減っていたはずだ。
Claude Code に切り分けを頼むときは、情報の出し方も工夫したほうがいい。長文で全部を投げるより、観測できた事実を分けて渡す。
事実だけを書きます。
- 起きる操作: 画像を1枚追加して保存
- 起きない操作: 文字だけの文書を保存
- 発生頻度: 毎回ではない
- 直前の変更: 画像の圧縮処理を追加した
- 見える症状: 保存後に一覧から消えることがある
この情報から、再現条件を狭めるための質問を5つ作ってください。
この「事実だけ」という一言が効く。推測を混ぜたまま話すと、会話の途中で前提がぐちゃぐちゃになる。たとえば「たぶん保存が悪い」と決めつけていると、実際には一覧更新の問題でも保存側ばかり見てしまう。勘違いは、だいたいその瞬間に入る。
再現しないケースでは、Claude Code に「再現用メモ」を作らせるのも有効だ。口頭で曖昧に覚えておくより、再現条件を固定したほうが次に繋がる。
以下の形式で、不具合の再現メモを作ってください。
- 現象:
- 再現手順:
- 再現しやすい条件:
- 再現しにくい条件:
- 直前の変更:
- 確認したこと:
- 未確認のこと:
事実と推測を分けて書いてください。
このメモがあると、別の日に見直したときの「なんとなく怪しい」が減る。人間の記憶は雑だ。昨日の確信は、今日の思い込みに変わる。Claude Code に整理させるのは、そのぶれを抑えるためでもある。
ただし、やってはいけないこともある。再現しないのに、いきなり広範囲の修正を許すことだ。差分が大きいほど、どこで直ったのか分からなくなる。筆者はこれで何度か痛い目を見た。保存まわりの1行だけ直すつもりが、ついでに周辺のリファクタまで入れてしまい、翌日「直ったのはどれだ」と自分で迷子になった。再現性確認が曖昧なまま差分を増やすのは、かなり危ない。
だから、修正を頼むとしても段階を踏む。
まずは修正しないで、再現条件を整理してください。
そのうえで、最小修正案を1つだけ出してください。
大きなリファクタリングは不要です。
この「最小」が重要だ。再現しない不具合は、1回で全部直そうとすると崩れる。最小修正に絞れば、検証もしやすい。戻すのも楽になる。
非エンジニアの用途でも考え方は同じだ。たとえば、フォルダ整理や重複ファイルの削除で「消えたり消えなかったりする」ように見えるとき、いきなり全削除を走らせるのは危ない。まずは対象を小さくして、1フォルダだけで再現するかを見る。
このフォルダ整理の作業で、削除はまだしないでください。
まず次を確認したいです。
- どの種類のファイルが対象か
- どの条件で重複と判断するか
- 1フォルダだけで試した場合の確認手順
- 元に戻せる形で試す方法
安全側の進め方にしてください。
文書作成でも同じだ。テンプレを当てたら一部だけ崩れる、という話は珍しくない。そんなときも、本文全体を直す前に、崩れる段落を1つ抜き出して再現を確認すればいい。
この文書の崩れを再現したいです。
全文ではなく、問題が出る段落だけを取り出して、原因候補を整理してください。
そのうえで、再現確認しやすい短いサンプル文も作ってください。
再現しない不具合を切り分けるコツは、派手な推理をしないことだ。代わりに、事実、条件、差分、この3つを冷たく並べる。Claude Code はその整理に向いている。逆に、曖昧な感覚のまま「たぶんこれで」と進めると、勘違いが増えるだけだ。
最後に覚えておくといいのは、再現しないこと自体が情報だという点だ。どの条件で出ず、どの条件で出るか。そこを詰めるほど、修正は細くなる。細くなった修正は、だいたい当たりやすい。広く当てに行くより、ずっと強い。