CLAUDE.mdが無視される原因とPreToolUseフック|AWS「CAO」60秒停止の回避術
作成日:
更新日:

CLAUDE.mdが無視される原因とPreToolUseフック|AWS「CAO」60秒停止の回避術

IT・Mac・AI実践

論旨
  • 第1層:手順書(CLAUDE.md・AGENTS.md・SKILL.md)はあくまでコンテキスト上の「お願い」 :稼働イベント 1,924件(ツール呼び出し 1,431件 )の実測記録が示す通り、長時間の開発で会話の自動要約が走ると、どれほど丁寧に書いた常設ルールも抜け落ちます。「絶対に破らせてはいけない禁止事項」を手順書だけで守らせる設計は構造的に破綻します。

  • 第2層:危険操作の遮断は PreToolUse フック(終了コード 2 )の「機械の関所」へ分離する :ツール実行直前に別プロセスで介入し、終了コード 2(exit 2)と標準エラー出力(stderr)を返すことで、従量課金キーの参照や検査スキップの commit を物理的に拒否できます。ただしスクリプトの未処理例外(終了コード 1 等)は呼び出しを素通りさせる フェイルオープン(Fail-Open) になるため、厳密な構造化パースが必須です。

  • 第3層・第4層:並列委任CLI「CAO」の60秒停止を防ぎ、フック関所・判定AIと多層統合する :tmux 上で複数の Claude Code ワーカーへ並列委任できる AWS 公式 cli-agent-orchestrator(CAO)は、裏で権限確認スキップを強制する一方、① Windows 共有フォルダ上の名前付きパイプ失敗(Errno 95)、② Ubuntu ログイン文字列("Welcome to")への 0.33秒誤一致 によるフォルダ信頼確認の 60秒タイムアウト停止 、③ ~/.claude/settings.json の危険モード確認スキップ自動書き換えという3つの罠を抱えています。事前承認と ~/.hushlogin で停止を根絶しつつ、PreToolUse 関所と判定専用AI・前提確認PASで暴走を抑える「4層ガードレール設計」が自律運用の決定打です。

合わせて読みたい深まる関連情報
この記事の対象となる方
  • CLAUDE.md や AGENTS.md に「勝手にコミットしない」「秘密鍵を読まない」「日本語で返答する」と書いたのに、会話が長くなると無視されて困っている開発者の方

  • Claude Code の PreToolUse フックを使って危険なコマンドを確実に止めたいものの、シェルスクリプトの例外処理(フェイルオープン)や誤検知(echo への過剰反応・短縮オプション見逃し)で悩んでいる方

  • AWS Labs 公式のマルチエージェントCLI「CAO(cli-agent-orchestrator)」で Claude Code を並列稼働させた際、Claude Code initialization timed out after 60s や Errno 95 で止まる問題と、権限スキップ時の暴走リスクを同時に解決したい方

AIコーディングエージェントを実務に投入すると、最初はルール通りに動いていたはずなのに、数十分後の長いセッションで突然「検査抜きで勝手に git commit -n を打たれた」「触ってはいけない環境変数を読み出された」というヒヤリハットに必ず直面します。

さらに一歩進んで、AWS Labs が公開しているマルチエージェント統括CLI「CAO(cli-agent-orchestrator)」などを使い、tmux 上で複数の Claude Code ワーカーに並列でタスクを委任しようとすると、問題はさらに先鋭化します。バックグラウンドの無人ワーカーが対話プロンプトで止まらないよう権限確認スキップ(--dangerously-skip-permissions)を有効にした途端、「初期ダイアログでの60秒タイムアウト停止」や「全体設定ファイルの勝手な書き換え」、そして「タガが外れたワーカーによる禁止操作の素通り」が一気に牙をむくからです。

つまり、「単体エージェントが CLAUDE.md を無視する問題」と「マルチエージェント(CAO)が60秒停止・権限スキップ暴走を起こす問題」は別々の話ではなく、『Claude Code の自律・並列運転を1秒も止めず、かつ絶対に暴走させない多層ガードレール(機械の関所)をどう設計するか』という単一のアーキテクチャ課題 なのです。

今回は、稼働イベント 1,924件 の一次計測記録と、AWS公式「CAO」の実機デバッグ記録、さらに判定専用AI・前提確認PASの検証データをもとに、第1層(手順書の限界理解)→ 第2層(PreToolUse 関所による物理遮断)→ 第3層(CAO並列委任の非対話開通と設定保護)→ 第4層(判定専用モデルと前提絞り込み) からなる4層ガードレール設計を徹底解説します。


手順書はお願いでフックは決まりという決定的な差

多層ガードレールの第1層として押さえるべき核心は、CLAUDE.md や AGENTS.md にどれほど強い言葉で「〜を禁止する」と書いても、システム上はAIへの「お願い(プロンプトの一部)」に過ぎず、実行を100%止める強制力は一切ない という事実です。

