Claude CodeのHooks・サブエージェント設計|0.2秒API直叩きと独立再計算検証術
作成日:

Claude CodeのHooks・サブエージェント設計|0.2秒API直叩きと独立再計算検証術

IT・Mac・AI実践

論旨

AIコーディングエージェントを実務へ本格投入する際、プロンプトのお願いだけで品質や安全性を守ろうとすると、コンテキスト肥大化によるルール無視や外部スキルの汚染、重いブラウザ自動化の乱発によるメモリ枯渇に直面します。

エージェントの自律性を活かしながら事故をゼロにする鍵は、Hooksによる決定論的な実行前ブロックと自動整形、サブエージェントへの調査分離、外部Skillのハッシュ検疫、ヘッドレスブラウザに頼らない0.2秒のAPI直叩き、そして別実装による独立再計算とバグ注入検証を組み合わせることにあります。

本記事では、現場の一次データと実測ログに基づき、AIエージェント開発の安全性・速度・検証精度を同時に引き上げる設計パターンを体系的に解説します。

合わせて読みたい深まる関連情報
この記事の対象となる方
  • Claude Codeの PreToolUse や PostToolUse を使い、危険な操作の遮断とコード整形・テストを自動化したい開発者の方

  • コードベース調査で親セッションのトークンが膨れ上がり、後半の指示忘れや推論劣化に悩んでいる方

  • 外部公開されている Agent Skill の安全性点検(Vetting)や、OSSへのAI製プルリクエスト提出時の入口ルールを把握したい方

  • AIが生成した Playwright スクリプトのメモリ消費(2GB枯渇)を解消し、Cognito SRP認証などのAPI直叩きで高速化したい方

  • LLM実験や自動評価パイプラインの採点バグを排除するため、独立再計算とバグ注入検証(ミューテーション検証)を導入したい方

Claude CodeのHooksとサブエージェント分離設計

AIエージェントに長時間の実装を任せていると、「最初に指示したコード整形やテスト実行を後半でサボる」「触ってはいけない設定ファイルを勝手に書き換える」「調査だけでコンテキストが埋まり本来の実装精度が落ちる」という3つの課題が必ず発生します。

これはモデルの性能不足ではなく、確率的に動くLLMに対して「自然言語のお願い」だけで秩序を維持しようとしている構造的なミスマッチが原因です(手順書が無視されるメカニズムの詳細は AIエージェントが手順書を83%無視する理由と強制検問術 でも詳しく検証しています)。

Anthropic公式のHooksドキュメント および Claude CodeのHooksでテストと整形を自動で回す実践レシピ(Zenn) で体系化されているとおり、絶対に守らせるべきルールはプロンプトから切り離し、ライフサイクルイベントに紐づく決定論的なフック(Hooks)とサブエージェント分離へ移行する必要があります。

質問するおじさん

手順書に毎回テストと整形をしてねと書いても、会話が長くなるとAIがすっかり忘れてしまうんだよね。

解説ナビゲーター

プロンプトはあくまで努力目標になりますからね。ツール実行の前後で強制的にスクリプトを走らせるHooksに任せるのが鉄則です!

PreToolUseの終了コード2による事前ブロック

PreToolUse は、Claude Codeがシェルコマンド(Bash)やファイル編集(Edit / Write)などのツールを実行する「直前」に発火する検問フックです。フックに設定されたスクリプトは、標準入力(stdin)から「どのツールを、どの引数で呼ぼうとしているか」を表すJSONデータを受け取ります。

ここで極めて重要な仕様が、スクリプトが返す 終了コード(Exit Code) の扱いです。

🔒 PreToolUseフックにおける終了コードの制御仕様
  • 終了コード 0(実行許可) :ツール呼び出しを正常に通過させ、そのまま実行に移ります。

  • 終了コード 2(物理ブロックとAIへの差し戻し) :ツールの実行を即座に中止し、標準エラー出力(stderr)に書き出したメッセージをそのまま Claude 自身へフィードバックします。AIは「なぜ拒否されたのか」を理解し、安全な代替コマンドへ自律的に軌道修正します。

  • その他の非ゼロ終了コード :非ブロッキングエラーとして扱われ、警告ログを出しつつ処理が継続される場合があるため、確実な遮断には必ず終了コード 2 を使用します。

