AIエージェントの必須検査をフック（hook）で止める｜Claude Code・Codex向け設計

AIエージェントに仕事を任せると、手順の一部が抜けることがあります。たとえば記事を公開する作業では、AIが本文を書き、引用元を調べ、最後に記事をWordPressへ送りますが、この途中でURLの確認や承認の確認が抜けると、内容がよくても公開してはいけない記事が出てしまいます。公開した事実は、あとから消せません。

担当者が困るのは、AIが「確認しました」と返しても、URLを本当に開いたのか、検査後に本文が変わっていないのか、承認を得たのかを確かめられないことです。AIの返答とは別に、この三つの結果を残し、記事を送る直前に担当者が照合できる状態が必要です。

そこで、記事を送る直前という決まったタイミングで確認処理を自動で動かし、一つでも不合格ならWordPressへの送信を始めさせないようにします。このように、AIの作業の節目をきっかけに利用者の処理を動かす機能を、フック（hook）と呼びます。

フックを使うには、AIが動く環境へ利用者が処理を登録できなければなりません。そのため、同じAIという名前でも、Web画面、CLI（コマンドで操作する環境）、IDE（コード編集画面）によって利用可否が変わります。

この表は2026年8月15日時点の公式資料に基づきます。実際に使えるかを調べるときは、今AIを動かしている場所がWeb画面か、CLIか、IDEかを確認し、フックの設定ファイルを探します。

Codexという名前でも、画面、バージョン、設定が違えば使える機能は変わります。利用する環境の公式ドキュメントで、記事をWordPressへ送る前に不合格で止められるイベントがあるかを確かめてください。

フック（hook）とは何か

AIが仕事を進める途中には、コマンドを実行する直前、ファイルを保存した直後、回答を終える直前といった節目があります。フック（hook）は、その節目をきっかけに、利用者が用意した検査や記録の処理を自動で動かす機能です。Claude Codeの公式リファレンスとCodexの公式フックガイドでは、フックをライフサイクル上のイベントに登録し、イベントの情報をJSONで処理へ渡す仕組みが説明されています。

記事をWordPressへ送る仕事なら、送信直前の節目で承認の有無と本文の一致を調べます。どちらかが不合格なら、送信処理を始めさせません。調査ファイルを保存した直後の節目では、保存されたファイルが壊れていないかを調べられます。同じ検査でも、どの節目で動かすかによって、防げる失敗が変わります。

フックは「いつ・何を対象に・何をするか」で書く

フックの設定は三つの要素で読み解けます。イベントは「いつ動くか」、matcher（マッチャー）は「どのツールを対象にするか」、handler（ハンドラー）は「どのコマンドやプログラムを動かすか」を表します。たとえばClaude Codeで、WordPress投稿用のツールを呼ぶ直前に検査スクリプトを動かす設定は、.claude/settings.jsonへ次のように書きます。matcherの値は、実際に使っている投稿ツール名へ置き換えてください。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "^mcp__wordpress__publish_post$",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/check-before-publish.sh"
          }
        ]
      }
    ]
  }
}

実行するcheck-before-publish.shは、Claude Codeから標準入力で渡されるJSONを受け取り、公開前の検査を呼び出します。不合格なら理由を標準エラー出力へ書いて終了コード2を返すため、PreToolUseは投稿ツールを実行しません。終了コード0はフックとして異議がないという意味です。通常の権限確認は残ります。

#!/usr/bin/env bash
set -u

input=$(cat)
tool_name=$(jq -r '.tool_name // ""' <<<"$input")

if ! python3 "$CLAUDE_PROJECT_DIR/scripts/verify-before-publish.py"; then
  echo "公開前検査が不合格です: $tool_name" >&2
  exit 2
fi

exit 0

Codexでは、同じ三層の設定を.codex/hooks.jsonまたは.codex/config.tomlへ置けます。次の例はTOML形式です。プロジェクト内のフックは、利用者が定義内容を確認して信頼した後に動きます。設定を追加または変更したら/hooksを開き、信頼状態まで確認してください。

[[hooks.PreToolUse]]
matcher = "^mcp__wordpress__publish_post$"

[[hooks.PreToolUse.hooks]]
type = "command"
command = '/usr/bin/python3 "$(git rev-parse --show-toplevel)/.codex/hooks/check_before_publish.py"'
timeout = 30

設定ファイルだけ作っても、検査の中身までは決まりません。検査プログラムには、承認記録の場所、照合する本文、合格条件、不合格時の終了コードを具体的に書きます。私なら、合格する例だけでなく、承認ファイルを外した不合格の例も一度動かします。投稿ツールが実際に止まった記録まで見て、フックを設定できたと判断します。

よく使うフックのパターン