解説ナビゲーター

えっ、CLAUDE.md に「--no-verify でのコミットは絶対禁止」「有料APIキーの環境変数は表示しないこと」って太字で書いておけば、Claude Code は守ってくれるんじゃないんですか?

質問するおじさん

そこが一番危ない思い込みなんだよ。手順書はあくまでLLMのコンテキストウィンドウに流し込まれる「テキスト」でしかない。実際に稼働ログを1,900件以上計測した一次データを見ると、なぜ手順書だけでは単体運転でも並列委任でも事故を防げないのかがはっきり分かるぞ。

稼働イベント1,924件で見えた3大指示書の限界

AIエージェントに作業方針や手順を伝える代表的なファイルとして、現在は CLAUDE.md 、AGENTS.md 、SKILL.md の3つが広く使われています。Zenn「手順書は『お願い』、フックは『決まり』——CLAUDE.md・AGENTS.md・SKILL.md と、機械で断る関所を自分の記録で比べる」では、2026年11月12日〜14日(UTC)の3日間にわたる自身の稼働イベント記録 1,924件(そのうちツール呼び出し 1,431件 )をもとに、これら3つの指示書とフックの役割の違いが克明に分析されています。

まず、3つの指示書の仕様と位置づけを正確に整理しておきましょう。

📋 エージェントを制御する3大指示書の仕様と役割
  • CLAUDE.md(プロジェクト・ユーザー常設指示書) :Claude Code のセッション開始時に自動でコンテキストへ読み込まれるMarkdown文書です。リポジトリ固有のビルド手順、コーディング規約、常設の振る舞い(「返答は日本語で行う」など)を記述します。

  • AGENTS.md(エージェント横断の標準手順書) :特定のツールに依存しない共通手順書フォーマットです。MCP(Model Context Protocol)や goose とともに、Linux Foundation 傘下の Agentic AI Foundation 創設プロジェクトの1つとして標準化が進められており、複数のAIコーディングツールを併用する現場で採用されています。

  • SKILL.md(タスク特化型の段階的スキル定義) :普段は名前と概要だけをエージェントに知らせ、該当タスクが発生した時だけ本文を読み込ませる仕組みです。agentskills.io 形式のフロントマター仕様では、name は 1〜64文字の英小文字・数字・ハイフン(親フォルダ名と完全一致が必須)、description は 1〜1024文字 、環境要件を示す compatibility は 500文字以内 と厳密に定義されています。

これら3つは読み込みのタイミングや標準化団体こそ異なりますが、「最終的にLLMのコンテキスト(入力トークン)として渡される自然言語の文章である」 という点では完全に同じです。

会話の自動要約で常設ルールが抜け落ちる仕組み

なぜコンテキストに入ったはずのルールが破られるのでしょうか。最大の障壁(ボトルネック)は、長時間のセッションで発生する コンテキストの自動要約(Compaction) です。

ファイルの読み書きやテスト実行を何十回も繰り返してコンテキスト上限に近づくと、エージェントは過去の会話履歴を自動的に圧縮・要約して空き容量を作ります。前述の稼働イベント1,924件の計測記事でも、長い会話が要約された直後に、CLAUDE.md に書いてあったはずの「返事は日本語で」といった常設ルールが抜け落ち、急に英語で出力し始める現象 が記録されています。

手順書(お願い)とフック(決まり)の決定的な構造差
お願い(確率的)
CLAUDE.md / AGENTS.md / SKILL.md

LLMのコンテキストに入る自然言語テキストです。作業の段取りやコーディング作法を伝えるには最適ですが、長文セッションの自動要約(Compaction)や目の前のエラー解消への集中によってルールが抜け落ちる ため、危険操作の100%遮断は不可能です。

決まり(決定論的)
PreToolUse フック / 漏えい検査ゲート

ツールが実行される直前にOS側で別プロセスとして起動する「機械の関所」です。LLMの記憶や気分に一切左右されず、終了コード 2 を返した瞬間にツール実行を物理的に遮断 し、標準エラー出力(stderr)でAIに差し戻し理由を突きつけます。

つまり、「こういう手順でテストを書いてほしい」という 段取りの案内 には CLAUDE.md や SKILL.md が向いていますが、「従量課金キーを絶対に読ませない」「検査抜きコミットを絶対に許さない」という 保安上の境界線 を手順書に頼るのは、ブレーキのない車を声かけだけで止めようとするのと同じなのです。


PreToolUseフックで危険操作を遮断する設計術

第1層の手順書が「自動要約で抜け落ちる」以上、長時間セッションや後述するマルチエージェント並列稼働を安全に回すには、第2層としてAIの記憶に依存しない「機械の関所」を置く必要があります。その中核を担うのが Claude Code の PreToolUse フック です。