たとえば、本番データベースへの破壊的クエリ、rm -rf による広域削除、git push --force、あるいは機密情報が詰まった .env ファイルの読み書きなどを正規表現で検知し、終了コード 2 で弾くラッパースクリプトを1本挟むだけで、うっかりミスやハルシネーションによる環境破壊を 1バイトも 許さずに遮断できます(タイムアウト回避を含めた実装例は CLAUDE.mdが無視される原因とPreToolUseフック回避術 もあわせてご参照ください)。

PostToolUseでの自動整形と単体テスト実行

一方、ファイルの編集や作成が完了した「直後」に自動発火するのが PostToolUse です。Hooks実践レシピ(Zenn) で示されているとおり、Edit や Write、MultiEdit をマッチャーに指定してフォーマッタやリンター、単体テストを紐づけておけば、AIに「編集後に整形コマンドを叩いて」と毎回指示する必要自体がなくなります。

ここで多くの開発者が抱く「PostToolUse で毎回テストを回したら、1ファイル直すたびに何十秒も待たされて開発テンポが悪化しないか?」という疑問に対しては、フックの役割を2段階に分けることで解決できます。

フック種別 発火タイミング 実行すべき処理の粒度 目標所要時間
PostToolUse ファイル編集・保存の直後 変更された単一ファイルへの高速整形(Biome / Prettier / Ruff)と、該当モジュールの軽量な単体テストのみ 0.5〜3秒以内
Stop / SubagentStop エージェントが作業完了を宣言する直前 リポジトリ全体の型チェック、ビルド確認、統合テストスイートの実行(失敗時は終了コード 2 で完了を差し戻し) 10〜60秒程度

このように、PostToolUse は対象ファイル限定の数秒で終わるチェックに絞り、全体整合性のテストは完了直前の Stop フック(詳細は Claude 5.5のstrict設定とStop hook検問術 参照)へ配置することで、速度と品質の二律背反(トレードオフ)を完全に解消できます。

Exploreと自作サブエージェントによる調査分離

Hooksと並ぶもう1つの柱が、調査タスクのサブエージェント分離です。サブエージェントに調査を丸投げする型:Exploreと自作エージェント活用術(Zenn) が指摘しているとおり、親セッション(メインの対話枠)で直接何十個ものファイルを検索・読み込みさせると、途中の試行錯誤ログや巨大なソースコード断片がすべて親のコンテキスト履歴に残り続けます。

一度汚れたコンテキストは以降のすべてのターンで毎回再送信されるため、トークン消費が雪だるま式に膨らむだけでなく、本当に重要な設計方針が埋もれてしまいます(KVキャッシュとコンテキスト管理の経済性は AIトークン浪費とKVキャッシュ・SQLiteオフロードの管理体制(ガバナンス) で詳述しています)。

親セッションを汚さないサブエージェント調査分離フロー
STEP 1
親エージェント

実装方針の策定に専念し、コードベース全体の探索や依存関係の洗い出しは直接行わずサブエージェントへ指示を出します。

STEP 2
Explore / 自作調査班

隔離された独立コンテキスト内で Read・Grep・Glob を大量実行し、該当パス・行番号・構造化された結論だけを抽出します。

STEP 3
クリーンな実装

親セッションは数十行の要約レポートだけを受け取り、コンテキストを一切汚さずに高い推論精度のまま本実装とHooks検証を完遂します。

Claude Code標準の組み込みサブエージェントである Explore は読み取り専用で高速にコードベースを探索するよう最適化されており、さらに .claude/agents/ ディレクトリに独自のMarkdown定義ファイルを置けば、利用可能なツールを Read・Grep・Glob のみに制限した「セキュリティ監査専任」「API仕様抽出専任」などの自作サブエージェントを簡単に構築できます。また、SubagentStart および SubagentStop フックを併用すれば、どのサブエージェントがいつ起動し、どれだけの調査結果を返したかの監査ログも自動記録できます。


外部Agent Skillの検疫とOSSのPR入口ルール

Claude Codeや各種AIエージェントの普及に伴い、GitHub上では便利なワークフローをパッケージ化した「Agent Skill(SKILL.md と同梱スクリプト群)」が多数公開されています。しかし、第三者が作成したスキルを無点検で手元の開発環境へ導入することは、見知らぬシェルスクリプトにローカル権限を丸ごと渡すのと同じ危険を伴います。

