AIと作るバリデーションスクリプト：手動確認を自動化

2026年6月4日更新 2026年9月16日

この記事で学べること

繰り返す確認を自動化するには、コードを書く前に、検出対象、違反例、許容する例外、合否条件を仕様として決めます。このリポジトリでは、人が毎回設定を見比べる運用から、変更直後に不整合を検出するスクリプトへ移しました。AIは実装を支援できますが、何を違反とするかはプロジェクトの責任者が定義します。

この記事では、「AIの支援を使いながら、誤検知を抑えた検証スクリプトをどう設計するか」という問いに焦点を当て、実行前の前提、作業手順、完了を確かめる方法を扱います。

最後まで読むと、「AIの支援を使いながら、誤検知を抑えた検証スクリプトをどう設計するか」という問いを、自分の状況に照らして判断するための材料を持ち帰れます。

人が検出条件と例外を定義し、AIが実装した検査を既知の正例・負例で確かめます。

このサイトを構築する過程で、ハーネス（AIへの設定ファイル群）の数が増えていきました。CLAUDE.md、各ルールファイル、スキルファイル、エージェント定義ファイルなど、参照関係を持つファイルが10本を超えたあたりから、手動での整合性確認が現実的でなくなりました。

たとえば、CLAUDE.mdが参照するルールファイルの存在確認があります。コマンド定義に書かれたスクリプトパスが有効かどうかも確認対象です。

これらを毎回目視で調べると時間がかかり、見落としも生じます。

この問題に対して、バリデーション（検証）スクリプトを作ることにしました。

設定と実装がずれる現象そのものと予防方針はハーネス（AIに渡すルール、作業手順、検証方法をまとめた仕組み）ドリフトとは何かで扱っています。この記事では、検出条件をスクリプトへ落とし込む実装過程に範囲を限定します。

バリデーションスクリプトとは、「設定が正しいかどうかを自動でチェックするプログラム」です。

日常的な例で言うと、荷物を発送する前にリストと照合して「すべての品物が入っているか」を確認する作業を、人間が一つひとつ目で見て確認する代わりに、機械に確認させるようなものです。

このサイトのスクリプト（npm run harness:check）は、次のような項目を確認します。

スクリプトを作る際、私がAIに対して行ったのは「コードを書いて」という指示ではなく、「何をチェックすべきか」の仕様を先に整理することでした。

ステップ1：チェックすべき項目の洗い出し

まず、「どういう状態が『壊れている』か」を自分の言葉でリストアップしました。「参照先のファイルが存在しない」「スラグの形式が仕様と一致しない」「シンボリックリンクが切れている」といった項目を箇条書きにしました。

ステップ2：AIによるスクリプトの実装

このリストをAIに渡し、「Node.jsでこれらをチェックするスクリプトを書いてください」と依頼しました。AIは各チェック項目をコードに落とし込んだスクリプトを出力しました。

ステップ3：動作確認と修正依頼

実際にスクリプトを動かして結果を確認しました。「このエラーは実際には問題ない」「この項目は検出できていない」といった点を具体的にフィードバックし、修正を繰り返しました。

全体として、私が行ったのは「何をチェックするか」の仕様整理と「動作確認」です。コードの記述はほぼAIが担いました。

スクリプトが完成してからは、AIが設定ファイルを更新するたびにnpm run harness:checkを実行するよう手順に組み込みました。

この結果、「AIがルールファイルを別のパスで参照するよう書き換えてしまった」「シンボリックリンクを誤って削除した」といった問題を、次のコマンド実行時に即座に検出できるようになりました。

以前は気づくのが遅れていた種類の問題が、変更直後に検出される状態になりました。

振り返ると、スクリプトの品質は「何をチェックするか」の仕様整理に依存していました。仕様が曖昧なまま「バリデーションスクリプトを作って」と依頼しても、重要な確認項目が抜けたり、不要な項目が混在したりします。

AIはコードを書くのが得意ですが、「何をどこまでチェックすべきか」の判断はプロジェクトの文脈を知っている人間が担う必要があります。この役割分担が、スクリプトの実用性を左右すると感じています。

ハーネスの設定整合性を手動で確認し続けることには限界があります。バリデーションスクリプトを作ることで、設定の不整合を自動で検出できるようになりました。スクリプトの実装はAIが担いますが、プロジェクトの文脈を理解した人が「何をチェックするか」の仕様を整理しないと、誤検出や見逃しが残ります。

最初に繰り返している確認を1つ選び、違反例と正常例を最低1件ずつ書きます。文脈や意味の判断が必要な項目は単純な文字一致では確定できないため、自動検出を人のレビュー候補として扱ってください。