イベント駆動AIエージェント — ファイル変更・メッセージ・時間をトリガーに

ポーリングで定期的にチェックするのではなく、イベントが発生した瞬間にAIが動く。Claude Code HooksとOS標準機能を組み合わせたイベント駆動設計を実装する。

イベントトリガー一覧

トリガー種別	発火タイミング	主な用途
`PreToolUse`	ツール実行前	危険操作のブロック
`PostToolUse`	ツール実行後	結果の検証・ログ記録
`Notification`	通知発生時	外部通知への転送
`Stop`	エージェント停止時	完了報告・クリーンアップ
`SubagentStop`	サブエージェント停止時	子タスク完了の集約

Hooks設定の具体例

.claude/settings.json に以下のように定義する。

ファイル変更検知でテスト自動実行

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "python scripts/auto_test.py",
        "timeout": 30000
      }
    ]
  }
}

WriteまたはEditツールが実行されるたびに、変更されたファイルに対応するテストを自動実行する。

危険コマンドのブロック

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "command": "python scripts/guard.py",
        "timeout": 5000
      }
    ]
  }
}

guard.pyはstdinからツール入力をJSON受け取りし、rm -rfやgit push --forceを含む場合にexit code 2で拒否する。

完了時にDiscord通知

{
  "hooks": {
    "Stop": [
      {
        "command": "python scripts/notify_discord.py",
        "timeout": 10000
      }
    ]
  }
}

イベント駆動 vs ポーリングの判断基準

条件	イベント駆動	ポーリング（cron）
リアルタイム性が必要	適切	不適切
外部APIの変更検知	不可（Webhookなければ）	適切
ファイルシステム変更	適切（Hooks/watchdog）	冗長
定時バッチ処理	不適切	適切
コスト最適化	発火時のみ課金	定期課金

cronとの組み合わせパターン

イベント駆動だけでは拾えないケースはcronで補完する。

# 1時間ごとにクラウドソーシングサイトをスクレイピング
0 * * * * cd /path/to/project && python bot/scraper.py

# 15分ごとに受注チェック
*/15 * * * * cd /path/to/project && python bot/order_check.py

watchdog.pyによるファイル監視

Pythonのwatchdogライブラリで特定ディレクトリを監視し、変更があればClaude Codeを起動する。

from watchdog.observers import Observer
from watchdog.events import FileSystemEventHandler
import subprocess

class TaskFileHandler(FileSystemEventHandler):
    def on_modified(self, event):
        if event.src_path.endswith("current_task.json"):
            subprocess.run([
                "claude", "-p",
                "current_task.jsonが更新された。内容を確認して実行せよ。"
            ])

observer = Observer()
observer.schedule(TaskFileHandler(), path="./", recursive=False)
observer.start()

設計のベストプラクティス

Hookのタイムアウトは短めに設定する: 長時間Hookは操作体験を損なう
guard系Hookはexit code 2で拒否する: exit 0は許可、exit 2はブロック
通知Hookは非同期にする: バックグラウンド送信で本体処理をブロックしない
ログを必ず残す: イベント発火時刻・内容・結果をファイルに記録する

イベント駆動設計により、AIエージェントは「聞かれたら答える」存在から「変化を察知して動く」自律エージェントに進化する。