AIに「ファイルを書いたら必ず検査して」と頼むだけでは、実際に検査したかどうかは分かりません。CodexやClaude Codeのフックは、ツールの実行前後など、決めた出来事をきっかけに処理を呼び出す仕組みです。
最初に決めるのは、何を検査し、いつ呼び、不一致や実行失敗が起きたときに、どの結果の利用を止めるかです。フック自体がCSVの意味を理解して品質を判定するわけではありません。検査処理が何を見ているかと、その処理が呼ばれたかを分けて確認します。
この記事では、架空CSVから作った確認用ファイルの検査を例に、導入前の試験表を作ります。製品別の設定手順や、設備の自動運転は扱いません。
指示・手順・フックの役割を分ける
「原本は変更しない」は作業のルールです。「入力と出力のIDを照合する」は検査手順です。「ファイル編集後にその検査を呼ぶ」がフックの役割になります。
| 決めること | 例 | 確認する対象 |
|---|---|---|
| 作業ルール | 原本は変更しない | 指示と変更差分 |
| 検査の中身 | 入出力のIDが各一回対応するか | 検査処理と期待結果 |
| 呼ぶ時点 | 対象ファイルの編集完了後 | イベントと対象条件 |
| 異常時の扱い | 結果を確定せず、担当者へ指摘を出す | 実際に止めた範囲と記録 |
検査処理だけなら、担当者が手動で呼ぶこともできます。先に手動で正常・異常の入力を試し、その後で自動的に呼ぶ仕組みへつなぐと、検査の不具合と接続の不具合を切り分けやすくなります。
実行前と実行後では、できることが違う
Codexのフック公式資料は、PreToolUse、PostToolUse、Stopなどのイベントを説明しています。設定の場所にはhooks.jsonやconfig.tomlがあり、管理外のフックには定義の確認と信頼の設定が必要です。条件に一致した複数のフックが並行して起動する場合もあり、一つの終了を待って次が始まると決めつけられません。
Claude Codeのフック公式資料にも実行前後のイベントがあります。ただし、設定形式、渡される情報、終了コードや出力の扱いは、製品とイベントに合わせて確認します。同じイベント名があるだけでは、設定をそのまま移植できる根拠になりません。
特に区別したいのは次の三つです。
| 時点 | 検討する用途 | 見落としやすい点 |
|---|---|---|
| ツール実行前 | 対象や操作を確認する | 何を拒否できるかは、そのイベントの仕様に依存する |
| ツール実行後 | 作られた結果を検査する | 既に行われた編集を、検査だけで巻き戻せるわけではない |
| AIの応答終了時 | 必要な検査記録がそろったか確認する | ファイルごとの検査を代替できるとは限らない |
CSVの列やIDを調べたいなら、対象ファイルが読める状態になった後で検査できます。一方、原本の変更そのものを防ぎたいなら、事後検査だけでは目的を満たしません。書込み権限や作業領域の分離も含め、実行前の条件を決めます。
「検査に通る」を具体的な仕様にする
例として、次の3件の架空記録を、AIが作った別ファイルへ転記する作業を考えます。数値の良否判定は行いません。
id,value_mm
H01,10.2
H02,
H03,0
この例で検査したいのは、元の3件のIDが各一回残り、値と空欄が変わらず、余分な行がないことです。行の並べ替えは許すものとします。空欄と0の扱いは、欠測とゼロの区別も参考に、入力仕様で決めてください。
検査処理を依頼するときは、「CSVをチェックする」だけでなく、次のように条件を渡します。
架空CSVの転記結果を確認する検査を作りたいです。
入力と出力は読み取るだけにし、修正はしないでください。
必須列はid,value_mmです。
元のIDと出力のIDが各一回対応することを確認します。
IDの空欄、重複、追加、欠落は不一致とします。
各IDのvalue_mmは、空欄を含め文字列として一致させます。
行の順番は問いません。
読み取れないファイルや列不足は「検査不能」とします。
入力不一致と検査不能を、正常終了にまとめないでください。
文字列としての一致は、この転記練習のために選んだ厳しい条件です。「10.20」を「10.2」へ整える用途では不一致になるので、数値の許容差や表記変換が必要な処理へそのまま流用しません。
検査の試験と、フック接続の試験を二段にする
検査単体では、次の入力を用意して結果を照合します。期待値は検査プログラムを作る前に決めます。
| 試す出力 | この練習での期待結果 |
|---|---|
| 元の3行と同じ | 一致 |
| 同じ3行を並べ替える | 一致 |
| H02の空欄を0へ変える | 値の不一致 |
| H03を消す | IDの欠落 |
| H01を二行にする | ID重複 |
| value_mm列を消す | 検査不能 |
| ファイルが存在しない | 検査不能 |
単体の結果が合ったら、フックに接続する担当者へ、対象イベント、対象ファイル、検査コマンド、作業ディレクトリ、制限時間、失敗時の扱いを渡します。製品の設定と実行環境を管理できない場合は、この条件表までを用意して管理担当へ相談します。
接続後は「検査が通った」だけでなく、意図したタイミングで呼ばれたかを確かめます。
| 接続の試験 | 残す記録・期待する振る舞い |
|---|---|
| 対象ファイルを編集 | イベント名、対象パス、検査の開始・終了、結果を残す |
| 対象外のファイルを編集 | 設定した対象条件に従って、検査するか対象外かを区別する |
| 検査スクリプトが起動できない | 「一致」ではなく実行失敗として分かる |
| 検査が時間内に終わらない | タイムアウトを残し、結果を確定しない運用になる |
| 同じ編集・検査を再実行 | 原本や既存結果を壊さず、どの試行の結果か分かる |
これらは導入時に満たしたい試験条件です。フックが自動的にすべて実現するという機能説明ではありません。失敗時に処理を止める設定の可否や範囲を確認し、難しい場合は人が検査記録を確認するまで結果を使わない運用にします。
設定しただけで「必ず検査される」としない
別のツールや経路から編集した場合、想定したイベントが発生しないことがあります。フックの対象条件に合わなかった場合や、設定が読み込まれなかった場合も、検査に合格したことにはなりません。
記録では「一致」「不一致」「検査不能」に加えて、検査自体が始まっていない「未実行」を分けます。直近の合格記録があっても、今回の入力・出力を検査した記録か確認してください。
繰り返しが少ない作業なら、手動チェックリストや既存スクリプトで十分なこともあります。自動化する場合も、最初は原本を保持した練習フォルダで始めます。検査処理が検査対象を自動修正し、その修正が次のフックを呼ぶような構成は、繰り返し実行の条件まで決めてから扱います。
ファイル処理の範囲はチャットAIとコーディングエージェントの違いでも整理しています。個別の作業への当てはめは、XのS1N_seigitechへ概要をDMでお知らせください。機密資料や個人情報は送らず、DMが使えない場合はお問い合わせページをご利用ください。
公式資料の確認日:2026年10月28日。表は架空の転記作業に対する試験設計です。Codex・Claude Codeへフックを設定した動作実演は行っていません。