実際に外部の拡張機能やスキルを経由した侵害リスクは現実のものとなっており(詳細は Claude Code拡張機能のSSH裏口事件とAI脆弱性診断Shannon を参照)、導入前の厳格な検疫(Vetting)が不可欠です。

外部Skill事前点検で見送った4本と採用基準

第三者のAgent Skillを30本入れる前の点検:4本を見送り、内容を直した実録(Zenn) では、外部の3つのリポジトリからスキル候補を精査し、危険な 4本 を見送った上で固定コミット版から 30本(全162ファイル) を導入した極めて貴重な一次データが公開されています。

この事前点検において、著者の方は以下の 4本 を明確なセキュリティ・運用上の理由から「導入見送り」と判断しています。

🚨 外部Agent Skillの事前点検で見送られた4本の具体例と理由
  1. wizard(機密ファイルとシークレット操作のリスク) :利用者に認証情報やCIの秘密を入力させて .env や GitHub CLI のシークレット(gh secret)に書き込むスクリプトを作る挙動が含まれており、認証情報の意図せぬ書き換えや漏洩リスクがあるため導入見送り。

  2. setup-pre-commit(既存Gitフックの無断上書き) :プロジェクト側で運用する Husky のコミット前フック(pre-commit)を設定・変更する構造になっており、既存の品質ゲート統制と競合するため導入見送り。

  3. git-guardrails-claude-code(エージェント防衛機構の自己書き換え) :危険な git コマンドを止めるガードレール名目でありながら、Claude Code自身のフック設定ファイル(settings.json 等)を書き換える処理が含まれており、前節で構築した決定論的フックの統制を崩すため導入見送り。

  4. improve-codebase-architecture(外部CDNからの動的読み込み) :出力するHTMLレポートが Tailwind や Mermaid を外部 CDN から読み込む構造(かつ他スキル呼び出しあり)になっており、外部リソース依存のリスクを避けるため導入見送り。

どれも一見すると「初期設定を自動化する」「アーキテクチャを改善する」といった魅力的な名前がついていますが、中身を開けば .env・gh secret・Husky・Claude Codeのフック設定・外部CDNという開発環境の急所に手を突っ込む挙動が含まれていたわけです。

ハッシュ照合74件と全162ファイル7種パターン検査

さらに 30本導入前点検の実録(Zenn) で徹底されているのは、採用した 30本 についても本番変更コマンド例の削除や確認なし実行の抑止といった修正を加えた上で、「導入後も中身が変質していないか」をスクリプトで機械検証している点です。

具体的には、3つのリポジトリのコミットSHAを固定し、レビュー・調整済みの対象 74ファイル について SHA-256 ハッシュ値の一致(hash_ok=74)を照合しつつ、導入した 30本・全162ファイル に対して以下の 7種パターン検査 を走らせ、違反ヒット 0件(hits=0)を確認しています。

🛡️ 導入済み30本(全162ファイル)に実施された7種パターン検査
  1. curl|sh(パイプ直結のリモートスクリプト実行) :curl や wget で取得した外部出力をそのまま sh / bash / zsh へパイプ実行する危険構文が含まれていないか。

  2. token(認証トークン・APIキーの直書き混入) :ghp_(GitHub)、sk-(APIキー)、AKIA(AWS)、xoxb- / xoxp-(Slack)などの生トークン文字列が残っていないか。

  3. private key(秘密鍵ブロックの混入) :BEGIN RSA / OPENSSH / EC / PRIVATE といった秘密鍵データが含まれていないか。

  4. override(プロンプトインジェクション・命令上書き) :ignore previous instructions や disregard system のように、親エージェントの安全規則を無効化する指示文が紛れていないか。

  5. rm -rf(ルート・ホーム領域の破壊的削除) :/ や ~、$HOME を対象とした広域の強制削除コマンドが含まれていないか。

  6. settings/hooks(エージェント設定・フックへの干渉) :settings.json、settings.local.json、PreToolUse、.claude/settings など、Claude Code自身の統制設定に触れる記述がないか。

  7. gh secret(リポジトリ秘密変数の変更) :gh secret set や gh variable set によってGitHub側のシークレット・変数を書き換える操作がないか。

