Claude Codeのアンチパターン5選 — 陥りやすい失敗と回避策
Kitchen sinkセッションやCLAUDE.mdの肥大化など、Claude Codeの運用でよく起きる5つの失敗パターンと、症状から選べる直し方・区切りコマンドの使い分けをまとめます。
Claude Codeでよく起きる5つの失敗パターン
Claude Codeの運用でつまずく原因は、機能の使い方そのものより、セッションの回し方に集中しています。コンテキストウィンドウは有限で、別件の会話や失敗の記録が積もるほど、肝心の指示が埋もれます。
公式のベストプラクティスは、この有限さから繰り返し起きる失敗を5つ挙げています。症状と最初の一手を先に並べると次のとおりです。
5つの失敗と最初の一手
別件を挟んだら元の作業が雑になった
Kitchen sinkセッションです(1節)。
同じ指摘を何度もしている
直らない指摘の繰り返しです(2節)。
CLAUDE.mdのルールが守られない
CLAUDE.mdの肥大化です(3節)。
動かすと端のケースで落ちる
Trust-then-verify gapです(4節)。
「調査して」で何も進まなくなった
際限のない調査です(5節)。
以降、各パターンの中身を順に見ます。
1. Kitchen sinkセッション — 無関係な作業を1つに混ぜる
1つのタスクで始めたセッションに、途中で関係のない質問を挟み、また元のタスクに戻る。これを繰り返すと、コンテキストは無関係な情報だらけになります。元のタスクの判断材料が、別件のやり取りに埋もれていきます。
直し方は、無関係なタスクに移る前に/clearでコンテキストをリセットすることです。「ついでに聞く」のコストは質問1つぶんの手間ではなく、セッション全体の判断材料が薄まることだと捉えると、切る判断がしやすくなります。
「ついで」の質問が本当に別件なら、/clearの手前にもう一つ選択肢があります。/btwは、現在のセッションに内容を追加せずに脇道の質問をするコマンドです。確認したいだけの質問なら、会話履歴を汚さずに済みます。
/clearは元の会話を捨てる操作ではありません。/clear 認証リファクタのように名前を付けると、前の会話は/resumeの一覧にその名前で残ります。同じClaude Codeプロセスの中なら、rewindメニューの前セッションの項目から復元することもできます。起動時に名前を付けたいときはclaude -n <name>が使えます(v2.1.287のclaude --helpで確認)。
2. 直らない指摘を繰り返す — 同じ間違いを何度も直させる
Claudeが何かを間違え、指摘して直させても、まだ間違っている。もう一度指摘する。この往復を繰り返すほど、コンテキストは失敗した試行の記録で埋まります。公式の基準は明快で、同じ問題で2回を超えて訂正したなら、コンテキストが失敗したアプローチで散らかっているとみなします。
訂正が2回で直らないときの手順
- 1
`/clear`でセッションを切り替える
3回目の指摘を同じセッションで出さず、いったん新しい会話にします。
- 2
訂正で分かった条件を洗い出す
1回目・2回目の的外れさから、本当に欲しかった挙動を逆算します。
- 3
条件をまとめて最初の指示に書く
後出しで足していくのではなく、1つのプロンプトにまとめて渡します。
たとえば「このAPIのエラーハンドリングを直して」とだけ頼み、返ってきた実装が的外れで、次の実装も別の観点で的外れだったとします。この場合、最初の指示を「404は再試行せず即座に呼び出し元へエラーを返す。500系は3回まで指数バックオフで再試行する」のように書き直します。失敗から学んだ条件を一度に渡すほうが、同じ思い込みへの逆戻りを防げます。
3. 肥大化したCLAUDE.md — ルールが多すぎて無視される
CLAUDE.mdが長くなりすぎると、重要なルールがノイズに埋もれます。公式のメモリー解説は、1ファイル200行未満を目安とし、それより長いと追加のコンテキストを消費して遵守率が下がると述べています。
分量の対処は、削る・分ける・置き換えるの3つです。
- 削る: 指示がなくてもClaudeがすでに正しくやっていることは消します。判断の物差しは「この行を消したらClaudeが間違えるか」です。
- 分ける: コードベースの一部にしか関係しない指示は、
.claude/rules/のパス指定ルールに移します。該当ファイルを扱うときだけ読み込まれます。 - 置き換える: 毎回必ず実行したい処理はhookにします。
削る前に、矛盾する指示がないかも見ておきます。2つの指示が食い違うと、Claudeはどちらかを任意に選ぶことがあります。サブディレクトリのCLAUDE.mdや.claude/rules/まで含めて、古い指示や衝突する指示を定期的に点検する運用が公式に示されています。
特定の1行だけが守られないときは、その行だけに「IMPORTANT」のような強調を足す手があります。多くの行を強調すると、どれも目立たなくなります。
見落としやすい点が1つあります。@pathのimportは、ファイルを整理する助けにはなりますが、コンテキストの消費は減らしません。importしたファイルも起動時に読み込まれるためです。長いCLAUDE.mdをimportで分割しても、肥大化は解消されません。
削る作業に自信が持てないときは、チェックイン済みのCLAUDE.mdに対して/doctorを実行すると、コードベースから導ける内容についてClaudeが削除案を出します。/contextは、メモリーの肥大化を含む最適化の提案を出します。
「編集のたびにフォーマッタを走らせる」のような手順は、CLAUDE.mdに書いても助言として読まれるだけです。公式は、CLAUDE.mdとauto memoryをどちらも「強制される設定ではなくコンテキスト」として扱うと説明し、動作をブロックしたいならPreToolUse hookを使うよう案内しています。毎回必ず走らせたい処理は、PostToolUse hookに移せます。
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
}
]
}
]
}
}これは公式のhooksガイドにあるPrettierの例で、.claude/settings.jsonに置きます。Edit|Writeのmatcherにより、ファイル編集ツールの後だけ動きます。設定済みのhookは/hooksで確認できます。CLAUDE.mdの階層設計と運用についてはClaude CodeのCLAUDE.mdを実用に引き上げる10のパターンで扱っています。
4. Trust-then-verify gap — もっともらしい実装がエッジケースを取りこぼす
Claudeが作った実装は、見た目にはもっともらしく仕上がります。しかし動かしてみると、想定外の入力やエッジケースを処理できていないことがあります。この「もっともらしさ」と「実際に正しいか」のあいだの隙間が、trust-then-verify gapです。
埋め方は、検証手段を渡すことです。公式の指示は「検証できないなら出荷しない」です。たとえば「メール検証関数を実装して」とだけ頼むより、「user@example.comはtrue、invalidはfalse、user@.comはfalseになるテストケースで確認してから実装して」のように、合否を判定できる条件を最初のプロンプトに含めます。UIの変更なら、スクリーンショットを貼って「実装後に撮った画面と元の画面を比べて差分を直す」と頼む形になります。
検証の強さは、ここから段階的に上げられます。
検証をどこまで機械に任せるか
プロンプトの中で頼む
実行して直すところまでを同じ依頼に含めます。どのタスクでも、今すぐ使えます。
`/goal`・Stop hookで縛る
/goalは完了条件を満たすまで別の評価役が毎ターン確認します。Stop hookは、チェックのスクリプトが通るまでターンの終了をブロックします。
もう一段上には、新しい文脈の別サブエージェントに差分を検証させる方法があります。新しい文脈のサブエージェントは差分だけを見て検証できます。具体的な型は敵対的レビューで扱っています。
5. 際限のない調査 — スコープなしの「調査して」がコンテキストを埋め尽くす
範囲を絞らずに「調査して」とだけ指示すると、Claudeは関連しそうなファイルを何百本も読みに行き、コンテキストがそれだけで埋まります。読んだファイルはすべてコンテキストを消費します。
直し方は2つあります。調査の範囲を狭く区切るか、調査そのものをサブエージェントに任せることです。「認証まわりを調べて」ではなく「トークンのリフレッシュ処理と、既存のOAuthユーティリティが再利用できるかをサブエージェントで調べて」のように、対象と目的を絞ります。
サブエージェントは独立したコンテキストウィンドウで動き、メインには要約だけが返ります。子側がReadやGrepを何十回繰り返しても、メインの会話に載るのは結論だけです。分業の組み方はClaude Codeのサブエージェント完全活用で扱っています。
区切るコマンドは3種類 — /clear・/compact・/rewind
失敗への対処はどれも「どこで区切るか」に行き着きます。区切り方は会話の捨て方で3種類に分かれます。
/rewindのチェックポイントが追うのは、Claudeのファイル編集ツールによる変更だけです。Bashコマンドや外部プロセスによる変更は記録されないため、gitの代わりにはなりません。
コンテキストを区切る3つの方法
`/clear`
空のコンテキストで新しい会話を始めます。
`/compact [指示]`
会話を要約して場所を空けます。同じタスクを続けたいときに向き、/compact API変更に集中のように焦点を指定できます。
`/rewind`
Esc2回でも開きます。選んだメッセージ以降だけ、または以前だけを要約できます。
自動要約に任せる場合の閾値も調整できます。/autocompact 500kのようにトークン数を渡すと、自動要約が走るまでにコンテキストをどこまで使うかを決められます(v2.1.221以降)。claude --helpにも--autocompact <auto|tokens>が載っています(v2.1.287で確認)。プロジェクトルートのCLAUDE.mdは/compactの後もディスクから読み直されて再注入されます。会話の中だけで伝えた指示は要約で消えうるので、残したい指示はCLAUDE.mdに書きます。要約で何が残るかは、CLAUDE.mdに「要約時は変更したファイルの一覧とテストコマンドを必ず保持する」のように書いておく方法が公式に示されています。
型として覚えるより、兆候に気づく練習をする
この5つは固定の正解ではありません。複雑な1つの問題を深掘りしている最中は、あえてコンテキストを蓄積させたほうがよい場面があります。探索的なタスクなら、計画を飛ばしていきなり試させたほうが早いこともあります。あいまいな指示のまま様子を見たいときもあります。
大事なのは、うまくいったときに何をしたかを覚えておくことです。プロンプトの組み立て方、渡した文脈、選んだモード。うまくいかなかったときは、コンテキストが騒がしくなっていなかったか、指示があいまいすぎなかったか、タスクが1回のセッションには大きすぎなかったかを振り返ります。5つのパターンはチェックリストというより、その振り返りに使う語彙です。
まとめ
同じ症状が続くときは、訂正を重ねる前にセッションの区切り方を変えるのが近道です。散らかったコンテキストの上で指示を足しても、埋もれる量が増えるだけだからです。