Claude Codeのhooks機能を超える：カスタムイベント設計でワークフローを自在に制御する実践テクニック

Claude Codeを実務で使い込んでいくと、必ず直面する壁があります。それは**「hooks機能のイベントタイミングが、自分のやりたいことと微妙にズレる」**という問題です。

ソニックガーデンのプログラマが指摘しているように、`Stop`や`PreToolUse`といった既存のhooksイベントは確かに便利ですが、これらはあくまで「Claude Code自身のライフサイクル」に紐づいています。つまり、AIツール側の都合でタイミングが決まっているため、開発者が本当に処理を挟みたい瞬間とは一致しないケースが頻発するのです。

例えば、「特定のファイルを編集した直後」「テストが失敗したタイミング」「コードレビュー前の最終チェック時」など、**開発フロー上の論理的な区切り**でフックを発火させたい場合、既存の仕組みでは対応できません。

投稿で提案されているのが、**ワークフローをTodoリストとして設計する**アプローチです。この手法は、AI主導のライフサイクルから脱却し、開発者が主体的にイベントタイミングを定義できる点で画期的です。

従来のhooks設計では「AIがいつ何をするか」を軸に考えていましたが、Todoベースでは「開発タスクのどの段階で何を確認・実行するか」を軸にします。これにより、以下のような柔軟な制御が可能になります：

この設計思想は、AIコーディングツールを「指示を受けて動く自律エージェント」ではなく、**「開発ワークフローに組み込まれた協働ツール」**として捉え直すものです。

GitHub CopilotやCursorとの比較

GitHub Copilotは主にコード補完に特化しており、ワークフロー制御の概念自体が希薄です。一方、Cursorはファイル編集やコマンド実行のタイミングでイベントをトリガーできますが、やはりツール側が定義したイベントに依存します。

Claude Codeのhooks機能も同様の制約を持っていますが、**Todoベース設計を導入することで、これらのツールにはない「ビジネスロジックレベルでの制御」が可能**になります。特に、複数のステップを経る複雑な開発タスクや、チーム間での承認プロセスが必要な場合に威力を発揮します。

メリットと注意点の両面分析

**メリット：**

**注意点：**

適用が特に効果的なケース

1. **マイクロサービス開発**：API実装→テスト→ドキュメント更新という一連の流れを自動化したい場合

2. **レガシーコードのリファクタリング**：段階的な書き換えで、各ステップごとに動作確認が必須な場合

3. **コンプライアンス要件の厳しいプロジェクト**：各工程で監査ログやレビュー記録を残す必要がある場合

逆に、単純なコード補完や一度きりのスクリプト作成には、設計コストに見合わない可能性があります。

1. 既存タスクをTodo化して可視化する

まずは普段の開発フローを書き出し、Todoリストに分解してみましょう。例えば：

- [ ] ユーザー認証APIのエンドポイント実装
- [ ] 入力バリデーションの追加
- [ ] ユニットテストの作成
- [ ] API仕様書の更新
- [ ] セキュリティレビュー依頼

これを見ながら、「どのタイミングでClaude Codeに何をさせたいか」を考えます。

2. シンプルなトリガースクリプトを作成する

Todo完了時に特定のコマンドを実行する軽量なスクリプトから始めましょう。例えば、Todoファイルの変更を監視し、チェックマークが付いたら次のアクションを実行する仕組みです：

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

class TodoHandler(FileSystemEventHandler):
    def on_modified(self, event):
        if event.src_path.endswith('TODO.md'):
            # Todoの完了状態をチェックし、対応するhookを実行
            check_and_trigger_hooks()

3. Claude Codeのプロンプトに「Todo確認ステップ」を組み込む

Claude Codeに指示を出す際、明示的に「現在のTodoリストを確認し、完了したタスクに応じて次のアクションを提案してください」と依頼します。これにより、AI自身がワークフローを意識した動作をするようになります。

この情報は @hiropon さんの投稿を参考にしています。