GhosttyでAI製PRが30秒以内に閉じられた理由

自分自身のローカル環境を守る検疫と同時に、AIエージェントを使って外部のオープンソースプロジェクト(OSS)へ貢献(コントリビュート)する際の「相手側の入口ルール」も急速に厳格化しています。

承認前にAIで書いたPRを出したら、30秒以内に自動で閉じられた。Ghostty・Hono・Kiriの入口ルールを比べた(Zenn) では、AIを活用して作成したプルリクエスト(PR)を3つのOSSに提出した際の生々しい対比が記録されています。

OSSプロジェクトにおけるAI作成PRの入口ルール比較
30秒以内自動閉鎖
事前承認(Vouch)必須型(Ghostty)

Ghostty では信頼されたコントリビュータによる事前承認(vouch)または事前のIssue合意が入口条件となっており、未承認のままAIで書いた Draft PR を出した結果、1本目は 28秒後、2本目は 23秒後 にボットによって自動クローズされました。

規約順守で前進・解消
入口規約の事前読解と順守(Hono / Kiri)

Hono では CONTRIBUTING.md に「PRはメンテナー限定、バグは最小再現付きの Issue で報告」と明記されていたため PR ではなく Issue 2件 を提出して2日後にメンテナーのPRで両方解消し、Kiri ではコミット署名・CLA・同時3本上限・実機出力添付などの規約を守って PR 4本 を出し、マージや署名付き取り込みへと進んでいます。

この一次事例が教えてくれるのは、「手元のHooksでテストが通ったからといって、そのまま gh pr create までAIに自動実行させてはいけない」という教訓です。OSSメンテナは毎日大量に送りつけられる低品質なAI生成PR(メンテナのレビュー時間を奪うスパム)からプロジェクトを守るため、Ghostty の 28秒・23秒自動クローズ のような機械的ゲートを導入しています。

外部リポジトリへPRを出す作業では、必ず PreToolUse フックで gh pr create を一旦ブロックし、「対象リポジトリの CONTRIBUTING.md と vouch(事前承認)制度の有無を人間が確認したか?」をチェックする停止ゲートを挟むのが礼儀であり実務上の防衛策です。

ノルウェージャンフォレストキャット

28秒や23秒で自動的に閉じられるなんて、OSS側の防衛ゲートもすごく速くて厳格なんだね。

解説ナビゲーター

だからこそ、AIにPR送信まで一気通貫でやらせず、相手先の貢献規約を事前に確認する人間用のストップゲートが大切になります!


Playwright多重起動の罠とAPI直叩き0.2秒化

AIエージェントに「複数のWebサービスから管理画面の数値や明細を定期取得するスクリプトを書いて」と指示すると、ほぼ間違いなく Playwright(または Puppeteer / Selenium)でヘッドレスブラウザ(Chromium)を立ち上げ、ログイン画面の入力欄を探してクリックするコードを生成します。

確かにブラウザ操作は汎用性が高いものの、これをそのまま定期バッチや並列処理に乗せると、インフラ資源を一瞬で食い潰す最大の障壁(ボトルネック)に変わります。

物理メモリ2GB枯渇とスワップ70%超の障害構造

Playwright多重起動でメモリ2GB蒸発したのでCognito SRP認証をPython直叩きし0.2秒化した話(Zenn) では、物理メモリ 2GB の VPS 環境で4つのサイトの巡回スクリプトを Playwright で動かした際に起きた深刻なリソース枯渇が報告されています。

💥 Playwright(ヘッドレスChromium)多重起動時に発生した最大の障壁(ボトルネック)
  • 1サイトあたり300〜500MBのメモリ消費 :ヘッドレスモードであっても Chromium は完全なブラウザエンジン(レンダリングプロセス・V8 JavaScriptエンジン・ネットワークスタック)を起動するため、1インスタンスごとに 300〜500MB のRAMを消費します。

  • 物理メモリ2GBの完全枯渇とスワップ70%超 :4サイト分が重なった瞬間、VPSの物理メモリ 2GB が蒸発し、SSDやハードディスク上のスワップ領域の使用率が 70%超 に跳ね上がって、OSの OOM Killer(メモリ不足によるプロセス強制終了)がいつ発動してもおかしくない危険水域に陥りました。

  • 1回の取得に15〜30秒の待機時間 :ブラウザ起動、大量のJavaScriptバンドルのダウンロードと解釈、DOMの描画完了待ち、ログイン画面の遷移待機が積み重なり、たった1回のデータ取得に 15〜30秒 もかかっていました。