なお、PreToolUse フックを「巨大ファイルの Read 丸読み防止・出力10KB切り詰め回避・SQLite全文検索(FTS5)への誘導」という トークン節約・I/O最適化 に使う手法については、姉妹記事「AIコーディングのファイル丸読み遮断術|Read禁止フックと出力10KB切り詰め回避設計」で詳しく解説しています。本記事では、それと対をなす 「危険コマンド・秘密鍵漏えいの物理遮断とフェイルオープン防止」 の実装に焦点を当てます。

終了コード2による拒否と標準エラー出力のフィードバック

Anthropic公式ドキュメント「Hooks reference - Claude Code Docs」で定義されている通り、Claude Code のフック機構では、エージェントが Bash や Read、Edit などのツールを呼び出そうとした直前に、指定した外部スクリプトやバイナリを実行できます。このとき、フック側が返す 終了コード(Exit Code) によって挙動が厳格に分かれます。

🚦 PreToolUse フックの終了コード仕様と実測遮断データ
  • 終了コード 0(通行許可) :ツール呼び出しを安全とみなし、そのまま実行を通します。

  • 終了コード 2(強制拒否・AIへの差し戻し) :公式仕様における「ブロッキングエラー」です。ツール呼び出しを即座に中止し、さらにフックスクリプトが 標準エラー出力(stderr)に書き出したメッセージをそのまま Claude Code 本体のコンテキストへ突き返し 、「なぜ拒否されたのか、代わりにどう行動すべきか」をエージェントに強制認識させて自律的に軌道修正させます。

  • その他の非ゼロ終了コード(1 等:ノンブロッキング警告=素通り) :公式の Hooks リファレンスで特に注意すべき仕様として、終了コード 2 以外のエラー(exit 1 や未処理例外によるクラッシュ)は「ノンブロッキングエラー」として扱われ、ユーザー画面にエラーを表示するだけで ツールの実行自体はブロックされずそのまま通過 します。

  • 1,431回のツール呼び出しにおける実測遮断実績 :稼働記録1,924件の検証データでは、ツール呼び出し1,431回のうち 2回 がこの PreToolUse(終了コード 2)によって未然にブロックされています。内訳は 「従量課金APIキーが入った環境変数の参照(1件)」 と 「事前検査を飛ばす git commit(1件)」 です。さらに公開前のシークレット漏えい検査でも、125回の実行中 6回 を終了コード 1 で確実に停止させています。

1,431回のうちたった2回と思うかもしれませんが、セキュリティ事故や高額課金キーの露出は 「たった1回の素通り」で致命傷 になります。その1〜2回の逸脱を機械的に100%拾い上げ、しかも人間が介入することなく stderr 経由でAI自身にやり直させられることこそが、フックを置く最大の価値です。

単純な文字列照合の死角とフェイルオープン対策

ここで読者の方が実際に PreToolUse フックを自作する際、必ずぶつかる 3つの技術的ツッコミどころ(落とし穴) に先回りして回答しておきます。

解説ナビゲーター

なるほど!じゃあシェルスクリプトで実行コマンドの文字列を受け取って、grep "--no-verify" に引っかかったら exit 2 する数行のスクリプトを書けば完璧ですね!

質問するおじさん

ちょっと待った!その「単純な文字列照合スクリプト」こそが、現場で一番事故を起こす原因なんだ。短縮オプションの抜け道、メッセージ文字列への誤爆、そして先ほど公式仕様で確認した「フェイルオープン(例外時の exit 1 による素通り)」の3つを潰さないと関所にならないぞ。

前述の実測記事でも、素朴な文字列検査フックが抱える弱点が率直に指摘されています。実務で関所を作る際は、以下の3点を必ず対策してください。

🛡️ フック実装で絶対に潰すべき3つの死角
  1. 短縮オプション(-n 等)の見逃し :git commit --no-verify という文字列だけを監視していると、AIが git commit -n -m "fix" と短縮フラグで呼び出した際に1バイトも引っかからず素通りしてしまいます。コマンドライン引数をトークン単位に分解し、-n や複合フラグ(-am 等と並んだ指定)まで構文として検査する必要があります。

  2. echo やコミットメッセージ内の文字列への過剰反応(誤爆) :コマンド全文を単純に部分一致検索すると、AIが git commit -m "--no-verify を禁止するフックを追加" や echo "ANTHROPIC_API_KEY の設定方法" と出力しただけで危険操作と誤判定し、作業が前に進まなくなります。実行される「先頭コマンド本体」と「引数・リテラル文字列」を構造化して切り分ける設計が不可欠です。

  3. 未処理例外によるフェイルオープン(Fail-Open:素通り) :これが最も危険な仕様です。Claude Code 公式 Hooks 仕様の通り、フックスクリプトの途中で JSON のパースエラーや未定義変数参照などの未処理例外が発生し、終了コード 2 以外のコード(Python の未捕捉例外による exit 1 等)で異常終了した場合、ツール呼び出しが拒否されずそのまま通ってしまう(フェイルオープンになる) ため、例外ハンドラで明示的に exit 2 へ倒す設計が必須です。

