Should a Growing AGENTS.md Be Trimmed? — Change Decisions from an Audit of 29 Files

The Short Answer

I reviewed 29 AGENTS.md files across 22 repositories. The shortest was 22 lines, the longest 523 lines, and I found 83 blocks of shared text. Even so, all 29 files ended with the same decision: no change this time.

Line count and the amount of shared text were not enough to justify a change. What matters is whether there is a concrete operational problem, such as contradictory instructions, broken references, or rules whose priority is unclear.

Another practical approach is to treat AGENTS.md not as the place where everything must be written, but as an entry point. OpenAI's Codex guidance describes maintaining AGENTS.md as a place for repository-specific, persistent guidance. In its Harness Engineering article, OpenAI also describes an experience in which concentrating too much knowledge in a large AGENTS.md made important information harder to find and allowed stale rules to remain. That team came to use AGENTS.md more like a table of contents, with detailed information organized under docs/.

The rest of this article explains what was observed, what was in scope, and how those observations led to the decision above.

1. Why Does AGENTS.md Tend to Get Longer?

AGENTS.md does not grow by itself. Its contents only increase when a person or a tool modifies it.

In practice, however, additions are more likely than deletions. During AI-assisted work, for example, you may make decisions such as:

• “Check this document before starting work from now on.”
• “Do not write an unverified state as a fact.”
• “For this type of change, wait for human confirmation before executing it.”
• “Add a check so that the same incident does not happen again.”
• “Apply the existing operating rules to new repositories as well.”

Even when nobody explicitly says “add this to AGENTS.md,” AGENTS.md may be chosen as the place to preserve a rule that should remain in effect. A shared template may also add a large set of rules at once.

Deleting an existing rule is different: you need evidence that the rule is no longer necessary. Otherwise, a rule removed as “probably obsolete” may turn out to have been preventing an incident.

A new decision or incident-prevention rule appears
        |
        v
Keep it as a rule for future work
        |
        v
Keep existing rules unless there is a reason to remove them
        |
        v
The document may grow gradually, or become much larger at once

The issue here is not “uncontrolled bloat.” It is an operating structure in which rules are easy to add, while deletion tends to require justification.

2. Not Every Environment Has the Same Problem

In environments with controls such as the following, AGENTS.md may be less likely to grow without discipline:

• Human approval is required before AGENTS.md can be changed.
• Shared rules are managed centrally in another template or policy file.
• AGENTS.md contains only entry-point guidance, while detailed rules live in separate documents.
• The file is generated automatically and manual additions are prohibited.
• The tools an AI can use, or the scope it can modify, are constrained by mechanisms outside the file itself.

Even then, the accumulation may simply move from AGENTS.md into a shared template or policy layer.

Among the 29 files reviewed here, 27 contained wording related to change control, and 23 contained reference terms indicating templates, shared policies, or similar mechanisms.

The presence of such wording does not mean the control actually works. This audit examined document structure and history; it did not evaluate how the AI actually behaved.

3. Is a Long AGENTS.md Bad?

The 29 files had the following line counts.

Of the 29 files, 24 had 199 lines or fewer. Five files had 300 lines or more, and the longest had 523 lines.

This distribution did not support a threshold such as “more than 500 lines is too long.” No change justification was found even for the 523-line file, and there was no evidence that the 22-line file was inherently better.

Line count alone was not enough to determine whether a file needed to be changed.

Length can be a reason to inspect a file more closely. That is as far as this dataset supports.

4. “Can Be Shortened” Is Not the Same as “Should Be Shortened”

If you ask an AI to “clean up redundant parts,” it can find similar passages and combine them. But in operational rules, repeated wording is not automatically waste.

Two similar warnings may apply to different contexts, such as routine work and production work. A critical rule may intentionally appear in more than one place so that it is noticed before a high-risk operation. A shared rule may also be copied deliberately so that each repository remains usable on its own.

For that reason, I did not treat deleted line count, compression percentage, or the number of findings as success metrics for the audit. If shortening is made the goal first, prerequisites, exceptions, evidence, and incident-prevention guidance can all become deletion candidates.

Being able to shorten something does not mean you should.

5. The First Audit Ended as an Operational-State Check

The first audit was not performed to support an article. Its purpose was to check whether the actual operating state contained a problem. I reviewed 29 AGENTS.md files across 22 repositories without modifying them.

I did not find a clear contradiction that required immediate correction or an obviously broken reference. Similar shared rules appeared across multiple repositories, but similarity alone was not enough to justify deletion or consolidation.

All 29 files therefore ended with the result no change this time, and the audit ended there. I did not repeat the same audit in search of a more convenient result for publication.

6. A Separate Reproducibility Check Was Performed for the Article

For publication, a third party should be able to follow how the inspection was performed. I therefore fixed a publishable audit procedure and ran a separate read-only check against the same environment.

The first result was not treated as the correct answer. I did not assume that “there were 29 files last time, so there must be 29 files again.” The scope was searched again, and the number actually discovered was used.

The result was again 22 repositories and 29 files.

The detailed procedure used for this reproducibility check has been prepared as a separate reference document. In the public version, local directory names, internal work names, and other environment-specific details are generalized, while the audit conditions and decision criteria are preserved.

7. What Did the Reproducibility Check Measure?

The audit focused mainly on things that could be counted mechanically:

