雑に「失敗した」で片づけると、Claude Code はだいたい同じところをまた踏む。そこがまずい。再現しなかった失敗と、たまたま起きた失敗を混ぜて書くと、原因がぼやける。失敗の切り分け、偶発エラーの整理、再現性の判定を先にやるだけで、次の指示がかなり鋭くなる。
Claude Code は、曖昧な記録をそのまま信じて突っ走ると、不要な修正を広げやすい。逆に、何が毎回起きるのか、何が一度だけ起きたのかを分けて残すと、無駄なコンテキスト消費が減る。筆者は最初、エラー文をそのまま貼って「直して」と投げていたが、実際には一回しか出ていない偶発エラーまで重要扱いしてしまい、関係ない周辺ファイルまでいじられて手戻りした。あれは地味にだるい。
まずやることは単純だ。失敗ログを「再現した」「再現しなかった」「条件つきで再現した」の3つに分ける。Claude Code に頼むときも、ここを混ぜない。
たとえば、調査メモを作るならこんな書き方で十分だ。
次の失敗を整理してください。
- いつ起きたか
- 何をしたときに起きたか
- 同じ操作で再現するか
- 1回だけの偶発エラーか
- その失敗が何に影響したか
出力は次の3区分でまとめてください。
1. 再現した失敗
2. 再現しなかった失敗
3. たまたま起きた失敗の可能性が高いもの
曖昧なものは「保留」に分け、勝手に原因を断定しないでください。
この手の整理は、コード修正だけでなく、ファイル整理や文書作成でも効く。たとえば大量のPDFや画像をClaude Code に見せて「不要なものを探して」と頼む場面だ。1回だけ出た謎のファイル名を「不要」と決めつけると危ない。バックアップ直後にだけ置かれた一時ファイルかもしれないし、アプリが吐いた一過性のログかもしれない。そこで、まず「繰り返し出るもの」と「1回だけ見えたもの」を分ける。
実際の依頼文は、こんな具合にすると扱いやすい。
このフォルダ内の不要候補を整理してください。
ただし、次のものは分けて扱ってください。
- 同じ種類が複数回出てくるもの
- 1回だけしか見えないもの
- 作成日時や内容から偶発的に置かれた可能性があるもの
削除候補は、理由を1行ずつ添えて出してください。
不確かなものは削除候補に入れず、保留にしてください。
ここで大事なのは、「何が原因か」を急いで言い切らせないことだ。Claude Code は整理役としては優秀だが、雑な問いには雑な整理を返す。エラーを見つけた瞬間に「原因はこれだろう」と飛びつくと、たまたま出た失敗に引きずられる。人間も同じで、派手な失敗ほど犯人に見える。だが、実際は再現しない。そういうやつは、記録上いちばん扱いづらい。
記録のコツは、失敗を「現象」「条件」「再現性」で分けることだ。原因欄を先に埋めない。順番が逆だと、あとで話が壊れる。
たとえばメモはこう整える。
現象:
- 保存に失敗した
- ファイル名が文字化けした
- 予定外のファイルが1つ増えた
条件:
- 同じ操作を3回やったうち1回だけ発生
- ネット接続が不安定な時間帯
- その直前に別アプリでも更新が走っていた
再現性:
- 再現した
- 再現しなかった
- 条件をそろえると再現する可能性がある
この分け方をしておくと、Claude Code に次の指示が出しやすくなる。「再現したものだけを対象に修正案を出して」「再現しなかったものは除外して」と言えるからだ。逆に全部を一緒に渡すと、話が広がる。diff が妙に大きくなったり、関係ないファイルの候補まで並んだりする。あれは無駄が多い。
少し実務寄りのコツもある。失敗を見たら、その場で次の4点だけは残す。長文はいらない。短くていい。
- 何をしたか
- 何が起きたか
- 同じ手順で再び起きたか
- 画面に出た文言やファイル名
この4点があると、後でClaude Code に投げ直したときに、「再現しなかった失敗」なのか「たまたま起きた失敗」なのかを切り分けやすい。スクリーンショットを貼るだけより、ずっと強い。画像は文脈を食うわりに、再現性の判断材料が抜けやすいからだ。
注意したいのは、たまたま起きた失敗を過大評価しないことだ。1回だけのタイポ、1回だけの接続切れ、1回だけのファイル競合は、重大事故に見えても実はノイズのことがある。筆者は以前、1回だけ出た同期エラーを本命扱いしてしまい、同期設定まわりを広く見直してしまった。あとから見ると、単に一時的な外部要因だった。ああいう修正は、やる前に一息置いたほうがいい。
Claude Code にその判断を手伝わせるなら、問いをこう絞る。
次の記録を、再現性で分類してください。
- 再現した
- 再現しなかった
- たまたま起きた可能性が高い
- まだ判断できない
判断の根拠も短く書いてください。
不十分な情報があれば、追加で確認すべき点だけ質問してください。
これで十分だ。ここで「原因を断定しろ」とは言わない。断定した瞬間に、偶発エラーの整理が崩れる。実務では、断定より切り分けのほうが価値がある。特にファイル整理や文書作成みたいな用途では、まず安全側に寄せるのが正しい。
一歩進めるなら、記録の名前そのものを変えるといい。単に「エラー記録」ではなく、「再現ログ」「単発ログ」「保留ログ」に分ける。Claude Code にもその名前で見せる。ラベルがあるだけで、以後の指示がぶれにくくなる。
この3つのファイルに分けて整理してください。
- 再現ログ.md
- 単発ログ.md
- 保留ログ.md
再現ログには、同条件で繰り返し起きたものだけを書く。
単発ログには、1回しか起きていないものを書く。
保留ログには、情報不足で判断できないものを書く。
こうしておくと、後で見返したときに「これは本当に直すべき失敗か」がすぐ見える。雑に全部を同列に置くと、過去の自分が出したノイズまで未来の自分が読まされる。時間の無駄だ。
最後にひとつだけ強く言う。失敗の記録は、事実を並べる作業であって、気分を書き殴る作業ではない。再現したものと、たまたま起きたものを分けておけば、Claude Code はかなり賢く使える。逆にそこをサボると、指示の精度が落ちる。地味だが、効き目は大きい。