Hook Enforcement System

LLMの記憶に依存しない物理的プロセス強制。シェルスクリプトがコンテキスト劣化を補完する。

Why Hooks?

LLMの注意力はコンテキストが長くなるほど劣化する。CLAUDE.mdに書かれたルールは「お願い」に過ぎず、長いセッションの後半では無視される可能性がある。

Hookはシェルスクリプトによる物理的な強制層であり、LLMの状態に関係なくプロセス遵守を保証する。

⚠
CLAUDE.mdのルールは「お願い」。Hookは「法律」。

ルールはLLMが読んで「覚えている限り」従うもの。Hookはコマンド実行前に物理的にチェックし、違反があればブロックする。記憶に依存しない。

📜

CLAUDE.md（ルール）

LLMが読み込んで理解する。コンテキストが長くなると注意力が低下し、ルールを見落とす可能性がある。

依存: LLMの記憶力
🛡

Hook（物理強制）

シェルスクリプトがコマンド実行前後に自動チェック。LLMの状態に関係なく、違反をブロックまたは警告する。

依存: なし（自律的に動作）

Hook Architecture

Hookには2つのタイミングがある: PreToolUse（ツール実行前）と PostToolUse（ツール実行後）。

🚫

PreToolUse

ツール実行前に発火。denyを返すことでコマンドの実行自体をブロックできる。

💬

PostToolUse

ツール実行後に発火。メッセージの出力やフラグの作成はできるが、実行自体は止められない。

Hook一覧

Hook イベント 対象ツール 動作 目的
guard.sh PreToolUse Bash ブロック 危険コマンドの物理ブロック（14カテゴリ）
pre-agent-compliance.sh PreToolUse Agent ブロック 義務未完了時のAgent起動ブロック + ハートビート更新
post-agent-checklist.sh PostToolUse Agent フラグ作成 Orchestrator完了後のチェックリストリマインド + ハートビート更新
validate-rules.sh PostToolUse Edit/Write 警告 rules.yaml変更時のYAML構文・必須フィールド検証
open-pr.sh PostToolUse Bash 自動化 PR作成後のブラウザ自動オープン

guard.sh

最も重要なHook。14カテゴリの危険コマンドを物理的にブロックする。LLMがどのような指示を受けても、これらのコマンドは実行されない。

🚫
例外なし

guard.shがブロックするコマンドに例外はない。「今回だけ」「テストだから」は通用しない。回避が必要な場合はHook自体の修正が必要。

ブロック対象（14カテゴリ）

1 gh pr merge PRマージ禁止。マージはユーザーが手動で行う
2 git push --force 履歴の強制上書き禁止
3 git reset --hard 作業内容の破壊的リセット禁止
4 git merge main mainブランチの直接マージ禁止
5 rm -rf / システムファイルの再帰削除禁止
6 DROP DATABASE データベースの破壊的操作禁止
7 git config --global グローバルGit設定の変更禁止
8 ngrok / cloudflared トンネルサービスの起動禁止
9 curl | sh リモートスクリプトの直接実行禁止
10 chmod 777 過剰な権限付与禁止
11 /dev/ 書き込み デバイスファイルへの直接書き込み禁止
12 SSH / SCP リモート接続・ファイル転送禁止
13 Projects外の再帰削除 プロジェクト外ディレクトリの再帰削除禁止
14 .obligations-pending操作 義務フラグの手動操作禁止（自動管理のみ）

Obligation System

Orchestrator完了後にmemoとtoken-usage.yamlの記録を強制する仕組み。Hookが義務フラグを作成し、記録が完了するまで次のAgent起動をブロックする。

1
Orchestrator Agent 完了
Orchestratorがフェーズグループの実行を完了する。
2
post-agent-checklist.sh が検出
.claude/hooks/.obligations-pending にタイムスタンプを記録する。PO完了後チェックリストのリマインドを出力。
3
POがmemo・token-usage.yamlを更新
Session Managerを起動し、記録を委譲する。
4
次のAgent起動時にチェック
pre-agent-compliance.sh が両方の更新を確認。完了済みならフラグ解除・Agent起動許可。未完了ならdenyでブロック。
💡
フラグ作成の対象

義務フラグを作成するのはOrchestrator完了時のみ。Explore、Plan、Session Managerなどの補助的なAgent完了時にはフラグは作成されない。

🕐
1時間自動クリア

フラグが1時間以上古い場合はセッション跨ぎとみなし自動クリアされる。前セッションの義務が次セッションをブロックし続けることを防ぐ。

Heartbeat System

複数のClaude Codeスレッドが同時に動作することを検出するための機構。Agent起動前後にハートビートファイルを更新する。

ハートビートファイル 
# Agent 起動前 (pre-agent-compliance.sh)
echo "$(date +%s)" > .claude/sessions/.heartbeat-${PPID}

# Agent 実行中...

# Agent 完了後 (post-agent-checklist.sh)
echo "$(date +%s)" > .claude/sessions/.heartbeat-${PPID}

スレッド判定ロジック

Session Manager起動 ➔ check-active-sessions.sh ➔ 全 .heartbeat-* スキャン ➔ kill -0 で PID生存チェック
条件 判定 アクション
PID生存 + in_progressセッション Active 「別スレッドで稼働中」と報告
PID死亡 Dead ハートビート削除、中断タスクとして扱う
ハートビート2時間超 Stale 自動クリア、中断タスクとして扱う

rules.yaml Validation

validate-rules.sh は governance/rules.yaml の編集後に自動的に構文と構造を検証する。

検証項目

📄

YAML構文

YAMLとしてパース可能かを確認。構文エラーは即座に警告。

🗃

必須セクション

gates または process_rules セクションの存在を確認。

☑

必須フィールド

process_rules の各エントリに id, description, severity が存在すること。gates の各エントリに id, description が存在すること。

⚠
検証エラー時

警告メッセージが出力される。即座に修正すること。不正なrules.yamlはゲートチェックの正常動作を妨げる可能性がある。

PR Auto-Open

open-pr.sh は gh pr create コマンドの実行後にPR URLをブラウザで自動的に開く。PRの内容確認をスムーズにするための利便性Hook。

gh pr create 実行 ➔ open-pr.sh 検出 ➔ PR URL 抽出 ➔ ブラウザで自動オープン

Future Vision

現在の改善サイクルは「ルール追加 → LLMが読む → 適用」だが、将来的にはHookと統合することで、学んだことが忘れられない組織を実現する。

STEP 1
問題発生
プロセス違反やエラーを検出
STEP 2
改善レポート作成
Secretaryが原因分析と対策を文書化
STEP 3
ルール + Hook追加
rules.yamlにルール追加 + 対応するHookを実装
STEP 4
自動強制
次回以降、LLMの記憶に依存せず物理的に強制
🌱
学んだことが忘れられない組織

問題が発生するたびにHookが追加される。組織は経験を蓄積し、同じ失敗を二度と繰り返さない。LLMのコンテキスト長やセッション境界に制約されない、真の組織的学習を実現する。