フェイルオープンを防ぎ、かつ毎回のツール呼び出し(数千回規模)で遅延を一切感じさせないためには、シェルスクリプトの場当たり的な正規表現ではなく、標準入力から渡される JSON(tool_name と tool_input)を厳密にパースし、万が一のパース失敗時も必ず安全側(exit 2 による遮断と明示的なエラー通知)に倒す堅牢なプログラム で実装するのが定石です。

Python で書く場合は最外殻を try ... except Exception: で囲んで異常時の挙動を固定し、さらに当ラボのように月間数万回のツール呼び出しをミリ秒単位でさばく場合は、メモリ安全で未処理例外によるランタイムクラッシュが起きない Rust 製の単一ネイティブバイナリ にコンパイルしてフックに据える手法が極めて有効です。

#!/usr/bin/env python3
# ~/.claude/hooks/pre_tool_guard.py
import json
import shlex
import sys

def deny(reason: str) -> None:
    sys.stderr.write(f"[PreToolUse 関所ブロック] {reason}\n")
    sys.exit(2)

def main() -> None:
    try:
        payload = json.load(sys.stdin)
    except Exception as e:
        # パース失敗時に素通り(フェイルオープン)させないよう明示的に終了コード2で止める
        deny(f"フック入力JSONの解析に失敗したため安全側で遮断しました: {e}")

    tool_name = payload.get("tool_name", "")
    tool_input = payload.get("tool_input", {}) or {}

    if tool_name == "Bash":
        cmd_str = tool_input.get("command", "")
        try:
            tokens = shlex.split(cmd_str)
        except ValueError:
            tokens = cmd_str.split()

        # 1. git commit の検査スキップ(--no-verify および短縮 -n)を構造化検知
        if len(tokens) >= 2 and tokens[0] == "git" and tokens[1] == "commit":
            for tok in tokens[2:]:
                if tok == "--no-verify" or tok == "-n" or (tok.startswith("-") and not tok.startswith("--") and "n" in tok[1:]):
                    deny("git commit での検査スキップ(--no-verify / -n)は禁止されています。テストとLintを通してからコミットしてください。")

        # 2. 従量課金キー等の環境変数ダンプを遮断(単純なecho説明文は除外し、変数展開やprintenvを検知)
        forbidden_keys = ("ANTHROPIC_API_KEY", "OPENAI_API_KEY", "AWS_SECRET_ACCESS_KEY")
        for key in forbidden_keys:
            if f"${key}" in cmd_str or f"${{{key}}}" in cmd_str or (tokens and tokens[0] in ("env", "printenv", "set")):
                deny(f"秘密鍵・従量課金キー({key})の直接参照・環境変数ダンプはセキュリティ規定により遮断されました。")

    sys.exit(0)

if __name__ == "__main__":
    main()

このように shlex.split(あるいは Rust の型付きパーサー)でトークンを分解し、JSON 解析エラー時にも sys.exit(2) で安全側に倒すことで、誤爆とフェイルオープンの二律背反(トレードオフ)を同時に解消できます。

Rust でこうした高速・堅牢なCLI関所やシステムツールを自作したい方には、所有権・エラーハンドリング・JSONシリアライズの基本から徹底的に学べる定番書が手元に1冊あると一生モノの武器になります。

オライリー・ジャパン『プログラミングRust 第2版』


AWS公式マルチエージェントCAOの3つの罠と回避策

第2層の PreToolUse フックによって「人間の確認プロンプトに頼らずとも、危険な操作だけを機械的に弾く関所」が完成しました。この関所があって初めて、第3層である マルチエージェントの無人・並列委任 を安全かつ高速に回す土台が整います。

なぜなら、AWS Labs が Apache-2.0 ライセンスで公開している CAO(cli-agent-orchestrator) のようなマルチエージェント統括ツールでは、バックグラウンドの tmux ペインで走る複数の Claude Code ワーカーが権限確認のたびに対話待ちで止まらないよう、起動時に --dangerously-skip-permissions を付与し、さらに設定ファイルで危険モードの確認プロンプトを自動スキップする設計 になっているからです。

つまり、「CAO でワーカーを60秒停止させずに非対話でスムーズに起動させる設定」と「権限スキップでタガが外れたワーカーを第2層の PreToolUse 関所で守る設計」は、必ずセットで導入しなければならない表裏一体の仕組み なのです。

