AIエージェントの異常検知・モニタリングをCLAUDE.mdで設計する実践ガイド

AIエージェントは「静かに壊れる」——監視なき自動化の危険性

AIエージェントを本番環境に投入した直後は順調に動いていたのに、気づいたらAPIコストが10倍に膨れ上がっていた。あるいは、エージェントが無限ループに陥ったまま数時間動き続けていた——そんな経験をした開発者は少なくないはずです。

従来のソフトウェアはエラーが出れば例外をスローして止まります。しかしLLMベースのAIエージェントは「失敗してもそれっぽい出力を返し続ける」という特性があります。エラーログには何も残らないまま、実は期待した動作をまったくしていない、という事態が発生しやすいのです。

この記事では、CLAUDE.mdに異常検知・モニタリングの仕組みを設計・組み込むことで、AIエージェントの問題を早期発見し、安定稼働を維持するための実践パターンを紹介します。CI/CDや自己修正の観点についてはAIエージェント開発を加速するCI/CD実践ガイドも参照してください。

なぜCLAUDE.mdにモニタリングを書くのか

CLAUDE.mdはAIエージェントへの「指示書」です。コーディング規約やワークフロー手順だけでなく、エージェントが自分自身の動作を監視・評価するための基準を記述できます。これにより次の3つの効果が得られます。

• 自己診断の基準が明示される：エージェントは何が「正常」で何が「異常」かを文脈として持てる
• 異常時の行動規範が統一される：ログ出力・アラート・処理停止のタイミングがブレない
• チームで共有できる監視仕様になる：暗黙知だったモニタリングルールがドキュメント化される

CLAUDE.mdがないと何が起きるか

CLAUDE.mdに監視指針がない場合、エージェントは「とにかく完遂しようとする」デフォルト動作を取ります。ループが300回に達しても、コストが上限を超えても、出力品質が著しく低下しても——止まる理由を知らないため動き続けます。結果として、開発者が翌朝ダッシュボードを見て初めて異常に気づく、という後手後手の対応になりがちです。

監視設計をCLAUDE.mdに入れる基本構造

CLAUDE.mdのモニタリングセクションは、大きく「検知条件」「通知方法」「対処行動」の3ブロックで構成するのが実践的です。

「AIエージェントの指示書に監視ルールを書く」というアイデアは奇妙に聞こえるかもしれませんが、自律的なシステムが自分の健全性を評価できるかどうかは、与えられた文脈次第です。

異常検知パターン：CLAUDE.mdに書くべき3つの監視観点

1. ループ・繰り返し検知

AIエージェントが最も陥りやすい問題の一つが「同じアクションを繰り返す無限ループ」です。CLAUDE.mdには以下のような指針を明示します。

## モニタリング規則

### ループ検知
- 同一ツール呼び出しが連続5回以上発生した場合、処理を一時停止してユーザーに確認を求める
- 同じエラーメッセージが3回連続した場合は「再試行ループ」と判断し、別アプローチを試みるか停止する
- タスク開始から30分経過しても完了しない場合、進捗サマリをログに出力して継続可否を問う

このルールがあることで、エージェントは自分がループしていることを「認識できる」状態になります。認識できれば、報告・停止・代替手段の試行といった適切な対処が可能になります。

2. コスト・リソース上限の監視

LLM APIのコストはトークン数に比例します。エージェントが大量のドキュメントを読み込み続けたり、長大なコンテキストを積み上げたりすると、1タスクで予期せぬ高額請求が発生することがあります。

### リソース監視
- 1タスクで使用するファイル読み込みは最大20ファイルまで。超える場合は優先度の高いものに絞る
- ツール呼び出しの総回数が50回を超えたら警告ログを出力し、ユーザーに残タスクを確認する
- 外部APIへのリクエストは1分間に10回以内。超過しそうな場合はバッチ処理を検討する

3. 出力品質の自己評価

AIエージェントは「それらしい」出力を生成し続けます。しかし品質が著しく低下していても気づかないことがあります。CLAUDE.mdに品質チェックの基準を書いておくことで、エージェントが自分の出力を評価する軸を持てます。

### 品質チェック
- コード生成タスクの場合、生成後に必ずlint/typeチェックを実行する
- テスト生成タスクでは、テストが実際にパスするか確認してから完了報告する
- 曖昧な要件でタスクを開始する前に、具体的な完了条件を確認する

Hooksと組み合わせたイベント駆動モニタリング