Cognito SRP認証をPythonで直叩きする設計

この窮地を打開するために Cognito SRP直叩き0.2秒化の実録(Zenn) が採ったアプローチは、「なぜブラウザを起動していたのか?」を根本から問い直すことでした。

ブラウザの開発者ツール(DevTools の Network タブ)を開いてログイン時からデータ表示までの通信を観察すると、現代の多くのモダンWebアプリ(SPA:Single Page Application)は以下の2ステップしか行っていません。

  1. 認証エンドポイントへのトークン要求 :ログインフォームに入力されたIDとパスワードを使い、AWS Cognito に対して SRP(Secure Remote Password:パスワード平文を通信路に流さずゼロ知識証明ベースで認証するプロトコル) で認証を行い、JWT(IDトークン/アクセストークン)を受け取る。
  2. バックエンドREST APIへのJSONリクエスト :受け取ったトークンを Authorization: Bearer ... ヘッダーに添えて裏側の REST API を叩き、必要なデータ(JSON)を取得する。

つまり、数百メガバイトのメモリを使ってHTMLやCSS、巨大なJavaScriptフレームワークを描画していたのは「トークンを1個取ってJSONを1回受け取るためだけ」だったのです。

Playwright脱却・Cognito SRP認証+API直叩きへの移行手順
STEP 1
DevToolsで通信解析

Networkタブから Cognito の UserPoolId・ClientId と、ログイン後に叩かれているデータ取得用 REST API のエンドポイントURLを特定します。

STEP 2
PythonでSRP認証

ヘッドレスブラウザを廃止し、Python の pycognito ライブラリ等を使って SRP 計算を直接実行し、アクセストークンをメモリ上で高速取得します。

STEP 3
REST API直叩き

取得したトークンを付与して HTTPS リクエストを1発送り、構造化JSONを直接受け取ります。所要時間は 15〜30秒 から 0.2秒 へと劇的に短縮されます。

この設計変更により、1回あたり15〜30秒かかっていた処理がわずか0.2秒(約75倍〜150倍の高速化)で完了するようになり、Chromiumプロセスが消滅したことで2GBあったメモリ消費も数十MBレベルの軽量なPythonプロセスのみへと劇的に改善しています。

推論(試算)ですが、仮に1日100回の定期巡回を回す運用で比較した場合、1回20秒の Playwright では毎日約33分間ずっとCPUと 300〜500MB のメモリを占有し続けるのに対し、0.2秒 のAPI直叩きなら1日合計でもわずか20秒で全処理が終わり、月額数百円〜千円クラスの最小構成VPSやサーバーレス関数の無料枠内でも余裕を持って稼働させられます。

ブラウザ自動化を残す場面とAPI直叩きの境界条件

もちろん、「すべての Playwright を今すぐ捨てるべきか?」というと、そこには明確な境界条件(および N=1 事例の適用限界)があります。ご自身のアカウント権限および対象サービスの利用規約の範囲内で自動化を行う前提のもと、以下の基準で切り分けるのが最も合理的です。

判断軸 API直叩き(Python / Rust等)へ切り替えるべき場面 Playwright(ヘッドレスブラウザ)を残すべき場面
データ供給源 Networkタブに綺麗な JSON(REST / GraphQL)応答が見えるSPA サーバーサイドでHTMLに直接埋め込まれ、複雑なJS実行後にしかDOMが生成されない画面
認証方式 AWS Cognito SRP、OAuth2、JWT、Cookieセッション等で完結する場合 WebAuthn(パスキー)、複雑な多段階画面遷移、ブラウザ固有の暗号化処理が必須な場合
インフラ制約 メモリ 2GB 以下のVPS、軽量コンテナ、秒単位の高速応答が求められるバッチ メモリ8GB以上の専用ランナーがあり、実行時間が数十秒かかっても問題ない夜間ジョブ
本来の目的 バックエンドからの定型データ取得・状態確認・API連携 フロントエンドUI自体のE2Eテスト・レイアウト崩れ検証・スクショ撮影

