AGENTS.mdは長くなったら削るべきか — 29ファイルの監査から考える変更判断

Overview

はじめに

AIにリポジトリ内で作業してもらうとき、AGENTS.md に「このプロジェクトではこう動いてほしい」というルールを書いておくと便利です。命名規則、確認してほしい文書、触ってはいけない範囲、テスト方法などを、毎回の会話で説明し直さずに済むからです。

運用を続けると、別の疑問が出てきます。

AGENTS.mdが長くなってきた。定期的に整理した方がよいのでは？

そこで、実際の環境を変更せずに調べました。対象は22のリポジトリにあった29個の AGENTS.md です。

この記事で扱うのは、AGENTS.md を短くする技法ではありません。どの観測を変更理由として扱い、どこで変更しないと判断するかです。

Conclusion

結論から言うと

22のリポジトリにある29個の AGENTS.md を調べました。最短は22行、最長は523行で、共通する文章のまとまりは83件見つかりました。それでも29ファイルすべてで「今回は変更しない」という判断になりました。

行数や共通する文章の多さだけでは、変更を正当化できなかったためです。変更候補として見るべきなのは、矛盾した指示、壊れた参照、優先順位が分からないルールなど、現状の運用に具体的な問題を生む状態です。

もう一つ実用的なのは、AGENTS.md を「全部を書く場所」ではなく「入口」として使う考え方です。OpenAIのCodex利用ガイドでは、AGENTS.md をリポジトリ固有の継続的な情報を与えるために保守する方法が紹介されています。またHarness Engineeringの記事では、大きな AGENTS.md に知識を集約した結果、重要な情報を見つけにくくなり、古いルールも残りやすくなった経験が説明されています。そのチームでは AGENTS.md を百科事典ではなく「目次」のように使い、詳しい情報を構造化した docs/ へ分けています。

以下では、この結論に至るまでに何を観測し、どこまでを調査対象にしたのかを順に示します。

Context

1. AGENTS.mdは、なぜ長くなりやすいのか

AGENTS.md が自動的に増えるわけではありません。誰か、または何らかのツールが書き換えなければ内容は増えません。

それでも、運用上は追加の方が削除より起こりやすくなります。たとえばAIとの作業中に、次のような判断をすることがあります。

「次からは作業前にこの文書を確認する」
「未確認の状態を事実として書かない」
「この種類の変更は、人が確認してから実行する」
「前回と同じ事故を起こさないように確認項目を追加する」
「新しいリポジトリにも既存の作業ルールを適用する」

「AGENTS.mdへ追記して」と明示していなくても、将来も使うルールの保存先として AGENTS.md が選ばれることがあります。共通テンプレートの導入によって、まとまったルールが一度に追加される場合もあります。

一方、既存ルールを消すには、そのルールが不要になったと判断できる材料が要ります。「不要だと思って消したルールが、実は事故防止に必要だった」という可能性があるためです。

新しい判断や事故対策が生まれる
        ↓
将来も使うルールとして残す
        ↓
既存ルールは念のため残す
        ↓
文書が少しずつ、または一度に大きくなることがある

ここで問題にしているのは「勝手な肥大化」ではなく、追加しやすく、削除には根拠を求めやすい運用構造です。

Scope

2. すべての環境で同じ問題が起きるわけではない

すでに次のような仕組みを持つ環境では、AGENTS.md が無秩序に増える可能性は低くなります。

AGENTS.md の変更に人の承認を必須にしている
共通ルールを別のテンプレートやポリシーファイルで一元管理している
AGENTS.md には入口だけを書き、詳しいルールは別文書へ分けている
自動生成ファイルとして管理し、手作業での追記を禁止している
AIが使えるツールや変更範囲を、ファイルの外側の仕組みで制限している

ただし、蓄積場所が AGENTS.md から共通テンプレートやポリシー側へ移るだけの場合もあります。

今回の29ファイルでは、27ファイルに変更制御に関係する記述があり、23ファイルにはテンプレートや共通ポリシーなどを示す参照語がありました。

記述があることと、制御が実際に機能していることは別です。 今回は文書の構造や履歴を調べただけで、AIが実際にどのように動いたかまでは評価していません。

Measurements

3. 長いAGENTS.mdは悪いのか

29ファイルの行数は次の通りでした。

指標	行数
最小	22
最大	523
平均	153
中央値	123
25%点	66
75%点	165

29ファイル中24ファイルは199行以下でした。一方で300行以上のファイルが5件あり、最長は523行でした。

この分布から「500行を超えたら長すぎる」といった閾値は導けませんでした。523行のファイルを含めて変更根拠が確認できず、逆に22行のファイルが特別に優れていると判断できる材料もなかったからです。

