AIに毎回渡す共通ルールが、2回ずつ読み込まれていた。公式の重複防止は、自作の仕組みには効かなかった
AIには、作業を始めるたびに共通ルールの文書を読ませている。Claude Code の公式ドキュメントで読み込みの仕組みを確かめていたら、その文書が二重に入る条件に手元の設定が当てはまっていた。
結論
共通ルール（当時約10KB）が、ルールを置いているリポジトリで作業するときだけ2回入っていた。自作の起動時の仕組みが全文を差し込み、さらにそのリポジトリの設定ファイルが同じ文書を読み込んでいた。Claude Code の重複防止が効くのは標準の読み込みどうしだけで、自作の差し込みは対象の外だった。起動時の仕組みに条件を1つ足し、単体で8通り、新しいセッションで3か所を確かめて、どこでも1回になった。トークン数は測っていない。
きっかけ
AIに作業を任せるとき、共通のルールを1つの文書（AGENTS.md）にまとめて、専用のリポジトリに置いている。以下、このリポジトリを「ルールの保管庫」と呼ぶ。Claude Codeが起動するたびに、自作の起動時の仕組み（SessionStartフック）がこの文書の全文を読み込ませていて、どのフォルダで作業していても入るようにしていた。
2026年9月22日、Claude CodeがAGENTS.mdをどう扱うかを公式ドキュメントで確かめていた。手元の設定と比べると、ルールの保管庫の中だけ条件が違っていた。保管庫の設定ファイル（CLAUDE.md）にも@AGENTS.mdと書いてあり、Claude Code標準の読み込みでも同じ文書が入る。そのセッションの最初の文脈を見ると、同じ文書が実際に2回入っていた。
公式ドキュメントが重複しないと保証しているのは、設定ファイルからの読み込みとAGENTS.mdの直接の読み込みのあいだだけ。自作の起動時の仕組みが差し込む文章は、その外にある。
やったこと
どこで2回になるか
作業する場所ごとに、入り方を整理した。
| 作業する場所 | 起動時の差し込み | 設定ファイルからの読み込み | 合計 |
|---|---|---|---|
| ルールの保管庫 | 全文 | あり | 2回 |
| 保管庫の作業用コピー（worktree） | 本体側の全文 | コピー側の全文 | 2回（版が違う2つ） |
| ほかのリポジトリ | 全文 | なし | 1回 |
作業用コピーのほうは、本体の文書とコピーの文書という別の版が2つ入っていた。コピーで文書を書き換えていれば、書き換える前と後の2つの版を同時に読むことになる。
文書は約10KBあり、前日のルール整理で約18%増えていた。そのぶん、二重に払う量も増えていたことになる。
直し方は3つあった
| 案 | やること | 判断 |
|---|---|---|
| A | 起動時の仕組みに条件を足し、保管庫では全文の代わりに「読み込み済みなので省略」の1行だけ出す | 採用 |
| B | 保管庫の設定ファイルから @AGENTS.md を外す |
起動時の仕組みが動かない環境で、ルールが丸ごと消えるので採らない |
| C | 今のまま | 実害は小さいが、毎回同じ量を二重に読む |
起動時の仕組みは全部のプロジェクトにかかる設定なので、AIは3案を出して人間に選んでもらい、Aに決まった。
足した条件は2つで、作業している場所が保管庫そのものかその作業用コピーであることと、その場所の設定ファイルに@AGENTS.mdと書いてあること。両方そろったときだけ、全文の代わりに次の1行を出す。
[AI context] AGENTS.md is loaded by this repository's CLAUDE.md (@AGENTS.md import); hook injection of the body is skipped to avoid a duplicate.
判定の途中で何かが失敗したら、これまでどおり全文を差し込む。判定に失敗して、ルールがどこからも入らなくなることはない。変更前の仕組みは別のファイルに残してある。
確かめた
起動時の仕組みだけを動かして、8通りを確かめた。
| 場所 | 結果 |
|---|---|
| 保管庫、そのサブフォルダ、一時的な作業用コピー、既存の作業用コピー | 省略の1行 |
| ほかのリポジトリ2つ、Git で管理していないフォルダ、作業場所の指定が無いとき（今いるフォルダで判定） | 全文 |
設定ファイルから @AGENTS.md を外した作業用コピー |
全文（自動で戻る） |
そのうえで、新しいセッションを実際に起動して確かめた。
| 場所 | 起動時の差し込み | ルールの中身を聞いたとき |
|---|---|---|
| ルールの保管庫 | 0回（省略の1行だけ） | 正しく答えた（設定ファイルからの1回） |
| 保管庫の作業用コピー | 0回（省略の1行だけ） | 正しく答えた |
| ほかのリポジトリ | 1回 | 正しく答えた |
この記事を書いた2026年10月1日にも、起動時の仕組みを4か所で動かし直した。保管庫とそのサブフォルダでは省略の1行、この連載のリポジトリとGitで管理していないフォルダでは全文で、結果は変わっていない。文書はこの日の時点で約12KBになっていた。
わかったこと
公式の重複防止が対象にしているのは、公式の読み込みどうしだけだ。自分で起動時に文章を差し込む仕組みを作ると、その文章は公式の仕組みからは見えない。同じ文書を公式の読み込みでも読ませていれば、二重になる。
直すのは条件1つで済んだ。気づいたきっかけは、公式ドキュメントの記述を手元の設定と突き合わせたことで、何かが壊れて気づいたわけではない。
直し方を決めた場面については、後でAIの止まり方を振り返ったときの記録がある。元に戻せて影響も小さい技術的な選択を、3案を並べて人間に選ばせる形にしていた。記録では、本来は人間の確認程度かAIだけで決めてよかったもので、止まりすぎの例になりうる、としている。
確かめたのは1人の環境のClaude Code（当時の版）で、入った回数は最初の文脈を目で見て数えた。トークン数は測っていないので、二重に払っていた量は数字では言えない。Claude Codeの新しい版ではAGENTS.mdを直接読む機能が入るので、設定ファイル側の読み込み方が変わる可能性がある。