AIとバリデーションスクリプトを作る：ハーネス設定の整合性を自動確認する仕組み

2026年6月22日

Shiori

手動チェックの限界

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

たとえば、「CLAUDE.mdにはshared/rules/フォルダのルールを読むと書いてあるが、そのファイルが実際に存在するか」「コマンド定義に記載されたスクリプトパスが有効か」といった確認を、毎回目視でチェックするのは時間がかかる上に見落としも生じます。

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

設定と実装がずれる現象そのものと予防方針はハーネスドリフトとは何かで扱っています。この記事では、検出条件をスクリプトへ落とし込む実装過程に範囲を限定します。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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