行数だけでは、直す必要があるか判断できなかった。

長さは、詳しく確認するきっかけにはなります。今回のデータから言えるのはそこまでです。

Principle

4. 「短くできる」と「短くすべき」は違う

AIに「冗長な部分を整理して」と頼めば、似た文章を見つけて統合することはできます。しかし運用ルールでは、同じ文章が複数あること自体が無駄とは限りません。

同じ注意でも、片方は通常作業、もう片方は本番作業に対する注意かもしれません。重大な事故を防ぐため、重要なルールを別の場所でも確認させている場合もあります。各リポジトリを単独で使えるよう、共通ルールを意図的にコピーしていることもあります。

このため、削除した行数、短縮率、見つけた問題の数を監査の成果指標にはしませんでした。短くすることを先に目標へ置くと、前提条件、例外、根拠、事故防止の注意まで削除候補になり得ます。

短くできることと、短くすべきことは同じではない。

Audit

5. 最初の監査は「運用状態の確認」として完了させた

最初に行ったのは記事を書くための調査ではなく、実際の運用状態に問題がないかを確認する監査でした。22のリポジトリから29個の AGENTS.md を変更せずに確認しました。

すぐに直す必要がある明確な矛盾や、壊れた参照先は見つかりませんでした。複数のリポジトリに似た共通ルールはありましたが、それだけでは削除・統合の根拠にはなりませんでした。

結果は29ファイルすべて「今回は変更しない」で、この監査はその時点で完了させました。記事を書くために、同じ監査を繰り返して都合のよい結果を探すことはしていません。

Reproducibility

6. 記事用には、別の再現確認を行った

公開記事にするなら、第三者が「どのように調べたのか」を追える必要があります。そこで最初の監査とは別に、公開できる監査手順を固定し、同じ環境をもう一度読み取り専用で調べました。

このとき、最初の結果を正解として扱っていません。「前回29ファイルだったから今回も29ファイルのはず」とはせず、対象をもう一度検索し、実際に見つかった数を使いました。

結果として、22リポジトリ・29ファイルが再び見つかりました。

再現確認で使った詳細な監査手順は、記事本文とは別の参考資料として公開できる形にしています。公開版ではローカルのディレクトリ名や内部の作業名など、特定環境だけに通じる情報を一般化していますが、監査条件や判定条件は変えていません。

Scope

7. 再現確認では何を調べたのか

主に機械的に数えられるものを調べました。

正確な行数
文字数とファイルサイズ
見出し、箇条書き、表、コードブロックの数
複数ファイルで完全一致する文章のまとまり
Git履歴から確認できる増加パターン
変更制御や共通ポリシーを示す記述の有無

一方、次のことは調べていません。

個々のルールが正しいか
禁止事項が厳しすぎるか
AIが実際にそのルールを守ったか
ルールが事故を防いだか
「最も良いAGENTS.md」「最も悪いAGENTS.md」の順位付け
何行削れるか

調査対象は、文書の大きさ・構造・変化として観測できる範囲です。個々のルールの妥当性や実際のAI行動は、この監査の外に置きました。

History

8. 29ファイルは、同じ増え方をしていなかった

Git履歴から増え方を分類できた17ファイルでは、次の3種類が見つかりました。

増え方	ファイル数
複数回の変更で少しずつ増えた	5
一度の導入で大きく増えた	5
大きな導入後にも追加が続いた	7
履歴不足で分類できない	12

今回の環境だけを見ても、「AGENTS.mdは時間とともに少しずつ増える」という一つのパターンでは説明できませんでした。共通テンプレートを一度に入れたファイルもあれば、その後の運用で追加が続いたファイルもあります。

12ファイルは分類に必要なGit履歴が足りませんでした。分からないものは分からないまま残し、過去を推測で補完していません。

Duplication

9. 共通する文章が83件あっても、「83件の問題」ではない

複数の AGENTS.md を比べると、3行以上連続して一致する文章のまとまりが83件見つかりました。

しかし、この83件を問題件数とは数えていません。共通テンプレートを使えば同じ文章が複数のリポジトリに存在するのは自然ですし、各リポジトリを単独で扱えるよう意図的に同じ注意を置くこともあります。

また、文字列が同じ・似ていることと、意味まで同じで統合可能であることは別です。今回の機械的な比較で確認したのは文章の一致までで、意味が重複しているとは自動判定しませんでした。

Decision

10. なぜ29個とも変更しなかったのか

