機能を学ぶ前に知りたい、Claude Code の失敗パターン4分類

機能を学ぶ前に、失敗の種類を知る

Claude Code を使い始めたばかりのころ、私は「どの機能をどう組み合わせるか」ばかりを考えていた。Auto Mode を覚え、Hooks を設定し、MCP を繋いで——そうやって機能を積み上げていくうちに、ふと気づいた。うまく動かないとき、「どの機能が足りないか」ではなく「何が壊れているか」を先に特定しないと、対策を間違えてしまうと。

このブログでこれまで書いてきた多角性の記事は、役職・粒度・時間・フェーズ・記憶層・信頼度という6つの「正の軸」だった。本記事は初めての「負の軸」——Claude Code の失敗パターンを症状ベースで4タイプに整理し、それぞれの原因と対策を対応づける。

機能をどれだけ覚えても、失敗の種類を見誤ると対策が的外れになる。

失敗4分類マトリックス

このマトリックスは対症療法的な見立てでもある。根本を追えば「権限・監視・コスト・コンテキスト」という4つの設計領域のどこかに歪みがある。

暴走 — 指示を超えた連鎖

症状

エージェントが指示の範囲を超えてファイル群を一括書き換えする。rm -rf のような不可逆操作を確認なしで実行する。「完了したら終了せよ」と指示しても延々と続行する。サブエージェントが想定外のドメインに踏み込む。こうした現象をまとめて「暴走」と呼ぶ。

実際に起きたこと

blog-agents のパイプラインで、researcher エージェントが2回脱線した。1回目は internal-comms スキルの判定ループに入って終了できなくなり、2回目は「Step 2: RAG検索」の手前で処理が止まった。いずれも main agent が直接 WebFetch でリカバリするしかなかった。

原因を追ってみると、権限が広いまま完了条件が曖昧な状態でエージェントを動かしていたことが問題だった。どこまでやれば終わりかが定義されていないエージェントは、何かがトリガーになって無関係な処理に流れやすい。

防ぐには

暴走に対して最も直接的に効くのが Auto Mode と Hooks の deny 設計 の組み合わせだ。Auto Mode は irreversible と判定した操作を自動でブロックし、PreToolUse フックでは rm -rf や git push --force といったパターンをマッチして deny できる。

最小投資として「rm -rf をパターンマッチで deny する1行を Hooks に追加する」だけでも、事故の規模は大きく変わる。

作り物 — 実在しない事実

症状

実装コードの中に実在しない API 関数名が紛れ込む。記事の数値や引用が根拠なく書かれている。もっともらしいバージョン番号や URL が微妙にずれている。二次情報を一次情報のように扱う——これらは Claude が自信を持って誤ったことを書くハルシネーションの症状だ。

実際に起きたこと

blog-agents では複数回、このパターンに引っかかっている。

ひとつは AMD のコスト数値「$12→$1,504」という記述で、二次情報1ソースのみで一次裏取りができなかったため、Plagiarism エージェントが記事から削除した（アンチパターン4選の記事執筆時）。もうひとつは Hetzner の CX11 プランで、廃止済みのプランを「最小構成」として推奨しかけたところを Plagiarism が CX23 に訂正した（Discord 連携記事の執筆時）。

もっと根の深い問題が学術引用だ。Claude は「Gloaguen et al. 2026」のような年付きの著者名引用を自然に生成する傾向がある。しかし多くが架空の引用だ。このパターンは writer-lessons に記録し、「実在確認できない引用は『複数の研究・実測報告によると』で一般化する」というルールに落とし込んだ。

防ぐには

作り物への対策は構造的な検証層を設けることだ。blog-agents では Plagiarism エージェントが WebFetch で一次出典を確認する役割を持っている。数値や引用に ◎（公式一次情報）・○（二次情報）の信頼度マークをつける習慣も有効で、書くときに出典の強さを意識させる効果がある。

架空の学術引用を生成する癖は Claude の根本的な傾向だ。年付き著者名の引用が出てきたら、実在を確認してから使うか、一般表現に置き換えることを迷わず選ぶ。

コスト爆発 — usage limit 到達

症状

月額予算を予想外に早く消費する。1日で usage limit に到達してエージェントが止まる。Opus 4.7 を使ったセッションが想定の数倍のトークンを消費する。プロンプトキャッシュが効いているはずなのに効いていない。

実際に起きたこと

