Claude Codeのアンチパターン5選 — 陥りやすい失敗と回避策

Claude Codeでよく起きる5つの失敗パターン

Claude Codeの運用でつまずく原因は、機能の使い方そのものより、セッションの回し方に集中しています。コンテキストウィンドウは有限で、詰め込みすぎれば性能が落ち、指示が長すぎれば読み飛ばされます。この記事では、その有限さが原因で繰り返し起きる5つの失敗パターンと、それぞれの直し方をまとめます。

1. Kitchen sinkセッション — 無関係な作業を1つに混ぜる

1つのタスクで始めたセッションに、途中で関係のない別の質問を挟み、また元のタスクに戻る。これを繰り返すと、コンテキストは無関係な情報だらけになります。元のタスクに関する判断材料が、あいだに挟んだ別件のやり取りに埋もれ、Claudeも人も何が今の論点かを見失いやすくなります。長いセッションほどこの埋もれ方は静かに進み、気づいたときにはもう遅いということが少なくありません。

直し方は単純です。無関係なタスクに移る前に/clearでコンテキストをリセットします。「ついでに聞く」のコストは、質問1つぶんの手間ではなく、セッション全体の判断材料が薄まることだと捉え直すと、/clearを挟む判断がしやすくなります。迷ったら切る、を基本にします。

2. 直らない指摘を繰り返す — 同じ間違いを何度も直させる

Claudeが何かを間違え、指摘して直させても、まだ間違っている。もう一度指摘する。この往復を繰り返すほど、コンテキストは失敗した試行の記録で埋まっていきます。厄介なのは、この状態のセッションほど指摘の効きが悪くなることです。過去の失敗したアプローチがコンテキストに残ったまま次の指示を出しても、同じ思い込みを引きずって同じ間違いに戻りやすくなります。

2回訂正して直らなければ、3回目を試す前に/clearします。そのうえで、1回目・2回目の訂正で分かったことを踏まえた、より具体的な最初の指示を書き直します。同じ土俵で往復を続けるより、土俵ごと作り直すほうが早く収束します。

たとえば「このAPIのエラーハンドリングを直して」とだけ頼み、返ってきた実装が的外れで訂正、次の実装も別の観点で的外れで再訂正、という展開になったとします。3回目の指示を同じセッションで出す前に/clearし、「404は再試行せず即座に呼び出し元へエラーを返す。500系は3回まで指数バックオフで再試行する」のように、1・2回目の的外れさから逆算した具体的な条件を最初から書きます。往復のたびに条件を後出しするより、失敗から学んだ条件を一度にまとめて渡すほうが、同じ思い込みへの逆戻りを防げます。

3. 肥大化したCLAUDE.md — ルールが多すぎて無視される

CLAUDE.mdが長くなりすぎると、Claudeは重要なルールをノイズに埋もれさせて見落とします。「あれもこれも書いておけば守られる」という積み増しの発想が、逆に守られるルールの数を減らします。

直し方は容赦なく削ることです。指示がなくてもClaudeがすでに正しくやっていることは、CLAUDE.mdから消すか、hookのような機械的な強制に置き換えます。CLAUDE.mdは「毎回説明し直すのが面倒なこと」を書く場所であって、網羅的な仕様書ではありません。

「保存前に必ずlintを走らせる」のような手順は、CLAUDE.mdに文章で書いておいても、他の指示に埋もれて実行されないことがあります。同じ内容をPostToolUse hookでlintコマンドを自動実行する形に変えれば、Claudeが読み飛ばす余地自体がなくなります。文章で「守ってほしい」と頼むより、機械的に強制できる部分はhookへ移すほうが確実です。CLAUDE.mdの階層設計と運用についてはClaude CodeのCLAUDE.mdを実用に引き上げる10のパターンで扱っています。

4. Trust-then-verify gap — もっともらしい実装がエッジケースを取りこぼす

Claudeが作った実装は、見た目にはもっともらしく仕上がっています。しかし実際に動かしてみると、想定していなかった入力やエッジケースを処理できていないことがあります。この「もっともらしさ」と「実際に正しいか」のあいだの隙間が、trust-then-verify gapです。

埋め方はただ1つ、検証手段を渡すことです。テスト・スクリプト・スクリーンショット比較のように、合否がその場で分かる仕組みを用意していなければ、検証できない変更は出荷しません。「メール検証関数を実装して」とだけ頼むより、「user@example.comはtrue、invalidはfalse、user@.comはfalseになるテストケースで確認してから実装して」のように、合否を判定できる条件を最初のプロンプトに含めておくと、実装後にその場でチェックが回ります。

