「エージェントの指示ファイルがどんどん食い違う」に対して真っ先に出てくる対処は、コピーの保守をやめることです。AGENTS.md を書き、そこから CLAUDE.md と .cursor/rules/*.mdc と .github/copilot-instructions.md を生成する。それで終わり、のはずでした。
実際に作りました。動きます。それでも問題は解けていません。この 2 つの差は書き出しておく価値があります。実機で回すまで、私にも見えていませんでした。
python3 agent_fanout.py
create CLAUDE.md
create .cursor/rules/from-agents-md.mdc
create .github/copilot-instructions.md正となるファイルが 1 つ、そこから派生ファイルが数個。派生側を誤って編集しないよう、先頭にヘッダを入れます。
<!-- Generated from AGENTS.md by agent-fanout. Do not edit this file. -->CI に入れておけば、CLAUDE.md を直接編集したプルリクエストはビルドを落とします。
- run: python3 agent_fanout.py . --checkこれでカバーされるのは CI が回るマシン上の、このリポジトリ です。全部のように聞こえますが、外れるものを並べると印象が変わります。
別のリポジトリ。 チームが持つリポジトリは 1 つではありません。それぞれに AGENTS.md があり、どこかの時点で互いにコピーされたものです。生成はリポジトリの内側の整合を保ちますが、リポジトリ同士は離れていきます。
グローバル設定。 Claude Code はプロジェクトのファイルに加えて ~/.claude/CLAUDE.md を読みます。Cursor にもユーザーレベルの指針があります。どのリポジトリにも属さず、CI にも乗りません。レビューで議論したくなかった指針が置かれるのは、まさにこの場所です。
編集と編集のあいだ。 生成は、誰かが実行したときに走ります。その瞬間から次の CI までのあいだに、派生ファイルは編集され、そのまま使われます。エージェントは変更を即座に読みます。CI が気づくのは push のとき、push があればの話です。
CI のないリポジトリ。 プロトタイプ、作業用のクローン、先週の火曜に誰かが作ったリポジトリ。指示が最も自由に書き換わる場所であり、ゲートが 1 つもない場所でもあります。
単位はリポジトリではなくマシン。 エージェントが動く単位はノート PC です。1 台の中に多数のチェックアウトがあり、同じリポジトリのコピーが何個もあり、ホームディレクトリがあります。リポジトリ単位で動く仕組みは、その全体を横断して見られません。
防止はルール、検出は計測です。ルールは、計測するまで見えない形で迂回されます。
python3 agent_drift.py ~/work ~/side-projects
Scanned 47 instruction files.
DRIFT: 2 documents, 5 distinct versions between them.
claude-code:CLAUDE.md
6 copies, 3 versions
9b01aeaa204d 3 files, 406 lines
2dc3c616c279 2 files, 411 linesこちらはリポジトリではなくパスを走査し、ファイル名ではなく内容の類似度でまとめます。無関係な 2 つのプロジェクトで CLAUDE.md の中身が違うのはズレではなく、それをズレとして報告した時点で出力は読まれなくなります。（このまとめ方を決めるのに 3 回書き直しました。その部分は同じ CLAUDE.md が、1台に18バージョンあった。）
1 プロジェクトではなく、作業ディレクトリ全体に対して走らせてください。見るべき結果は、リポジトリの境界をまたいだところに出ます。
| 範囲 | 答える問い | |
|---|---|---|
agent-fanout | リポジトリ 1 つ | 「派生ファイルは最新か」 |
agent-drift | マシン全体、複数のパス | 「コピーはどこで分かれたのか」 |
生成は、コピーが存在する*理由*をなくします。検出は、想定していなかった理由で存在してしまったコピーを拾います。どちらも余分ではありません。前者だけをやると、カバーできているという誤った感触が残ります。ここが本当の失敗パターンで、私自身がはまったところです。
どちらも単一ファイルの Python、依存なし、肝心なところは読み取り専用、MIT ライセンスです。
AGENTS.md を一度書き、残りを生成する正直なところ、行き着く先はどちらのスクリプトも要らない状態です。資産がそもそもノート PC の上のファイルとして存在せず、レビュー済みの 1 か所からどのマシンにも届く。誰も何も貼り付けません。触らないから、ばらつかない。それを untactit で作っています。現在は公開前です。
スクリプトはそれ単体で成立していて、untactit には依存しません。使えるところだけ使って、あとは無視してください。