実際に CAO を開発環境(特に WSL2 Ubuntu や新規プロジェクトフォルダ)へ投入すると、ドキュメント通りに設定したはずなのに 「パイプが作れず起動しない」「ワーカーへの委任時に60秒間固まってタイムアウトする」「気づかないうちに全体設定が書き換えられている」 という3つの罠に遭遇します。Zenn「AWS公式のマルチエージェントCLI『CAO』でClaude Codeに仕事を委任させたら、フォルダ信頼確認で60秒止まった」の実機検証データ(CAO 2.5.4、Claude Code CLI 2.1.329、tmux 3.4、WSL2 Ubuntu 24.04.3)をもとに、CAO の内部アーキテクチャと3つの罠の突破手順を解説します。

名前付きパイプ作成失敗Errno95と保存先の分離

まず CAO を uv tool install で導入すると、環境に以下の 4つの実行ファイル が配置されます。

⚙️ CAO(cli-agent-orchestrator)の4大コンポーネントと委任構造
  • cao(メインCLI) :エージェントプロファイルの管理やスーパーバイザーセッションの起動を行うフロントエンドです。

  • cao-server(オーケストレーションサーバー) :ローカルの 127.0.0.1:9889 で待ち受け、tmux セッション/ウィンドウの生成やワーカーの状態管理、SQLite への記録を一手に引き受けるバックエンドです。

  • cao-mcp-server & cao-ops-mcp-server(委任用MCPサーバー) :司令塔となる code_supervisor プロファイル(自身は Write / Edit / Bash などの直接作業ツールがブロックされ、タスク分解と委任に専念する設計)が、developer などのワーカーを別 tmux ウィンドウで立ち上げて仕事を割り振るための MCP ブリッジです。

ここで最初の罠となるのが、WSL2 などで Windows 側と AWS 認証情報を共有するために ~/.aws を Windows ファイルシステム(/mnt/c/Users/.../.aws)へのシンボリックリンクにしている環境 です。

CAO は既定で ~/.aws/cli-agent-orchestrator 配下に設定ファイル、SQLite データベース、ログ、そして tmux ペインの出力を読み取るための名前付きパイプ(FIFO) を作成します。通常のファイルや SQLite は /mnt/c/... 上でも動きますが、Linux 固有の特殊ファイルである mkfifo システムコールだけが Windows ファイルシステム(9P / DrvFs)上で拒否され、[Errno 95] Operation not supported でクラッシュしてしまいます。

# 罠①の回避策:~/.aws 本体(認証情報)はそのままに、CAOのホームディレクトリだけをネイティブLinux側(ext4)へ分離する
export CAO_HOME_DIR=$HOME/.cao-home
mkdir -p "$CAO_HOME_DIR"

~/.bashrc や ~/.zshrc に export CAO_HOME_DIR=$HOME/.cao-home を1行追加するだけで、mkfifo がネイティブファイルシステム上で正常に作成され、このエラーは完全に解消します。

ログイン文字列の誤判定による60秒停止と事前承認

Errno 95 を越えて cao-server と code_supervisor を立ち上げ、いざワーカー(developer)にタスクを委任(handoff / assign)した瞬間に立ちはだかる最大の障壁(ボトルネック)が、Claude Code initialization timed out after 60s(60秒タイムアウト停止) です。

解説ナビゲーター

CAO が裏で Claude Code ワーカーを起動するとき、--dangerously-skip-permissions を付けて起動しているんですよね?それなのに何で画面が止まって60秒タイムアウトしちゃうんですか?

質問するおじさん

そこが二重の罠になっているんだ。実は --dangerously-skip-permissions を付けても、新しく作ったフォルダで最初に聞かれる "Yes, I trust this folder"(フォルダ信頼確認)だけはスキップされない。しかも、CAO の自動承認コードが Ubuntu のログインメッセージに 0.33秒 で騙されて素通りしてしまうんだよ!

前述のCAO検証記事によるソースコード追跡で判明した、驚きのバグ発生メカニズムは以下の通りです。

CAOが0.33秒で誤判定して60秒タイムアウトに陥る内部フロー
STEP 1
tmuxペイン新規起動

cao-server がワーカー用の新しい tmux ウィンドウ/ペインを開きます。その日最初のログイン時、ペイン先頭に Welcome to Ubuntu 24.04.3 LTS... というOSメッセージ(MOTD)が出力されます。

STEP 2
0.33秒で正規表現が誤一致

CAO内部(providers/claude_code.py の _handle_startup_prompts())には信頼確認を自動承認する処理がありますが、起動完了判定の正規表現 r"Welcome to|Claude Code v\d+" が Ubuntu の Welcome to に わずか0.33秒 で誤一致し、Claude Code started without prompts と勘違いして処理を抜けてしまいます。

