先に要点
- AGENTS.md が長すぎると、AIは `全部を丁寧に守る` より先に、重要ルールを見失いやすく なります。
- 崩れやすくなる主因は、起動時から文脈を圧迫すること、大事な指示が途中に埋もれること、古いルールや局所ルールまで混ざって競合すること です。
- OpenAI の Codex 公式は AGENTS.md を `Keep it small` と案内し、Anthropic の Claude Code 公式も `短く具体的に、1ファイル200行未満を目安` と案内しています。
- 対策は、repo全体で毎回必要なことだけを上位ファイルへ残し、パス別ルール、毎回のプロンプト、検証コマンドへ分解すること です。
ルールを増やせば増やすほど、AIは賢く動くはず。
最初はそう考えがちですが、実際の AI コーディングでは逆に崩れることがあります。
たとえば、Codex や Claude Code に
- プロジェクト概要
- 触ってはいけない場所
- テスト手順
- コーディング規約
- 過去の失敗メモ
- 一時的な依頼
- 特定ディレクトリだけの例外運用
を全部まとめて長い AGENTS.md に入れていくと、最初は便利でも、だんだん テストを飛ばす 不要なファイルまで読む 局所ルールを全体ルールだと誤解する 途中で別の方針に流れる といった崩れ方が増えやすくなります。
この記事では、2026年4月28日時点で OpenAI Codex、OpenAI の GPT-5 prompting guide、Anthropic Claude Code、長文脈の代表研究として知られる Lost in the Middle を確認しながら、なぜ長い AGENTS.md が AI コーディングを不安定にするのか を整理します。
md ルールファイル全体の置き場から見たい場合は、AIコーディングで使うmdファイルとは？AGENTS.md・CLAUDE.md・指示書の役割を整理 を先に読むと流れがつかみやすいです。
まず前提：AGENTS.mdは設定ファイルではなく文脈
ここを最初に押さえたいです。
AGENTS.md に書いた = 強制される ではありません。
AI コーディングツールにとって AGENTS.md は、かなりざっくり言うと 作業前に読む追加コンテキスト です。
つまり、コンテキストエンジニアリング の一部です。
OpenAI の Codex ドキュメントでも、AGENTS.md は repo と一緒に持ち運べる durable guidance として案内されつつ、Keep it small と明記されています。
Anthropic の Claude Code ドキュメントでも、具体的で短く、構造化された指示ほど従いやすい、長いファイルは文脈を消費し adherence を下げる と説明されています。
この前提に立つと、長い AGENTS.md が不利なのは不思議ではありません。
設定を増やしているのではなく、毎回読む前提情報を増やしているからです。
AI の入力全体を先に整理したい場合は、AIのコンテキストとは？プロンプト・会話履歴・RAGとの違いを整理 もつながります。
AGENTS.mdが長すぎると崩れやすい理由
1. 起動直後から文脈を圧迫する
長い AGENTS.md は、セッションの最初からコンテキストを消費します。
しかも AI コーディングでは、ルールファイルだけでなく、会話履歴、読んだソース、ツール出力、diff、テスト結果も後からどんどん積み上がります。
そのため、最初に重いファイルを抱えた状態で始めるほど、途中から
- 古い会話を要約する
- 関連しない履歴を切り捨てる
- 重要な前提を圧縮して持ち回る
場面が増えます。
これは 上限に達した瞬間に急に壊れる というより、余裕が減るほど判断が雑になりやすい という見方の方が実務に近いです。
トークン 消費も増えるので、精度だけでなくコスト面でも不利になります。
2. 重要な指示が途中に埋もれる
長文脈の研究としてよく引用される Lost in the Middle では、関連情報が入力の先頭や末尾にあるときの方が使われやすく、中ほどにあると性能が落ちやすい傾向が報告されています。
AGENTS.md でも同じことが起きます。
本当に守ってほしいのが
テストは必ず実行する本番DBへ接続しない既存変更を勝手に戻さない
のような数行なのに、その前後へ長い背景説明、過去の議論、今は使わない手順、細かな例外を大量に入れると、肝心のルールが中ほどへ沈みます。
結果として AI は
- 雰囲気は理解している
- でも最重要ルールを毎回きれいに再現できない
という崩れ方をしやすくなります。
OpenAI の GPT-5 prompting guide でも、構造化され scoped な prompt の方が reliable だとされ、過度に 徹底的に全部調べろ といった書き方は逆効果になりうると紹介されています。
つまり、情報量が多いほど強い のではなく、重要な判断材料へ焦点を合わせた方が強い ということです。
3. 古いルールや競合ルールが増える
長い AGENTS.md が危ないのは、単純な文字数だけではありません。
本当にきついのは、今の repo に必要なルール と 昔のメモ と 一時的な運用 が混ざることです。
たとえば、こういう状態です。
- 旧ディレクトリ構成の説明が残っている
- 今は廃止した手順がそのままある
- ある章では
積極的に自動実行してよい、別の章では必ず確認してから進めると書いてある - repo 全体のルールに、特定サブディレクトリだけの例外が混ざっている
Anthropic のドキュメントでも、矛盾するルールがあると Claude may pick one arbitrarily と説明されています。
つまり、AI が勝手なのではなく、どのルールを採るべきか人間側が曖昧にしている ことが多いです。
4. repo全体のファイルに、局所ルールまで詰め込みがち
長い AGENTS.md が育つときによくあるのが、本当は特定ディレクトリでしか使わないルール を全部ルートに置くことです。
たとえば、
まで repo 全体の AGENTS.md に書くと、AI は関係ない作業でもそれらを毎回抱えて始めます。
その結果、
- 単純な修正なのに探索が広がる
- 触らないはずの周辺領域まで気にし始める
- 関係のない制約でためらう
といったノイズが増えます。
OpenAI も Anthropic も、近い場所にルールを置く、path-scoped に分ける、task-specific なものは別の仕組みに逃がす、という方向を勧めています。
1ファイルに全部載せる ではなく、必要なときだけ必要なルールが入る 状態の方が安定しやすいです。
5. 長いセッションになるほど、効きが薄く見えやすい
AI コーディングでは、最初に AGENTS.md を読んで終わりではありません。
そのあとにファイル読解、コマンド実行、テスト失敗、再探索、追加修正が続きます。
この途中で履歴が膨らむと、最初に渡した大きな文脈 は相対的に埋もれやすくなります。
Claude Code が /compact や /clear のような文脈整理手段を持っているのも、この問題が実務で頻発するからです。
なので、長い AGENTS.md は 最初は効いていたのに、途中から崩れた という体感につながりやすいです。
これは AI が気分で忘れたというより、セッション全体の文脈管理で不利になっていると考える方が自然です。
「長すぎる」の正体は文字数より中身
何行から危険ですか と聞かれることがありますが、そこは固定しにくいです。
ただし実務では、次の状態になると危険信号です。
| 状態 | なぜ危ないか |
|---|---|
| 毎回使わない手順まで大量に入っている | 無関係な作業でもノイズとして読み込まれる |
| 歴史的メモと現行ルールが混ざっている | どれが現在有効なのか曖昧になる |
| 抽象論が多く、検証可能な指示が少ない | AIが行動へ落とし込みにくい |
| 例外ルールが増えすぎている | 通常ルールとの優先順位が崩れる |
| 一時依頼を恒久ルールとして残している | 今の作業と無関係な制約が毎回乗る |
Claude Code 公式は CLAUDE.md について 200 lines を目安に案内していますが、ここで大事なのは数値そのものより、毎回必要なことだけを残す という考え方です。
Codex の AGENTS.md でも同じ発想で見た方が実務では失敗しにくいです。
崩れにくくする直し方
1. ルートのAGENTS.mdは「毎回必要な最小セット」に絞る
ルートへ残すのは、たとえば次のようなものです。
逆に、1回限りの事情、特定チームだけのメモ、長い背景説明は外した方が安定します。
2. 局所ルールは近い場所へ逃がす
payments/ だけの注意は payments/ に近いルールへ、docs/ だけの文体は docs/ 側へ寄せる方が素直です。
記事全体としての使い分けは、AIコーディングで設定すべきものは？mdファイル・memory・rulesの使い分け でも整理しています。
3. 一時的な依頼は毎回のプロンプトへ出す
たとえば
今日は実装せず原因調査だけ今回は本番反映しないこのPRでは互換性維持を最優先
のような情報は、恒久ルールではなく今回の依頼です。
これを AGENTS.md に積み増すと、あとからノイズになります。
4. 抽象論より、検証できる指示へ書き換える
悪い例:
- 品質に気をつける
- なるべく安全に進める
- 必要ならテストする
良い例:
- 変更後は `npm test` を実行する
- `apps/billing/` では金額計算ロジックを勝手に簡略化しない
- ユーザーの既存変更を勝手に戻さない
AI にとって効くのは、立派な理念より 何をする / 何をしない / どう確認する が分かる書き方です。
5. proseだけに頼らず、仕組みで支える
AGENTS.md に 必ずテスト と書くだけでは限界があります。
本当に大事なら、
のような仕組み側でも支えた方が強いです。
OpenAI の Codex ドキュメントでも、AGENTS.md と pre-commit hooks や linters を組み合わせる考え方が案内されています。
つまり、ルールを長文で背負わせるより、守るべきことを自動検出できる形へ寄せる 方が崩れにくいです。
こんな症状が出たら、長すぎるAGENTS.mdを疑いたい
- AI が毎回、関係ない資料まで読み始める
- 小さな修正なのに探索が広がりすぎる
- 最重要ルールだけ時々抜ける
- 同じ repo なのに、日によって判断がぶれる
- 過去の一時運用を今でも守ろうとする
書いてあるのに効かない感覚が強い
この状態なら、AI が賢くないというより、前提情報の設計が太りすぎている 可能性があります。
無視される 側から原因を追いたい場合は、AIがルールのmdファイルを無視する原因は？対応策を整理 もあわせて読むと分解しやすいです。
まとめ
AGENTS.md が長すぎると AI コーディングが崩れやすくなるのは、AI が長文を嫌うからではありません。
毎回読む前提情報としては重すぎて、重要ルールの優先順位、適用範囲、現行性が崩れやすくなる からです。
特に効きやすい整理は次の3つです。
- ルートの AGENTS.md は repo 全体で毎回必要な最小セットに絞る
- 局所ルールは近い場所や rules 系の仕組みに逃がす
- 一時依頼は今回のプロンプトに出し、恒久ルールへ混ぜない
長いほど安心 ではなく、短くても重要な判断が再現できるか で見ると、AI コーディングの安定性はかなり上がります。
コスト面も含めて見直したい場合は、AIツールのセッションやトークンを節約する方法｜無駄な会話・長文入力・モデル選びを見直す もつながります。
参考リンク
- OpenAI Developers: Customization - AGENTS Guidance
- OpenAI Developers: Analyze datasets and ship reports - Guide Codex's behavior
- OpenAI Developers: GPT-5 prompting guide
- Anthropic Claude Code Docs: How Claude remembers your project
- Anthropic Claude Code Docs: Claude Code GitHub Actions
- arXiv: Lost in the Middle: How Language Models Use Long Contexts