1M Context の記事を執筆した際の最終投稿フェーズで、auditor エージェントが「You've hit your org's monthly usage limit」を返して停止した。記事の仕上げと WordPress への投稿まであと一歩というタイミングだった。

このときは main agent が直接 Python の Markdown→HTML 変換スクリプトを書いて WordPress REST API に POST することでリカバリした。エージェントが止まっても手段がないわけではないが、タイミングが悪いとリカバリのコストも上がる。

コスト爆発の主な原因は Opus の長時間運用と、セッション中のモデル切替によるキャッシュリセットだ。tool 定義を動的に変更するとキャッシュが invalidate され、/compact の遅延でコンテキストが膨らむことも拍車をかける。

防ぐには

Statusline でコストとコンテキスト使用率を常時可視化しておくと、爆発前に異変に気づける。/cost を定期確認する習慣もシンプルだが効く。

Prompt Caching の設計も直接的に効く。tool 定義を固定し system prompt を不変に保ちながらメッセージで状態を更新するパターンを徹底する。モデルの使い分けも有効で、探索期は Sonnet、本格作業は Opus、ヘビーバッチは Haiku というすみ分けを意識するとコストが安定しやすい。

精度低下 — 同じミスの再発

症状

同じ質問への回答が以前より悪化している。コンテキストの中盤にある情報が参照されなくなる。三点列挙や太字インラインヘッダーなど AI 臭の強い文体が増える。過去に指摘したはずの癖が再発する。

実際に起きたこと

blog-agents で顕著だったのが AI 臭パターンの再発だ。三点列挙＋時間タグ（「〜（5分）。〜（10分）。〜（30分）。この3つから〜」）や、段落冒頭の太字インラインヘッダー（「〇〇は〜だ」）は最初の数記事で頻発し、tone-checker の patterns.md に34以上のパターンとして蓄積することで徐々に抑制できた。

もうひとつは ultrathink をめぐる誤解だ。「ultrathink > think harder > think hard > think」という段階表は公式 Best Practices ドキュメントにも記載されており、実際に thinking budget にマッピングされている。ところがコンテキストが古い情報で組まれていると、段階表を「ただの二次情報の流布」と混同して誤った記述が生まれやすい。精度低下はこうした「前提情報の鮮度」の問題として現れることがある。

精度低下は MRCR（Multi-Range Context Retrieval）の特性とも関係している。1M コンテキストでも MRCR は約76%、256K では93%程度しかコンテキスト内の情報を正確に参照できない。コンテキストを詰め込めば詰め込むほど、精度は落ちる。

防ぐには

コンテキスト使用率が70%を超えたら /compact を打つルールをチームで共有しておくことが基本だ。並行して、同じミスを繰り返さないための knowledge/ パターン蓄積を続けることで、AI 臭の再発を地道に減らしていける。

4分類の連鎖と最小投資

連鎖に気づく

4つのタイプは独立した障害ではなく、連鎖する。精度が下がったまま実行を続けると判断が曖昧になって暴走につながる。暴走すると無駄な操作が連発してコスト爆発が起きる。作り物の情報を前提に次の処理が走ると、誤情報がコンテキストに蓄積されて精度低下が加速する。コスト爆発でセッションを切り替えると、コンテキストが消失してまた精度が下がる。

最初の1タイプに気づいたら、他の3タイプに連鎖していないかを確認する習慣が、事故を小さく抑えるうえで効いてくる。アンチパターン4選の記事では設計上の悪手を整理しているが、本記事の4分類は「症状が出た後の見立て」として補完関係にある。

最小投資の考え方

完璧な対策を追うより、各タイプに最小の一手を入れることを優先する。

この4つをまず入れておくだけで、多くの事故は未然に防げるか、少なくとも早い段階で気づける。blog-agents の実体験からの感覚では、「暴走を防ぐ deny ルール」と「コスト可視化」の2つが最初の一手として優先度が高い。

失敗の見立てが設計を変える

Claude Code を使いこなすということは、機能を覚えることではなく、「何が壊れやすいか」を身体に入れることだと私は思っている。症状から4タイプに分類できるようになると、新しい機能を組み合わせるときに「これは暴走リスクを増やさないか」「作り物を増幅させないか」という問いが自然に出てくる。

blog-agents の実体験記事ではパイプライン構築の時系列を整理しているので、失敗が具体的にどう起きたかを辿りたい方はそちらも参照してほしい。自分の運用でどのタイプが出やすいかを把握しておくと、次に機能を組み合わせるときの判断が変わる。