STEP 3
信頼確認画面で60秒停止

その後で本物の Claude Code が起動し、"Yes, I trust this folder" の入力待ち画面を出しますが、CAOの自動承認ループはすでに終了しているため誰もキーを押さず、60秒後にタイムアウトで強制失敗します。

原因が分かれば、対策は極めて明快です。作業対象のフォルダで CAO を動かす前に、以下の 2ステップの事前準備 を行うだけで、1秒も引っかからずに完走するようになります。

# 罠②の回避手順1:Ubuntuのログインメッセージ("Welcome to Ubuntu...")を抑止し、0.33秒誤一致を根絶する
touch ~/.hushlogin

# 罠②の回避手順2:作業対象の新規フォルダで事前に1回だけ手動で claude を起動し、"Yes, I trust this folder" を承認して終了しておく
cd /path/to/your-target-workspace && claude
# → 画面で "Yes, I trust this folder" を選んで承認したら、すぐに /exit で抜ける

実測記録でも、この事前承認(+~/.hushlogin)を済ませておくことで、スーパーバイザーからのタスク委任・ワーカーでの実装・結果回収まで 全体で約47秒(うちワーカー処理約24秒) で一発完走することが確認されています。

全体設定の自動書き換えリスクと多層防御の必須化

そして3つ目の見落とされがちな罠が、~/.claude/settings.json の自動書き換え です。

cao-server は起動するたびに、バックグラウンドのワーカーが権限確認プロンプトで止まらないよう、ユーザー全体の共通設定ファイルである ~/.claude/settings.json に "skipDangerousModePermissionPrompt": true を自動的に書き込みます 。

これが何を意味するかというと、「CAO での実験を終えた後、普段通りターミナルで手動の Claude Code を使った際にも、危険モードの警告画面が黙ってスキップされる設定がそのまま残り続ける」 ということです。ここで、前章で構築した第2層(PreToolUse フック関所)が真価を発揮します。

🔒 CAO運用後に必ず実施すべきセキュリティ防衛策
  • 作業終了後の ~/.claude/settings.json 点検・リセット :CAO を使ったバッチ委任が終わったら、~/.claude/settings.json を開き、"skipDangerousModePermissionPrompt": true が残っていれば false に戻すか該当キーを削除してください。

  • PreToolUse フック関所との多層防御(必須) :CAO 稼働中はすべてのワーカーが --dangerously-skip-permissions で自律走行し、かつ CLAUDE.md の注意事項も自動要約で抜け落ちるリスクがあります。だからこそ、前章で解説した PreToolUse フック(終了コード 2)を ~/.claude/settings.json に常設登録しておき、権限確認がスキップされた状態でも「秘密鍵の読み出し」「本番ブランチへの強制プッシュ」「検査抜きコミット」だけはOSプロセス層で物理遮断する枠組み(スキーム)を必ず併用してください。

  • SSH接続・Gitコミット署名への物理ハードウェアキー強制 :エージェントがローカルのSSH鍵を使って勝手に外部サーバーへ接続したりリモートリポジトリを書き換えたりできないよう、Git署名やSSH認証には物理タッチが必須となるハードウェアセキュリティキー(YubiKey)を挟むと、AIの無人暴走を物理層で100%食い止められます。

AIエージェントに広い権限を与えて自律走行させる開発環境だからこそ、最後の「外部へのプッシュ・本番SSH接続」だけは人間の指先による物理タッチを要求する YubiKey 5C NFC を組み込んでおくと、万が一設定が書き換わっても致命的な流出事故を防げます。

Yubico YubiKey 5C NFC(USB-C / NFC対応 FIDO2物理セキュリティキー)


判定専用AIと前提確認PASを組み合わせる実務設計

ここまで、第1層(CLAUDE.md 手順書の限界理解)、第2層(PreToolUse フックによる危険操作の決定論的遮断)、そして第3層(AWS CAO による並列委任の60秒停止突破と設定保護)という3つの層を組み立ててきました。

しかし、マルチエージェント開発を実際に無人・自律で回し始めると、最後の第4層として 「正規表現や構文解析(PreToolUse フック)だけでは白黒つけられない意味的な妥当性判定をどう自動化し、かつサブエージェントが『些細な確認質問』で作業を止めてしまう現象をどう防ぐか」 という壁に突き当たります。ここで非常に重要な2つの一次検証知見を統合しましょう。

設備点検48件の実測に学ぶ判定専用モデルの切り分け

1つ目は、現場の記録データに対する判定AIの実用性を検証したZenn「判定AIは現場で使えるか — 設備点検記録48件で Jev と d1 を測った全記録」です。この検証では、実際の設備点検記録 48件×7回計測 という徹底した反復テストを通じて、判定専用モデル(Jev と d1)の精度・応答速度・そして「どういう入力の時にどう壊れるか(誤判定するか)」が切り分けられています。

