AIエージェントのハーネスドリフトを自動検出する方法
この記事で学べること
- 共有ルールとツール別アダプターが時間とともにずれる原因
- 正本の変更とアダプター更新を同じ作業へ組み込む方法
harness:checkで同期漏れを検出し、残る限界を人が確認する運用
ハーネスドリフトは同期チェックで検出する
複数のAI実行環境で同じ方針を保つには、正本の変更とツール別アダプターの更新を同じ作業として扱い、同期検査まで完了条件に含めます。このサイトでは、shared/を正本にしても、検査がなければ更新漏れが残りました。ハーネスドリフトは、共有方針と実際に読み込まれる設定が時間とともにずれる状態です。
この記事では、「正本ルールとツール別アダプターの更新漏れをどう検出するか」という問いに焦点を当て、実行前の前提、作業手順、完了を確かめる方法を扱います。
最後まで読むと、「正本ルールとツール別アダプターの更新漏れをどう検出するか」という問いを、自分の状況に照らして判断するための材料を持ち帰れます。
正本・アダプター・同期検査を一続きにする
このサイトを構築する過程で、「設定ファイルに書いてあることと、コードの実態が合わなくなっている」という状況が繰り返し発生しました。
本記事では、設定ファイルに書かれた指示と実際のコード・運用がずれる状態を、便宜上「ハーネス（AIに渡すルール、作業手順、検証方法をまとめた仕組み）ドリフト」と呼びます。現時点で統一された業界標準用語ではありません。一般的な設定管理でいうconfiguration driftに近い問題を、AIハーネスに当てはめた呼び方です。
ハーネスドリフトでは正本ルールと実行用アダプターがずれる
実際に発生したドリフトの例を紹介します。
ルールとコードのずれ
CLAUDE.mdには「src/components/ディレクトリは直接変更しない」と書いてありました。しかし実際には、あるコンポーネントをリファクタリングした際にそのルールを更新し忘れ、しばらくの間ルールの記載内容とコードの実態が一致していない状態が続きました。
スキルファイルと実装のずれ
ブログ執筆スキルには、frontmatter（Markdown記事の先頭に置くtitle、description、dateなどの設定情報）へXXXフィールドを追加する手順が残っていました。サイトのコード変更後、そのフィールドは不要になっていました。スキルファイルの記述が古いまま残っていたため、AIはそのフィールドを引き続き追加し続けました。
パスの変更とファイル参照のずれ
ファイルを別のディレクトリに移動した際、CLAUDE.mdに書いてあった参照パスを更新し忘れ、AIが古いパスを使い続けました。
なぜドリフトが起きるか
ドリフトが発生する主な理由は、コードを変更したときに設定ファイルの更新を忘れるからです。
コードの変更は目的が明確なので実行されます。しかし設定ファイルの更新は「付随作業」であるため、後回しになったり忘れられたりします。
また、AIを使った開発では、人の指示や生成された作業計画によってコード変更が進むことがあります。その際、関連する設定ファイルが同時に更新されないと、ドリフトの一因になります。
正本の変更とアダプター更新を一つの作業にする
最初に取り入れた防止策は、「コードを変更するときは、関連する設定ファイルも一緒に更新する」というルールをCLAUDE.mdに明記することでした。
AIへの指示として「ファイル構造やディレクトリを変更する場合は、CLAUDE.mdの該当箇所も同時に更新すること」と記載しています。これにより、AIが変更作業を行う際に設定ファイルの更新も意識するようになりました。
ただし、このルールだけでは完全には防げません。ルールを書いても守られないことがある、というのはAIを使う上での現実的な制約です。
harness:checkで同期漏れを自動検出する
ルールによる防止と並行して、npm run harness:check でドリフトを自動検出しています。検査項目の設計とスクリプトを作った過程はAIとバリデーションスクリプトを作るに分け、この記事では「ルールと実装のずれを早期に見つける」という役割だけを扱います。
同期検査があってもハーネスドリフトは再発しうる
現時点では、ドリフトを完全に防ぐ方法はないと考えています。コードが変わり続ける限り、設定ファイルとのずれが生じるリスクは残ります。
現実的な対処は「気づくまでの時間を短くすること」です。変更のたびにチェックスクリプトを実行する習慣を作ることで、ドリフトが積み重なる前に検出できます。
まとめ：正本の変更・アダプター更新・同期検査を1つの作業にする
本記事でいうハーネスドリフトは、設定ファイルとコードの実態が時間とともにずれていく現象です。原因は主に「コード変更時に設定ファイルの更新を忘れること」です。防止策として「変更と設定更新をセットにするルール」と「自動検出スクリプト」の両方を組み合わせることで、ドリフトが長期間気づかれないまま積み重なる状況を避けやすくなります。
最初に正本と生成先の対応を1組選び、変更後に一致を確認する検査を追加します。自動検査は登録済みの対応だけを見られるため、新しい実行環境や意味上のずれは人が確認する必要があります。