AIエージェントは「静かに壊れる」——監視なき自動化の危険性
\nAIエージェントを本番環境に投入した直後は順調に動いていたのに、気づいたらAPIコストが10倍に膨れ上がっていた。あるいは、エージェントが無限ループに陥ったまま数時間動き続けていた——そんな経験をした開発者は少なくないはずです。
\n従来のソフトウェアはエラーが出れば例外をスローして止まります。しかしLLMベースのAIエージェントは「失敗してもそれっぽい出力を返し続ける」という特性があります。エラーログには何も残らないまま、実は期待した動作をまったくしていない、という事態が発生しやすいのです。
\nこの記事では、CLAUDE.mdに異常検知・モニタリングの仕組みを設計・組み込むことで、AIエージェントの問題を早期発見し、安定稼働を維持するための実践パターンを紹介します。CI/CDや自己修正の観点についてはAIエージェント開発を加速するCI/CD実践ガイドも参照してください。
\n\nAIエージェントの異常は「エラーとして顕在化しにくい」ため、能動的なモニタリング設計が不可欠です。CLAUDE.mdにその指針を明示することで、エージェント自身が異常を検知・報告する仕組みを作れます。
\nなぜCLAUDE.mdにモニタリングを書くのか
\nCLAUDE.mdはAIエージェントへの「指示書」です。コーディング規約やワークフロー手順だけでなく、エージェントが自分自身の動作を監視・評価するための基準を記述できます。これにより次の3つの効果が得られます。
\n- \n
- 自己診断の基準が明示される：エージェントは何が「正常」で何が「異常」かを文脈として持てる \n
- 異常時の行動規範が統一される：ログ出力・アラート・処理停止のタイミングがブレない \n
- チームで共有できる監視仕様になる：暗黙知だったモニタリングルールがドキュメント化される \n
CLAUDE.mdがないと何が起きるか
\nCLAUDE.mdに監視指針がない場合、エージェントは「とにかく完遂しようとする」デフォルト動作を取ります。ループが300回に達しても、コストが上限を超えても、出力品質が著しく低下しても——止まる理由を知らないため動き続けます。結果として、開発者が翌朝ダッシュボードを見て初めて異常に気づく、という後手後手の対応になりがちです。
\n\n監視設計をCLAUDE.mdに入れる基本構造
\nCLAUDE.mdのモニタリングセクションは、大きく「検知条件」「通知方法」「対処行動」の3ブロックで構成するのが実践的です。
\n「AIエージェントの指示書に監視ルールを書く」というアイデアは奇妙に聞こえるかもしれませんが、自律的なシステムが自分の健全性を評価できるかどうかは、与えられた文脈次第です。\n\n
異常検知パターン：CLAUDE.mdに書くべき3つの監視観点
\n\n1. ループ・繰り返し検知
\nAIエージェントが最も陥りやすい問題の一つが「同じアクションを繰り返す無限ループ」です。CLAUDE.mdには以下のような指針を明示します。
\n## モニタリング規則\n\n### ループ検知\n- 同一ツール呼び出しが連続5回以上発生した場合、処理を一時停止してユーザーに確認を求める\n- 同じエラーメッセージが3回連続した場合は「再試行ループ」と判断し、別アプローチを試みるか停止する\n- タスク開始から30分経過しても完了しない場合、進捗サマリをログに出力して継続可否を問うこのルールがあることで、エージェントは自分がループしていることを「認識できる」状態になります。認識できれば、報告・停止・代替手段の試行といった適切な対処が可能になります。
\n\n2. コスト・リソース上限の監視
\nLLM APIのコストはトークン数に比例します。エージェントが大量のドキュメントを読み込み続けたり、長大なコンテキストを積み上げたりすると、1タスクで予期せぬ高額請求が発生することがあります。
\n### リソース監視\n- 1タスクで使用するファイル読み込みは最大20ファイルまで。超える場合は優先度の高いものに絞る\n- ツール呼び出しの総回数が50回を超えたら警告ログを出力し、ユーザーに残タスクを確認する\n- 外部APIへのリクエストは1分間に10回以内。超過しそうな場合はバッチ処理を検討する3. 出力品質の自己評価
\nAIエージェントは「それらしい」出力を生成し続けます。しかし品質が著しく低下していても気づかないことがあります。CLAUDE.mdに品質チェックの基準を書いておくことで、エージェントが自分の出力を評価する軸を持てます。
\n### 品質チェック\n- コード生成タスクの場合、生成後に必ずlint/typeチェックを実行する\n- テスト生成タスクでは、テストが実際にパスするか確認してから完了報告する\n- 曖昧な要件でタスクを開始する前に、具体的な完了条件を確認する「検知条件」を具体的な数値で書くことが重要です。「何度も繰り返したら」という曖昧な表現ではなく、「5回連続で同じツールを呼んだら」のように定量的に記述することで、エージェントの判断がブレなくなります。
\nHooksと組み合わせたイベント駆動モニタリング
\nCLAUDE.mdの指針だけでなく、Claude CodeのHooks機能を組み合わせることでより堅牢な監視体制が構築できます。HooksはAIエージェントのツール呼び出し前後に任意のシェルコマンドを実行できる仕組みです。
\n\nツール呼び出し前の安全チェック
\nたとえば、PreToolUseフックを使うと、エージェントが破壊的なコマンド（rm -rfやDROP TABLEなど）を実行しようとした瞬間にインターセプトできます。
# settings.json の例\n{\n \"hooks\": {\n \"PreToolUse\": [\n {\n \"matcher\": \"Bash\",\n \"hooks\": [{\n \"type\": \"command\",\n \"command\": \"echo '$CLAUDE_TOOL_INPUT' | python3 scripts/safety_check.py\"\n }]\n }\n ]\n }\n}ツール呼び出し後のログ収集
\nPostToolUseフックを活用すると、エージェントの全ツール呼び出し履歴を自動的にログファイルに記録できます。これにより、問題発生後の事後調査（ポストモーテム）が格段に楽になります。
# 呼び出し回数カウンタの例\n#!/bin/bash\nTOOL_COUNT_FILE=\"/tmp/claude_tool_count\"\ncount=$(cat \"$TOOL_COUNT_FILE\" 2>/dev/null || echo 0)\nnew_count=$((count + 1))\necho $new_count > \"$TOOL_COUNT_FILE\"\nif [ $new_count -gt 50 ]; then\n echo \"WARNING: Tool call count exceeded 50 ($new_count calls)\" >&2\nfiCLAUDE.mdとHooksの役割分担
\n| 観点 | CLAUDE.md | Hooks |
|---|---|---|
| 制御主体 | AIエージェント自身 | 外部シェル |
| 得意なこと | 判断・文脈理解・代替手段提案 | 確実な遮断・ログ記録 |
| 見落としリスク | LLMが指示を無視する可能性あり | ほぼゼロ（決定論的） |
| 柔軟性 | 高い（自然言語で複雑な条件記述可） | 低い（シェルスクリプトの範囲内） |
重要な安全制約はHooksで確実に担保し、判断が必要な監視ルールはCLAUDE.mdで担うという二層構造が理想的です。
\n\nCLAUDE.mdのモニタリングセクションは「エージェントへの命令」ではなく「エージェントが状況を評価するための基準」として書きましょう。「〜したら停止せよ」よりも「〜の状態はループの兆候であるため、ユーザーに確認してから継続する」という書き方の方が、エージェントが文脈を理解して適切に行動しやすくなります。
\n本番運用で役立つモニタリングCLAUDE.mdテンプレート
\n以下は、実際の本番環境で使えるモニタリングセクションのテンプレートです。プロジェクトの規模や性質に応じてカスタマイズしてください。
\n## 異常検知・モニタリング規則\n\n### 自己診断チェックリスト（タスク開始時）\n- [ ] タスクの完了条件は明確か？曖昧な場合はユーザーに確認する\n- [ ] 必要なファイルやAPIへのアクセス権はあるか？\n- [ ] 推定ステップ数は妥当か？10ステップを超えるなら分割を検討する\n\n### 異常パターンと対処\n| 検知条件 | 判断 | アクション |\n|---|---|---|\n| 同一エラーが3回連続 | 再試行ループの疑い | 別アプローチを提案してユーザーに選択を求める |\n| ツール呼び出し50回超過 | タスク肥大化 | 現在の進捗を報告して継続可否を確認 |\n| ファイル読み込み20件超過 | スコープ拡大 | 優先度の低いファイルを除外してリスタート |\n| 30分以上経過 | タイムアウト予兆 | 現状サマリを出力して指示を仰ぐ |\n\n### アラート出力形式\n異常を検知した場合、以下の形式でログ出力する:\n```\n[CLAUDE-ALERT] {timestamp} | 検知: {anomaly_type} | 詳細: {description} | 推奨アクション: {action}\n```\n\n### 正常終了の確認\nタスク完了時には以下を確認してから「完了」を報告する:\n1. 期待した出力・成果物が存在するか\n2. テスト・lintが通っているか（コードタスクの場合）\n3. 副作用（意図しないファイル変更など）がないかまとめ：監視設計はAIエージェントの「安全装置」
\nAIエージェントを本番環境で安定稼働させるためには、コードを書く能力と同じくらい「自分の状態を監視する能力」が重要です。そしてその能力は、CLAUDE.mdに適切な監視指針を記述することで初めて与えられます。
\nエージェントが無限ループに陥っても、コストが爆発しそうになっても、出力品質が劣化しても——問題を自ら検知して報告・停止できるエージェントは、開発者にとって圧倒的に安心して使えるツールになります。
\nCLAUDE.mdの設計パターンについてさらに深く学びたい方は、体系的に整理された実践ガイド「CLAUDE.md設計パターン — AIエージェントを思い通りに動かす実践ガイド」をご覧ください。異常検知以外にも、セキュリティ設計・マルチエージェント構成・MCP連携など、本番運用で必要な設計パターンが網羅されています。
\nまた、エラーからの自律回復についてより詳しく知りたい場合はAIエージェントの自己修正能力とCLAUDE.md設計パターンも参考にしてみてください。
\n\n- \n
- AIエージェントは「静かに壊れる」ため、能動的なモニタリング設計が必須 \n
- CLAUDE.mdに「検知条件・通知方法・対処行動」の3ブロックで監視規則を記述する \n
- ループ検知・コスト上限・出力品質の3観点がモニタリングの基本 \n
- Hooksと組み合わせた二層構造（CLAUDE.md＋外部スクリプト）が堅牢な監視体制を実現 \n
- 監視条件は曖昧な表現を避け、具体的な数値で定量的に記述することが重要 \n