CLAUDE.mdの指針だけでなく、Claude CodeのHooks機能を組み合わせることでより堅牢な監視体制が構築できます。HooksはAIエージェントのツール呼び出し前後に任意のシェルコマンドを実行できる仕組みです。

ツール呼び出し前の安全チェック

たとえば、PreToolUseフックを使うと、エージェントが破壊的なコマンド（rm -rfやDROP TABLEなど）を実行しようとした瞬間にインターセプトできます。

# settings.json の例
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{
          "type": "command",
          "command": "echo '$CLAUDE_TOOL_INPUT' | python3 scripts/safety_check.py"
        }]
      }
    ]
  }
}

ツール呼び出し後のログ収集

PostToolUseフックを活用すると、エージェントの全ツール呼び出し履歴を自動的にログファイルに記録できます。これにより、問題発生後の事後調査（ポストモーテム）が格段に楽になります。

# 呼び出し回数カウンタの例
#!/bin/bash
TOOL_COUNT_FILE="/tmp/claude_tool_count"
count=$(cat "$TOOL_COUNT_FILE" 2>/dev/null || echo 0)
new_count=$((count + 1))
echo $new_count > "$TOOL_COUNT_FILE"
if [ $new_count -gt 50 ]; then
  echo "WARNING: Tool call count exceeded 50 ($new_count calls)" >&2
fi

CLAUDE.mdとHooksの役割分担

観点	CLAUDE.md	Hooks
制御主体	AIエージェント自身	外部シェル
得意なこと	判断・文脈理解・代替手段提案	確実な遮断・ログ記録
見落としリスク	LLMが指示を無視する可能性あり	ほぼゼロ（決定論的）
柔軟性	高い（自然言語で複雑な条件記述可）	低い（シェルスクリプトの範囲内）

重要な安全制約はHooksで確実に担保し、判断が必要な監視ルールはCLAUDE.mdで担うという二層構造が理想的です。

本番運用で役立つモニタリングCLAUDE.mdテンプレート

以下は、実際の本番環境で使えるモニタリングセクションのテンプレートです。プロジェクトの規模や性質に応じてカスタマイズしてください。

## 異常検知・モニタリング規則

### 自己診断チェックリスト（タスク開始時）
- [ ] タスクの完了条件は明確か？曖昧な場合はユーザーに確認する
- [ ] 必要なファイルやAPIへのアクセス権はあるか？
- [ ] 推定ステップ数は妥当か？10ステップを超えるなら分割を検討する

### 異常パターンと対処
| 検知条件 | 判断 | アクション |
|---|---|---|
| 同一エラーが3回連続 | 再試行ループの疑い | 別アプローチを提案してユーザーに選択を求める |
| ツール呼び出し50回超過 | タスク肥大化 | 現在の進捗を報告して継続可否を確認 |
| ファイル読み込み20件超過 | スコープ拡大 | 優先度の低いファイルを除外してリスタート |
| 30分以上経過 | タイムアウト予兆 | 現状サマリを出力して指示を仰ぐ |

### アラート出力形式
異常を検知した場合、以下の形式でログ出力する:
```
[CLAUDE-ALERT] {timestamp} | 検知: {anomaly_type} | 詳細: {description} | 推奨アクション: {action}
```

### 正常終了の確認
タスク完了時には以下を確認してから「完了」を報告する:
1. 期待した出力・成果物が存在するか
2. テスト・lintが通っているか（コードタスクの場合）
3. 副作用（意図しないファイル変更など）がないか

まとめ：監視設計はAIエージェントの「安全装置」

AIエージェントを本番環境で安定稼働させるためには、コードを書く能力と同じくらい「自分の状態を監視する能力」が重要です。そしてその能力は、CLAUDE.mdに適切な監視指針を記述することで初めて与えられます。

エージェントが無限ループに陥っても、コストが爆発しそうになっても、出力品質が劣化しても——問題を自ら検知して報告・停止できるエージェントは、開発者にとって圧倒的に安心して使えるツールになります。

CLAUDE.mdの設計パターンについてさらに深く学びたい方は、体系的に整理された実践ガイド「CLAUDE.md設計パターン — AIエージェントを思い通りに動かす実践ガイド」をご覧ください。異常検知以外にも、セキュリティ設計・マルチエージェント構成・MCP連携など、本番運用で必要な設計パターンが網羅されています。

また、エラーからの自律回復についてより詳しく知りたい場合はAIエージェントの自己修正能力とCLAUDE.md設計パターンも参考にしてみてください。