フックは公開を止める場面だけでなく、結果の検査や記録にも使えます。2026年8月15日時点でClaude CodeとCodexの両方にあるイベントと、一方だけで確認できるイベントを分けると、次のようになります。製品の更新で変わるため、実装時には各製品の公式リファレンスも確認してください。

実行後のPostToolUseで不合格を見つけても、すでに外部へ送った記事は元に戻りません。したがって、検査に失敗したまま公開されると困る条件はPreToolUseへ置き、公開後の応答確認や記録はPostToolUseへ分けます。Codexでは、Web検索のようなホスト側で動くツールはローカルのツールフックで観測できず、一部の専用ツールも対象外になり得ます。フックを使えることと、すべての操作を捕捉できることは同じではありません。

AIに記事の目的や説明方法を伝える指示文は、確認処理そのものではありません。この指示文をプロンプトと呼びます。プロンプトはAIに何を考えてほしいかを伝え、フックは送信や保存の節目で確認処理を動かします。二つの役割を分ければ、AIへのお願いを必ず動く確認の代わりにせずに済みます。

AIに考えさせる仕事と、条件で確かめる仕事

フックをどこで動かすか決めるには、公開作業を仕事の種類で分けます。記事の説明が読者に誤解を与えないか、例外をどう書くかは、文章の前後や根拠を読んで考える仕事です。この判断はAIに任せられます。URLが開くか、検査後に本文が変わっていないか、承認があるかは条件で決まるため、フックやガードレール（条件に合わない処理を止める仕組み）に任せます。

公開後に問題が起きたときに追えるよう、何を確認したかの記録も残します。記録がないと、後で迷います。最後に公開してよいかを決めるのは人です。同じ公開作業でも、考える仕事、確かめる仕事、記録する仕事、許可する仕事は分けて考えます。この検査記録を使って、低リスクで可逆的な工程だけを全件目視から例外レビューへ移す条件は、AIのダブルチェックをいつ減らすかで扱っています。

公開前の役割は四つです。

調査結果をフックで確認する場合は、フックを設定する前に「何を調べたら合格か」を決めます。最終レポートにURLが付いているか、検索語と実行時刻が記録されているかは、条件で検査できます。しかし、調査の範囲が依頼に対して十分か、根拠の選び方が妥当かは、記録の意味を人が読まなければ決められません。調査の手順と判断材料を後からたどれるように、調査過程を記録します。

たとえば市場調査や技術調査では、次の項目を調査過程の記録と最終レポートの両方へ対応させます。

AnthropicのResearch Agent評価例でも、主張が根拠で支えられるか、重要な事実を落としていないか、権威ある情報源を選んだかを分けて評価しています。URL数や検索回数だけをフックの合格条件にすると、記録の量と調査の妥当性を混同します。

表の自動チェックに向くのは、合否を条件で決められる確認です。文章の意味を単語検索だけで決めるのは不十分です。OpenAI Agents SDKのGuardrailsも、入力、出力、ツールを確認する場所を分けています。使う製品を選ぶ前に、誰が何を担うかを決めておくと、確認の抜けを見つけやすくなります。

公開前に止める理由を決める

仕事の分担が決まったら、不合格になったときの影響を考えて止める位置を決めます。承認がない記事を公開してから取り下げても読者に届いた事実は戻せないため、承認と本文の確認は記事をWordPressへ送る処理を始める前に終えます。公開後では遅いからです。

フックを動かす節目は一つではありません。AIがツールを使う前、使った後、回答を終える直前があります。Claude Codeのフックリファレンスでは、これらをPreToolUse（実行前）、PostToolUse（実行後）、Stop（応答終了時）と呼んでいます。公開の承認は「実行前」、AIが保存した調査ファイルの形式は「実行後」、必要な記録がそろったかどうかは「応答終了時」に確認します。

この考え方は、Claude Codeだけの話ではありません。OpenAI Agents SDKのGuardrailsも、実行前に止める確認と実行後に行う確認を分けています。私なら、製品名やイベント名を先に覚えるより、不合格のまま何が起きると困るかを考え、その直前で止めます。

確認した内容を後から追える記録にする

公開前に止めても、何を確認して止めたのかが残っていなければ、担当者は同じ検査をやり直せません。大きな監査システムを用意する前に、次の三つを一枚の記録に残します。この三つがあれば、どの確認が抜けたのかを追えます。

1. 検査した本文と、いま公開する本文が同じか。
2. URL、禁止表現、承認など、必要な確認がすべて合格か。
3. どの確認をいつ実行したか、後から追えるか。

三つの記録のうち、本文の一致を確かめるために使うのがSHAです。本文を検査したあとに編集すると、検査時と公開直前でSHAが変わるため、前の合格結果は使えません。本文のSHAは、本文が同じかを照合する短い識別子です。違えば、確認をやり直します。