• Exact line counts
• Character counts and file sizes
• Numbers of headings, bullet items, tables, and code blocks
• Blocks of text that matched exactly across multiple files
• Growth patterns observable from Git history
• Presence of wording related to change control or shared policy references

The following were not evaluated:

• Whether each individual rule was correct
• Whether prohibitions were too strict
• Whether the AI actually followed the rules
• Whether the rules prevented incidents
• A ranking of the “best” or “worst” AGENTS.md
• How many lines could be removed

The scope was limited to what could be observed about document size, structure, and change over time. The validity of individual rules and the AI’s actual behavior were outside this audit.

8. The 29 Files Did Not Grow in the Same Way

For the 17 files whose growth patterns could be classified from Git history, three patterns were observed.

Even within this one environment, the files could not be explained by a single pattern such as “AGENTS.md gradually gets longer over time.” Some files received a shared template all at once; others continued to grow after an initial large addition.

For 12 files, there was not enough Git history to classify the growth pattern. Those cases were left unknown rather than filled in with assumptions about the past.

9. Eighty-Three Shared Text Blocks Do Not Mean “83 Problems”

Comparing the AGENTS.md files found 83 blocks in which three or more consecutive lines matched exactly across files.

I did not count those 83 blocks as 83 problems. If several repositories use a shared template, identical wording is expected. The same warning may also be placed intentionally in multiple repositories so that each repository can be handled independently.

Text being identical or similar is also different from the meaning being redundant and safe to consolidate. The mechanical comparison established text matches only; it did not automatically classify them as semantic duplication.

10. Why Were None of the 29 Files Changed?

The audit produced observations about line-count variation, growth patterns, shared text, and references to change-control or template mechanisms. Those observations were useful inputs, but they were not change justifications by themselves.

To recommend a change, there should be a condition that can be explained as “this causes a problem if left as-is,” for example:

• Rules that cannot both be true at the same time
• References to files or locations that no longer exist
• Rules with the same role spread across multiple places so that their priority is unclear
• A rule that was intended to be temporary but now conflicts with current operations
• The same content repeated several times without an explainable reason for keeping it

The reproducibility check did not identify a clear problem that justified a change. All 29 files were therefore classified as no change this time.

To make that outcome possible, the audit included no change as an explicit completion state from the beginning.

Was a problem confirmed?
   |
   +-- No  -> No change this time -> Complete
   +-- Yes -> Check the justification
                  |
                  +-- Not enough to justify a change -> No change this time
                  +-- Sufficient justification       -> Human review, then modify

If an AI is given a target such as “make it 30% shorter” or “remove 10 duplicates,” it is likely to search for edits that satisfy that target. In operational rules, however, “something that can be deleted” and “something that should be deleted” do not necessarily mean the same thing.

The outcome measured by this audit was therefore not the amount of change, but whether the observations supported a decision to change something or to stop without changing it.

11. A Practical Maintenance Procedure

In practice, it is useful to separate decision principles from the actual workflow.

Decision Principles

• Treat length as a reason to inspect, not as the decision itself.
• Separate observed facts from change decisions. “The same text exists” and “it is unnecessary and can be deleted” are different statements.
• Ask whether the information belongs at the entry point or in a detailed document. Separate information the AI needs to see first from details that can be consulted only when needed.

Workflow

12. What This Audit Does Not Establish

This audit covered one operational environment. It is not a statistical study representative of all AGENTS.md users.

Therefore, it does not establish that:

• Every AGENTS.md gets longer over time
• There is a correct maximum line count
• A long AGENTS.md reduces AI performance
• A shorter AGENTS.md has higher quality
• Shared text should be deleted
• The presence of change-control wording means the environment is safe
• The growth-pattern ratios observed here also apply to other environments

Nor can this audit support a general rule such as “AGENTS.md should be around 100 lines.” Any line count mentioned in the external example is specific to that environment.

The audit also did not evaluate the AI’s actual behavior. For the 12 files with insufficient Git history, past growth patterns were not inferred or reconstructed.

These numbers should be read only as a case study observed in one environment.

13. Summary

The read-only review of 29 files produced observations about line count, growth patterns, and shared text, but those observations alone did not justify a change.

When assigning maintenance work to an AI, do not make the amount of change the success condition in advance. Observe first, determine whether there is justification for a change, and modify only the necessary scope when such justification exists. With that order of operations, making no change is not an abnormal outcome; it is one possible result of the decision process.

References

• OpenAI, How OpenAI uses Codex
  Describes using AGENTS.md to provide persistent repository-specific guidance.
  https://openai.com/business/guides-and-resources/how-openai-uses-codex/
• OpenAI, Harness engineering: leveraging Codex in an agent-first world, 2026-02-11
  Describes experience with concentrating knowledge in a large AGENTS.md and an example of using it as an entry point instead.
  https://openai.com/index/harness-engineering/
• Appendix: AGENTS.md READ-ONLY Audit Protocol (public version with environment-specific details generalized)
  A reference document based on the actual audit conditions used for the reproducibility check, with local paths, internal work names, and other details unnecessary to third parties generalized for publication.
  Open the English public audit protocol PDF

Study Limitations

• The audit covered one operational environment.
• It is not a statistical sample representative of all AGENTS.md usage.
• File length was not treated as a quality score.
• The reproducibility check did not deeply evaluate the content of individual rules.
• The AI’s actual behavior was not evaluated.
• The presence of change-control wording does not prove that the control is effective.
• Twelve of the 29 files lacked enough Git history to classify their growth pattern.