ここから得られる実務上の教訓は、「コードを書く重い汎用エージェントに、自分の出力の合否判定まで同じコンテキストで兼任させてはいけない」 という点です。

⚖️ 機械の関所と判定専用ワーカーの2層分担モデル
  • 機械で判定できる領域(構文・禁止フラグ・秘密鍵参照) :第2層の PreToolUse フック(Python / Rust)で 0〜数ミリ秒 で決定論的に遮断します。

  • 定型の合否・異常判定領域(ログ点検・差分チェック) :重いメイン対話とは切り離し、入出力スキーマを固定した軽量な判定モデルや、CAO で別ペインに立ち上げた専用検証ワーカーに独立して採点させます。

このように「機械の関所」と「独立した判定ワーカー」を分けることで、メインのコーディングエージェントのコンテキスト汚染(自動要約の誘発)とトークン浪費を劇的に抑えられます。

過剰な逆質問を防ぐ必須前提条件の絞り込み手法

2つ目は、AIに判断させる前の「事前点検ステップ」の罠を検証したZenn「LLMに点検や候補列挙を先にさせると、判断は良くなるのか? PAS実験の途中報告」です。

よく「AIにいきなり結論を出させず、最初に『不足している情報の点検』や『候補の列挙』をさせてから判断させれば精度が上がるはずだ」と考えがちです。しかし、Qwen3(8B / 4B)を用いてこの PAS(前提条件点検・候補列挙)の効果を実験した途中報告では、極めて興味深い事実が明らかになっています。

🧪 Qwen3(8B/4B)によるPAS実験が示した重要な逆転現象
  • 無条件に「点検欄」を先に置かせると過剰質問が発生する :回答の前にただ漫然と「不足情報の点検」や「候補列挙」を行わせると、LLMが 「最終的な結論に一切影響しない些細な欠落情報」まで過剰に掘り起こして質問・保留にしてしまい、かえって正答数が減ってしまう条件がある ことが判明しました。

  • 解決の鍵は「結論を左右する必須前提(クリティカル条件)かどうかの分離」 :事前チェックをプロンプトやサブエージェントに組み込む際は、「足りない情報をすべて挙げよ」ではなく、「最終判断(実行可否や設計方針)が180度変わる決定的な前提条件の欠落だけを選び出し、枝葉の未確定事項は標準値で進めよ」 と明確に分離する設計が必要です。

解説ナビゲーター

うわぁ、耳が痛いです……!サブエージェントにコードレビューや事前確認を頼むとき、「気になるところや不足情報を全部リストアップして」ってプロンプトに書いていたら、どうでもいい細かい確認質問ばかり返ってきて作業が止まっていたのはそのせいだったんですね!

質問するおじさん

そうなんだ。マルチエージェント(CAO)や事前チェックを回すときは、「機械フックで即断する禁止事項」と「人間やスーパーバイザーに聞くべき決定的な前提欠落」の境界線をくっきり引いておくのが、手戻りをゼロにする一番の秘訣なんだよ。

なお、tmux 上で CAO のスーパーバイザーと複数の Claude Code ワーカーを同時に走らせ、さらにローカルで Qwen3 などの判定モデルや Rust のビルドプロセスを並列稼働させると、一般的な16GB〜24GBメモリのPCではすぐにスワップが発生して動作が重くなります。マルチエージェント開発をストレスなく常時並列稼働させるなら、64GBの大容量ユニファイドメモリと14コアCPUを搭載した Mac mini(M4 Pro) クラスをローカル母艦に据えると、ワーカーを何本立ち上げてもメモリ不足で1秒も止まらない快適な環境が手に入ります。

Apple Mac mini(M4 Pro 等 Appleシリコン Pro系チップ・64GBユニファイドメモリ構成)


フック関所とCAO環境を自動診断するAIプロンプト

ここまでの4層ガードレール知見を、あなたの手元のリポジトリへ即座に導入できるよう、最上位推論モデル(Gemini 4 Carbon / Gemini 4 Argon または Claude Opus 5.5) にそのまま貼り付けて使える 「事前調査ファーストの環境診断&フック・CAO安全設計プロンプト」 を用意しました。

前章の PAS 実験の知見を取り入れ、「結論を左右しない些細な逆質問を禁止し、まずはリポジトリ内の既存ファイルを自ら調査した上で、機械フックと手順書の仕分け案を一発出力させる」 構造になっています。

# 指示:リポジトリの手順書(CLAUDE.md / AGENTS.md)棚卸しと PreToolUse 関所・CAO安全設定の自動設計
(※推奨実行モデル:Gemini 4 Carbon / Gemini 4 Argon / Claude Opus 5.5 等の最上位推論モデル)

