「壊れてるから直して」で投げると、だいたい遠回りになる。Claude Code みたいなCLIエージェントは、雰囲気で当てるより、再現できる条件を渡したほうがずっと強い。
バグ修正で本当に効くのは、症状の説明を増やすことではない。再現手順を切り分けて、同じ失敗をもう一度起こさせることだ。そこまでできれば、Claude Code はログやコードを追いやすくなるし、修正後の確認まで一気通貫で進められる。逆に、あいまいな「なんか動かない」は、コンテキストを食うだけ食って、外す。筆者も最初はこれで手戻りした。変更箇所を広げすぎて diff が膨らみ、直したいバグより副作用の確認に時間を取られた。あれはだるい。
まずやることは単純だ。Claude Code に「原因を探して」と丸投げする前に、こちらで再現条件を短く固める。たとえばこうだ。
次の不具合を再現してから修正してほしい。
症状:
- ファイル名に日本語が入っていると、出力先のリネームが失敗する
再現手順:
1. sample/ に「議事録 2024-01.txt」を置く
2. そのファイルを対象に変換コマンドを実行する
3. 出力が作られず、エラーも不十分なまま終了する
期待する動作:
- 日本語ファイル名でも処理が通る
- 失敗する場合は理由が分かるメッセージを出す
お願い:
- まず再現して、どの条件で落ちるかを確認してから直してください
- 修正後は同じ手順で再度確認してください
この書き方の肝は、「症状」「再現手順」「期待する動作」を分けることだ。Claude Code はコードベースを読むのが得意だが、何を成功とみなすかは人間が決めないといけない。ここを雑にすると、見た目だけ直って中身が変、という事故が起きる。
再現手順は、できるだけ一本道にする。条件を盛り込みすぎると、どこが本丸か分からなくなる。たとえばファイル整理の作業なら、「このフォルダを開いて、この拡張子だけを対象にして、ここに移動する」のように、1回で再現できる形に削る。非エンジニアの作業でも同じだ。重複ファイルの削除や書類の仕分けでも、まず「どのフォルダ」「どの条件」「何が起きたら失敗か」を書く。Claude Code は人間の曖昧な記憶より、こういう明文化に強い。
もう少し実務寄りにやるなら、再現用の最小データを作らせるのがいい。巨大な実データをそのまま渡すと、調査が重くなる。変化点だけを残した小さい例を用意する。
再現用に、最小限のサンプルデータを作ってください。
実データの中身は不要です。
必要なのは次の条件だけです。
- 日本語を含むファイル名
- 空白を含むファイル名
- 拡張子が複数あるケース
この3条件だけでバグが再現するか確認したいです。
こう頼むと、Claude Code は無駄に広い範囲を触らずに済む。再現用サンプルは、修正のたびに何度も使う。ここを丁寧に作ると、後で「直したはずなのに別ケースで壊れた」が減る。地味だが、効く。
注意したいのは、「再現できないのに直して」と急かすことだ。これはかなり危ない。Claude Code は手元のコードを見て推測はできるが、再現できない不具合は推測の比率が上がる。推測が増えると、修正が広がる。広がった修正は、あとで検証が面倒だ。筆者は一度、ログだけ渡して「たぶんここ」と当てにいった結果、別の入力経路まで巻き込んでしまい、差分の説明に時間を取られた。ああいうのは避けたほうがいい。
だから、再現手順を渡すときは、失敗条件もセットで書くとよい。
次の条件では再現しないことも確認したいです。
- ファイル名が半角英数字のみ
- 対象ファイルが1件だけ
- 出力先に既存ファイルがない
この条件で再現しないなら、問題は名前の変換周りに絞れそうです。
これは地味に効く。Claude Code に「何が原因ではないか」を見せると、調査の枝が減る。バグ修正は、当てる作業ではなく、外す作業でもあるからだ。
さらに一歩進めるなら、修正を頼む前に、再現した結果をそのまま貼るといい。エラーメッセージ、終了コード、生成されたファイル名、途中まで出たログ。このへんは、見た目より大事だ。特にCLI系の作業では、失敗が静かに起きることがある。何も出ずに終わる、途中で中断する、別フォルダに出力される。そういうときは、再現手順だけでなく、実際の観測結果を一緒に渡す。
再現結果:
- 実行は最後まで終わったように見える
- ただし出力ファイルは作られない
- 標準エラーには Permission denied が1回だけ出る
- どの入力ファイルで失敗したかは表示されない
ここまで書けば、Claude Code はコード中の失敗点を追いやすくなる。修正後の確認も、同じ文章をそのまま使えばいい。人間の記憶頼みよりずっと堅い。
ただし、やりすぎもある。再現手順を長文の実況中継にすると、肝心の条件が埋もれる。読む側もつらいし、Claude Code もノイズを拾う。大事なのは、再現に必要な順番だけだ。余計な背景説明は後ろに回す。先に条件、次に結果、最後に補足。これで十分だ。
このやり方は、バグ修正だけじゃなく、ファイル整理や文書作成にもそのまま効く。たとえば「この命名ルールでフォルダを整理してほしい」「この条件のPDFだけ抜き出してほしい」「このテンプレートで議事録を整えてほしい」といった依頼も、まずは再現手順化したほうがいい。曖昧な依頼は、だいたい曖昧な結果になる。逆に、再現条件がはっきりしていれば、Claude Code はかなり素直に動く。
要するに、直してほしいなら、先に同じ失敗を起こさせることだ。そこを省くと、修正はだいたい博打になる。再現できる依頼に変えるだけで、調査の精度も、修正の速さも、確認の楽さも変わる。これがいちばん地味で、いちばん効く。