AIエージェントに自動化コードを書かせる際は、最初から「Playwrightで書いて」と指示するのではなく、「まず Network 通信または API 仕様を確認し、ブラウザを起動せずに HTTP クライアント直叩きで実装できないか検討せよ」と制約を与えるだけで、将来のスワップ枯渇事故を未然に防ぐことができます。

質問するおじさん

ブラウザで画面を開かないとログインできないと思い込んでいたけれど、裏側の通信を見ればJSONをやり取りしているだけだったんだね。

解説ナビゲーター

はい!UIの見た目テストにはPlaywrightが最強ですが、データ取得目的ならAPI直叩きに切り替えるだけでメモリ2GB蒸発も一発で解消します。


採点バグを防ぐ1,152件の独立再計算とバグ注入検証

Hooksでエージェントの暴走を止め、外部スキルを検疫し、API直叩きで高速なデータパイプラインを組めるようになると、最後に立ちはだかるのが 「AIの出力結果を評価・採点・集計しているプログラム自体にバグはないか?」 という信頼性の壁です。

近年では、AIエージェントが書いた業務コードや、LLMベンチマークの評価スクリプトもまたAI支援で書かれることが増えています。このとき「元の採点スクリプトをもう一度実行して同じ数値が出たから正しい」と確認しても、採点ロジック自体に潜むバグ(条件分岐の漏れやJSONパースの取りこぼし)は 1ビットも 見抜くことができません。

原本ZIPのハッシュ確認と別実装での再計算手順

この「採点コード自身の信頼性」に正面から切り込んだ一次事例が、LLM実験の採点コードは信用できるのか?――1,152件の独立再計算とバグ注入検証(Zenn) です。

この検証では、合成業務課題実験「PAS-D」における 288問 × 2条件 × 2モデル(Qwen3 8B / Qwen3 4B)= 合計1,152件 の試行データに対して、以下の徹底した手順で独立監査を行っています。

🔬 1,152件のLLM実験結果を裏付けた独立再計算の3ステップ
  1. 原本データの不変性確認(40ファイルのSHA-256一致) :再計算を始める前に、凍結保管されていた原本 ZIP アーカイブ内の全 40ファイル について SHA-256 ハッシュ値を照合し、生ログが1バイトも欠損・変質していないことを確定させています。

  2. 既存採点コードを1行も流用しない「別実装」の構築 :元の実験で使われた採点スクリプトをコピーするのではなく、仕様定義だけをもとに、JSONの抽出・正規化から行動判定、条件別の集計に至るまでを 完全に別の実装コード としてゼロから書き起こしています。

  3. 全1,152件の行別判定突合による「不一致0件」の確認 :最終的な平均点や合計値だけを比べる(たまたまプラスとマイナスの誤差が相殺して一致するリスクがある)のではなく、全 1,152件 の試行1件ずつ(行別)の判定結果を元の出力と突き合わせ、不一致 0件(完全一致)であることを確認しています。

意図的な2種バグ注入による監査パイプラインの検証

さらに 1,152件の独立再計算とバグ注入検証(Zenn) が秀逸なのは、不一致0件が出た時点で満足せず、「もし元の採点コードにバグがあったら、この独立監査パイプラインは本当に気づけるのか?」を確かめる バグ注入検証(ミューテーションテスト) まで実施している点です。

具体的には、本番の原本データは一切汚さず、元の採点コードの コピー に対して意図的に 2種類のバグ(判定ロジックの境界条件をずらすバグや、特定ケースの分類を誤らせるバグ)を注入して採点を走らせました。その上で独立再計算の結果と突き合わせたところ、注入した 2種類のバグ両方とも確実に「不一致」として検出・警報できること を実証しています。

形だけの再実行と「独立再計算+バグ注入検証」の決定的な差
バグ検出不能
同一スクリプトの再実行

同じ採点コードを同じデータに何回当てても同じ出力が返るだけであり、正規表現の抜け漏れやJSONフィールドの参照ミス、集計条件のバグがあっても永久に見逃されます。

不一致0件を実証
別実装での独立再計算+バグ注入

原本 40ファイル のSHA-256を確認した上で、別実装の監査コードで全 1,152件 を行別照合して 不一致0件 を確認し、さらにコピーへ注入した 2種類のバグ を確実に検知できることで採点器の健全性を証明します。