あなたはシニアAIセキュリティアーキテクトです。結論に影響しない些細な逆質問や候補の羅列は一切行わず、まず以下の【ステップ1:事前調査】を自律実行してから、当リポジトリ専用の実装コードを出力してください。

## 【ステップ1:事前調査(推測で書かず必ず実ファイルを確認すること)】
1. カレントリポジトリおよび `~/.claude/` 配下に存在する `CLAUDE.md`、`AGENTS.md`、`.agents/skills/*/SKILL.md`、`~/.claude/settings.json`、`.claude/settings.json` の有無と記述内容を確認してください。
2. `CAO_HOME_DIR` の設定状況、`~/.aws` がシンボリックリンク(WSLの `/mnt/c/...` 等)になっていないか、および `~/.hushlogin` の有無を確認してください。

## 【ステップ2:『お願い(手順書)』と『決まり(PreToolUseフック)』の強制仕分け】
ステップ1で読み取った `CLAUDE.md` / `AGENTS.md` の記述を以下の2つに分類してください。
- **A. 手順書に残す項目**(アーキテクチャ方針、コーディングスタイル、テスト手順など)
- **B. PreToolUse フック(機械の関所)へ移管すべき絶対禁止項目**(検査スキップの `git commit -n / --no-verify`、秘密鍵・従量課金APIキーの環境変数出力、保護ブランチへの直接 `push`、危険な削除コマンドなど)

## 【ステップ3:フェイルオープン対策済み PreToolUse フックと CAO 安全起動スクリプトの生成】
1. **フェイルオープン防止フックの実装**:
   - 標準入力の JSON(`tool_name`, `tool_input`)を構造化パース(`shlex.split` 等でトークン分解)し、短縮オプション(`-n`)の見逃しや `echo` 文字列への誤爆を防いだスクリプト(Python 3 または Rust)を作成してください。
   - 未処理例外や JSON パース失敗時に素通り(フェイルオープン)しないよう、異常時は必ず標準エラー出力(`stderr`)に理由を出して **終了コード `2`(`exit 2`)** で遮断する設計にしてください。
2. **CAO(`cli-agent-orchestrator`)3大トラップ回避ラッパーの作成**:
   - `export CAO_HOME_DIR=$HOME/.cao-home` による FIFO(`Errno 95`)回避
   - `~/.hushlogin` 作成による Ubuntu MOTD(`"Welcome to"`)0.33秒誤一致&60秒タイムアウト回避
   - CAO終了後に `~/.claude/settings.json` の `"skipDangerousModePermissionPrompt"` を元の安全な状態へ自動復元するクリーンアップ処理
   上記3点を組み込んだ起動用ラッパースクリプトと、`.claude/settings.json` へのフック登録手順を提示してください。

まとめ:お願いの文書と機械の関所を分ける開発環境へ

今回の検証で明らかになった4層ガードレール設計の重要ポイントを振り返ります。

📌 本記事のまとめ(明日からのチェックリスト)
  • 第1層:手順書は「お願い」、フックは「決まり」 :稼働イベント 1,924件 の実測が示す通り、CLAUDE.md・AGENTS.md・SKILL.md は会話の自動要約で抜け落ちることがあります。絶対に守らせるルールは PreToolUse フック(終了コード 2 + stderr 差し戻し)へ切り出しましょう。

  • 第2層:フックの3大死角(短縮フラグ・echo 誤爆・フェイルオープン)を潰す :Anthropic公式の Hooks 仕様では終了コード 2 以外のエラー(exit 1 等)はツール実行が素通りします。コマンド引数をトークン分解して検査し、例外発生時にも必ず exit 2 で止める構造化コードを配置しましょう。

  • 第3層・第4層:AWS公式「CAO」は事前承認と ~/.hushlogin で60秒停止を突破し、関所・判定AIと組み合わせる :CAO_HOME_DIR の分離で Errno 95 を防ぎ、MOTD抑止と事前フォルダ信頼承認で 0.33秒の正規表現誤一致 を回避すれば、マルチエージェント委任が約47秒で快調に完走します。権限スキップ中の暴走は PreToolUse 関所で抑え、運用後の ~/.claude/settings.json 点検と判定専用ワーカー・必須前提絞り込み(PAS)で自律開発を完成させましょう。

AIエージェントに「お願い」するだけの段階を卒業し、決定論的な「機械の関所」と組み合わせることで、複数エージェントの並列稼働は驚くほど安全で頼もしいものに変わります。ぜひ今日からあなたの開発環境にも PreToolUse フックと CAO の安全設定を取り入れてみてくださいね。

フックの関所とCAO設定を整えて安心して眠る猫