本文のSHA、確認したURL、承認の有無、実行時刻、合否があれば、公開前の確認内容をたどれます。AIや確認処理がどの順で動いたかを、処理の実行記録として残します。OpenAI Agents SDKのTracingの公式説明も、生成やツール呼び出しの順番をたどれる記録を扱っています。ただし、記録があるだけで内容が正しいとは言えません。公開直前に本文と条件をもう一度照らして合否を決めます。

自動チェックを通しても、人の判断を残す

自動チェックと記録をそろえても、公開、外部への送信、決済、権限変更のように、失敗してから戻す手間が大きい操作を機械だけで決めてよいとは限りません。公開の責任は、人に残ります。「この内容をいま出してよいか」は人が決めます。OpenAIの実務ガイドも、影響が大きい操作を人へ戻す考え方を示しています。

使っているAI製品にフックがなければ、公開スクリプトの最初で確認する、CI（変更時に自動で検査する仕組み）を必須にする、承認待ちで止める、といった方法で代替できます。AIの返答とは別に公開を止められる場所があれば、フックという名前にはこだわりません。

この分担にすると、AIは下書きや資料の整理を進め、人は公開の影響を引き受けられます。確認作業を減らしても、公開を急ぎすぎる事故を防ぎやすくなります。

よくある質問（FAQ）

Q1. プロンプトに「必ず確認」と書けばフックは不要ですか？

フックは不要になりません。プロンプトには確認の目的や例外を伝えます。本文が検査後に変わっていないか、承認があるかは別の自動チェックで確かめます。

Q2. ChatGPTのWeb版でもこの記事のフックを使えますか？

ChatGPT Webの通常チャットでは、この記事で説明したユーザー定義フックをそのまま登録できるとは確認できません。2026年8月15日に確認した公式資料に、同じ設定方法が見当たらないためです。

ChatGPT Webを使う場合は、公開スクリプト、CI、API（サービスを呼び出す窓口）など、チャットの外側に検査を置きます。Claude CodeやCodex CLI・IDEを使う場合は、Claude Codeの公式フックリファレンスとCodexの公式フックガイドで、フックの設定と実行前に処理を止められるイベントを確認してください。

Q3. フックに置いてよい検査は何ですか？

フックに向くのは、合否を条件で決められる確認です。対象ファイルがあるか、本文が同じか、承認があるかが該当します。

Q4. 説明が読者に誤解を与えないかもフックで判定できますか？

文章が読者にどう伝わるかは、単語があるかどうかだけでは判定できません。AIに根拠を集めて説明させることはできますが、公開してよい説明かは根拠と文脈を見て人が判断します。

Q5. 公開前の検査はどの境界へ置きますか？

記事をWordPressへ送る処理を始める前です。公開後に見つけても、未確認の本文はすでに読者へ届いています。

Q6. ログがあれば品質が合格したと判断できますか？

ログだけでは判断できません。ログは「何が動いたか」を示すものです。内容の合否は、公開直前に本文と条件を照らして決めます。

Q7. フックがないAI製品ではどうしますか？

公開スクリプト、CI、人間承認待ちのどこかへ同じ確認を置きます。製品にフックがあるかどうかより、AIの返答とは別に公開を止められるかが重要です。

Q8. フックの設定はどこに書きますか？

Claude Codeではプロジェクトの.claude/settings.json、Codexでは.codex/hooks.jsonまたは.codex/config.tomlへ書けます。全プロジェクトへ適用する設定場所もあります。共有する設定と自分の端末だけで使う設定を分け、プロジェクト内の設定が信頼された環境で読み込まれるかも確認してください。

調査手法について

こちらの記事はグラフAIリサーチプラットフォームのSnorbeを使って作られています。Snorbeは研究開発・新規事業向けの調査テーマに応じた幅広い項目のオートリサーチや、ナレッジグラフの構築、構造化レポートの生成ができるAIリサーチツールです。

Screenshot

調査したいテーマを入力するだけで、AIが深堀りすべき観点や広げるべき調査項目をレコメンドしながら、自動でリサーチを進めます。収集した情報はナレッジグラフとして蓄積され、未調査領域（ホワイトスペース）を可視化しながら調査の網羅性を高めていけます。

また、観点マトリクスを30秒・構造化レポートを10分で自動生成する機能があり、出典付きのレポートをMarkdown/PDF形式でエクスポートできます。調査の元データも保存されるため、ファクトチェックや社内共有も容易です。

ご利用をご希望の方は、こちらよりお申し込みください。

また、グラフAIを活用した社内ナレッジ管理や、研究開発・新規事業のリサーチ支援、セルフホスト導入のご相談も受け付けています。お困りの方はお気軽にご連絡ください。

冨田到

市場調査やデスクリサーチの生成AIエージェントを作っています 仲間探し中 / Founder of AI Desk Research Agent @deskrex , https://deskrex.ai

www.deskrex.ai/