独立再計算で保証できる範囲と評価設計の限界

ここで読者の方が抱きやすい「独立再計算で不一致0件かつバグ注入もパスしたなら、そのLLM実験の結論やAIモデルの賢さも100%絶対だと証明されたことになるのか?」という疑問に対しても、元記事は極めて誠実な境界線を引いています。

独立再計算とバグ注入検証が保証するのは、あくまで 「凍結された生ログ(1,152件)から採点・集計テーブルに至るまでの計算プロセスに実装バグがないこと(採点パイプラインの計算整合性)」 です。以下の領域については、独立再計算とは別の層の検証が必要になります。

  • モデル推論そのものの揺らぎと再現性 :LLM APIやローカル推論エンジンが温度パラメータや量子化環境によって異なる出力を返す問題。
  • 課題設計(ベンチマーク自体)の妥当性 :合成課題の288問が実社会の複雑な業務をどこまで正確に代表できているか(外的妥当性)。
  • 採点仕様(ルーブリック)自体の妥当性 :仕様書で定義した「正解の条件」そのものが業務上の最適解と一致しているか。

このように「この検証で何が保証され、何が保証範囲外なのか」を曖昧にせず明文化することこそが、技術検証における最も信頼できる裏付け(エビデンス)となります。社内のAI精度評価や自動請求集計、テスト結果レポートをAIエージェントに作らせる際も、本番集計スクリプトとは別に「最小限の別ロジックで書いた独立検算スクリプト」を並走させ、意図的なダミー異常値を1件混ぜて警報が鳴るかテストしておくだけで、致命的な集計事故を根絶できます。


開発環境を安全に診断するAI導入用プロンプト

ここまで解説してきた「Claude CodeのHooksとサブエージェント分離」「外部Skillの7種検疫」「Playwright過多箇所のAPI直叩き化」「独立再計算とバグ注入検証」を、お手元のプロジェクトへ安全かつ段階的に導入するための診断プロンプトを用意しました。

最上位推論モデル指定と事前調査ファーストの原則

このプロンプトを実行する際は、軽量・高速系のモデル(Flash系やMini/Haiku系)ではなく、必ず 『Gemini 4 Carbon』 または 『Gemini 4 Argon』(あるいは Claude Opus 5.5 / Sonnet 5.5 等の最上位推論モデル)を選択してください。

軽量モデルはコンテキスト後半の安全制約(「いきなり書き換えるな」「バックアップを取れ」)をショートカットして勝手に設定ファイルを上書きしてしまう傾向があるため、環境診断とフック設計には必ず最上位の推論モデルを使用することが鉄則です。

現状診断と段階導入を行うコピペ用プロンプト

以下のプロンプトをそのままコピーし、手元のAIコーディングエージェント(Claude Code や Antigravity 等)に貼り付けて実行してください。最初はファイルを1文字も書き換えず、現状の診断レポートと移行計画だけを出力させます。

あなたはシニアセキュリティエンジニア兼AI基盤アーキテクトです。
作業を開始する前に、以下の参照記事の設計原則と安全基準を読み込んでください。
参照URL: https://lab.chihouzakki.com/blog/review/claude-code-hooks-subagent-vetting-cognito-srp-independent-recalc-guide/

【絶対遵守の3大安全原則(違反厳禁)】
1. 原本保護とバックアップ義務:既存の `.claude/settings.json`、Gitフック、自動化スクリプト等をいきなり編集・削除することは厳禁です。変更承認後に編集する場合も、必ず事前にタイムスタンプ付きのバックアップを作成してください。
2. 機密情報の読み取り・出力禁止:`.env`、秘密鍵、APIキー、認証トークンの中身は絶対に読み取ったりチャットに出力したりしないでください(ファイル存在確認のみ可)。
3. 事前調査ファースト(承認前編集の禁止):第1ターンではいかなるファイルの作成・変更も行わず、以下の4項目に関する「現状診断レポートと段階的導入プラン」のみを出力し、必ず人間の承認を待ってください。