検証を実装セッション自身に任せきりにしないという発想を一段進めたのが、別のサブエージェントに新しい文脈で差分を検証させる敵対的レビューです。実装した本人が「もっともらしい」と感じている状態そのものが、trust-then-verify gapの原因なので、判定役を分けることは検証手段を渡すこととは別角度からこのgapを埋めます。

5. 際限のない調査 — スコープなしの「調査して」がコンテキストを埋め尽くす

範囲を絞らずに「調査して」とだけ指示すると、Claudeは関連しそうなファイルを何百本も読みに行き、コンテキストがそれだけで埋まってしまいます。調査結果そのものより、調査の過程で読んだファイルの中身が場所を取るのが問題です。

直し方は2つあります。調査の範囲を狭く区切って指示するか、調査そのものをサブエージェントに任せます。「認証まわりを調べて」ではなく「トークンのリフレッシュ処理と、既存のOAuthユーティリティが再利用できるかをサブエージェントで調べて」のように、対象と目的を絞った指示にするだけで、読みに行くファイルの数は大きく変わります。

サブエージェントは独立したコンテキストで動き、メインには要約だけが返るため、探索の中身がメインの会話を圧迫しません。子側が内部でReadやGrepを何十回繰り返しても、メインに載るのは結論だけです。サブエージェントを使った調査の分業はClaude Codeのサブエージェント完全活用で扱っています。

5つの型を早見表で比較する

5つに共通しているのは、原因が機能の欠陥ではなく運用の型だという点です。どれもClaude Code側の不具合ではなく、コンテキストウィンドウという有限の資源をどう配分するかという、使い手側の設計判断で防げます。

型として覚えるより、兆候に気づく練習をする

この5つは固定の正解ではありません。複雑な1つの問題を深掘りしている最中は、あえてコンテキストを蓄積させたほうがよい場面もあります。探索的なタスクでは計画を飛ばしていきなり試させたほうが早いこともあります。制約を先に決めず、あいまいな指示のまま様子を見たいときもあります。

大事なのは、うまくいったときに何をしたかを覚えておくことです。プロンプトの組み立て方、渡した文脈、選んだモード。逆にうまくいかなかったときは、コンテキストが騒がしくなっていなかったか、指示があいまいすぎなかったか、タスクが1回のセッションには大きすぎなかったかを振り返ります。この振り返りを重ねることが、どのガイドよりも実践的な判断力につながります。5つのパターンはチェックリストというより、振り返るときに使う語彙だと捉えると扱いやすくなります。

まとめ

Claude Codeの失敗の多くは、機能の使い方ではなくセッションの回し方に原因があります。Kitchen sinkセッション・訂正の繰り返し・肥大化したCLAUDE.md・trust-then-verify gap・際限のない調査の5つは、どれもコンテキストウィンドウという有限の資源が原因です。共通の対処は「気づいたら早めに区切る」こと。/clear、検証手段の用意、サブエージェントへの分業は、いずれもこの一点に集約されます。

よくある質問

/clearと/compactはどちらを使うべきですか

無関係な作業に移るなら/clearでコンテキストを丸ごとリセットします。同じタスクの続きでコンテキストが埋まってきただけなら、重要な情報を要約して残す/compactのほうが向きます。/compact <指示>のように焦点を絞った指示を添えることもできます。

CLAUDE.mdはどのくらいの長さが目安ですか

公式に明確な文字数の基準はありません。目安は「Claudeがすでに指示なしで正しくやっていることが書かれていないか」を定期的に見直すことです。守られていないルールが多いと感じたら、量を減らす方向で調整します。

Trust-then-verify gapは小さな修正でも意識すべきですか

修正の規模に関わらず、検証できるかどうかを基準にします。1行の修正でも、テストやビルドで合否を確認できるならその場でチェックし、確認できないまま出荷しないという原則自体は変わりません。

5つのパターンはClaude Code特有の問題ですか

コンテキストが有限のAIエージェント全般に共通する構造です。ただし対処の手段(/clear、サブエージェントへの分業、Stop hookでの機械的な検証ゲート)はClaude Codeの機能に沿った具体策になっています。他のエージェントツールに移っても、原因を「コンテキストの有限さ」で捉える見方自体は流用できます。