ここまでで確認したのは、行数のばらつき、増加パターン、共通する文章、変更制御やテンプレートへの参照です。これらは監査の材料にはなりましたが、それ自体は変更理由ではありませんでした。

変更を勧めるには、たとえば次のように「このままでは困る」と説明できる状態が必要です。

同時には成立しないルールが書かれている
すでに存在しないファイルや場所を参照している
同じ役割のルールが複数箇所に分かれ、どちらを優先するか分からない
一時的だったはずのルールが現在の運用とぶつかっている
同じ内容が何度も現れるが、残す理由を説明できない

再現確認でも、変更を正当化できる明確な問題は確認できませんでした。そのため、29ファイルすべてを「今回は変更しない」と判定しました。

この判定を可能にするため、監査には最初から「変更なし」の終了状態を置いています。

問題が確認できたか？
   |
   +-- いいえ -> 今回は変更しない -> 完了
   +-- はい   -> 根拠を確認
                    |
                    +-- 変更するほどではない -> 今回は変更しない
                    +-- 変更する根拠が十分   -> 人が確認してから修正

AIに「30%短くして」「重複を10件なくして」のような目標を与えれば、その数値を達成する方向へ変更候補を探しやすくなります。運用ルールでは「削れる場所」と「削ってよい場所」が一致するとは限りません。

したがって、この監査で成果として扱うのは変更量ではなく、観測結果に応じて変更するか、変更せず終了するかを判定できたことです。

Practice

11. 実際にメンテナンスするなら

実務では、判定原則と工程を分けておくと扱いやすくなります。

判定原則

長さは判定ではなく確認のきっかけにする。
観測事実と変更判断を分ける。 「同じ文章がある」と「不要だから削れる」は別です。
入口に置く情報か、詳しい別文書へ分ける情報かを問う。 AIが最初に読む必要がある情報と、必要なときに参照すればよい詳細を分けます。

変更根拠がない場合は停止し、根拠がある場合だけ人の承認へ進みます。

読み取り専用で調べる。行数、参照先、明確な矛盾、重複候補などを確認します。
変更根拠を判定する。根拠がなければ、その時点で終了します。
必要な場合だけ人が対象を確認する。監査と修正を分け、本当に変更する部分だけを選びます。
承認した範囲だけ変更する。関係ないルールまでまとめて整理しません。
修正後に再確認する。新しい矛盾や参照切れが生まれていないか確認します。

Limitations

12. この調査からは言えないこと

今回の調査は一つの実運用環境だけを対象にしています。すべての AGENTS.md 利用者を代表する統計調査ではありません。

したがって、次のことは結論できません。

すべての AGENTS.md が時間とともに長くなる
適切な行数の上限がある
長い AGENTS.md はAIの性能を下げる
短い AGENTS.md の方が品質が高い
共通する文章は削除すべきである
変更制御の記述があれば安全である
今回の増加パターンの比率が他の環境でも同じになる

「AGENTS.mdは100行程度にすべき」といった一般的な行数基準も、この調査からは導けません。参考として紹介した行数は、その環境固有の一例に過ぎません。

また、実際のAIの行動までは評価していません。Git履歴が不足していた12ファイルについては、過去の増え方を推測して補完しませんでした。

今回の数字は、あくまで一つの環境で観測したケーススタディです。

Summary

13. まとめ

29ファイルを読み取り専用で確認した結果、行数、増加パターン、共通文章の存在は観測できましたが、それらだけでは変更を正当化できませんでした。

AIに保守を任せるときは、変更量を先に成果へ置かず、まず観測し、変更根拠を判定し、必要な場合だけ対象を限定して修正する。この順序にしておけば、変更しないことも異常ではなく、判定の結果として扱えます。

References

参考資料

OpenAI, How OpenAI uses Codex
AGENTS.md を、リポジトリ内で継続的に参照する情報を与える方法として紹介。
https://openai.com/business/guides-and-resources/how-openai-uses-codex/
OpenAI, Harness engineering: leveraging Codex in an agent-first world, 2026-02-11
大きな AGENTS.md に知識を集約した経験と、入口として使う設計例を紹介。
https://openai.com/index/harness-engineering/
別紙: AGENTS.md READ-ONLY監査プロトコル（公開用・環境固有情報を一般化）
本記事の再現確認で実際に使用した監査条件をもとに、ローカルパスや内部の作業名など第三者には不要な固有情報だけを一般化した参考資料。
公開版監査プロトコルPDFを開く

Constraints

調査上の制約

ファイルの長さを品質点として扱っていない。
再現確認では、個々のルール内容を深く評価していない。
変更制御に関する記述が存在しても、その制御が有効であることまでは証明していない。