【調査・診断してほしい4つの対象】
1. Claude Code Hooksとサブエージェント設計の診断
   - 現在の `.claude/` 配下の設定や手順書(`CLAUDE.md` 等)を確認し、自然言語のお願いに頼っているルールのうち、`PreToolUse`(終了コード2での危険操作ブロック)および `PostToolUse`(編集直後の軽量整形・単体テスト)、`Stop`(完了前の全体検証)へ切り出すべき候補を洗い出してください。
   - 親セッションのコンテキスト汚染を防ぐため、`Explore` または `.claude/agents/` の読み取り専用サブエージェントへ分離すべき調査タスクを提案してください。

2. 導入済み外部Agent Skill・スクリプトの7種検疫(Vetting)
   - リポジトリ内にサードパーティ製の Agent Skill(`SKILL.md` 等)や外部スクリプトがある場合、①パイプ直結実行(`curl|sh` 等)、②生トークン・APIキー混入、③秘密鍵ブロック混入、④命令上書きプロンプト(`ignore previous instructions` 等)、⑤ルート・ホームへの破壊的削除(`rm -rf`)、⑥エージェント設定・フックへの干渉(`settings.json` / `PreToolUse` 等)、⑦リポジトリ秘密変数の変更(`gh secret set` 等)の7観点で安全性を点検し、SHA-256ハッシュ固定案を提示してください。

3. Playwright / ヘッドレスブラウザ過多箇所のAPI直叩き移行診断
   - 単なるデータ取得や定期巡回のために Playwright / Puppeteer 等を起動しているスクリプトがあれば特定し、本来のUIテスト用途(Playwrightを残すべき箇所)と、認証トークン取得+REST API直叩きへ軽量化できる候補を切り分けてください。

4. 評価・集計スクリプトの独立再計算&バグ注入検証プラン
   - リポジトリ内にLLM評価、スコア採点、重要データの集計スクリプトがある場合、元コードを流用しない「別実装での独立再計算スクリプト」と、意図的なダミーバグを2種類注入して不一致検出を確認する最小テストの設計案を提示してください。

まずは上記1〜4の調査結果と優先順位付きの段階導入プランを日本語で分かりやすく報告し、どの項目から着手するか私の指示を待ってください。
ノルウェージャンフォレストキャット

いきなり設定ファイルを書き換えさせずに、まずは現状診断レポートを出させて人間が選ぶ仕組みなら安心だね!

解説ナビゲーター

はい!最上位の推論モデルを指定してこのプロンプトを投げれば、手元のプロジェクトの弱点と改善プランが安全に一覧化されますよ。


まとめ:確率的なAIを決定論的な検証基盤で包む

AIエージェントを使った開発生産性を最大化しつつ、現場での手戻りやセキュリティ事故、インフラ枯渇をゼロにするための要点を振り返ります。

📌 本記事の実践チェックリストと導入判断の目安
  • 導入して大きな効果が得られる方 :Claude Codeなどのエージェントを日常的に使っており、PreToolUse(終了コード 2)での危険操作遮断、PostToolUse での即時整形、Explore 等のサブエージェント分離でコンテキストとトークンを節約したい方。また、Playwright巡回のメモリ枯渇(2GB 蒸発)を API直叩き(0.2秒 化)で解消したい方や、評価・集計処理の正しさを独立再計算で証明したい方。

  • 無理にすべてを導入しなくてよいケース :1回限りの使い捨てプロトタイプ作成や、ログインを伴わない単発ページの見た目確認、あるいは数件程度の目視で確認できる小規模な出力チェックであれば、重厚な独立再計算パイプラインまで組む必要はありません。

  • 今日から始める最初の1歩 :まずは手元の環境で「絶対に触らせてはいけないファイル・コマンド」を PreToolUse の終了コード 2 で塞ぎ、外部から持ってきた Skill(危険な 4本 を見送り安全確認済みの 30本 のみを採用した検疫事例のように)を無点検で入れない習慣からスタートしてみてください。

確率的に推論するAIの柔軟さと、終了コード・SHA-256ハッシュ・API直叩き・独立再計算という「1ビットのごまかしも効かない決定論的なエンジニアリング」を噛み合わせることで、開発環境は驚くほど軽快で安全な場所になります。夜間のバッチ処理もエージェントの自動テストも安心して任せられる環境を整えて、心地よい開発ライフをお楽しみください。

安心してお昼寝するノルウェージャンフォレストキャット