AGENTS.md has one common problem: it keeps growing.
At first, it contains project rules.
Then someone adds build commands.
Then architecture notes.
Then decision history.
Eventually, it turns into another README.
I try to avoid that.
One File, One Responsibility
I do not keep AGENTS.md short because of an arbitrary line limit.
There is no widely accepted standard yet.
Instead, I ask a different question:
Does this help someone understand how to work with the project?
If the answer is “no”, the information probably belongs somewhere else.
Different Documents Hold Different Context
Most projects already have documents with well-defined responsibilities.
README explains what the project is.
ADR records why architectural decisions were made.
CHANGELOG tracks what has changed.
Technical documentation explains implementation details.
AGENTS.md should not replace any of them.
Its job is much simpler: provide the working context needed to interact with the project.
What I Keep
My AGENTS.md usually contains:
- the technology stack
- the repository structure
- engineering conventions
- project constraints
- documentation rules
- writing guidelines
That is enough for AI to understand the project’s boundaries.
It is also enough for me to restore context after a few months away from the project.
What I Leave Out
I deliberately avoid putting the following into AGENTS.md:
- project history
- changelog
- detailed architecture descriptions
- long command references
- API documentation
- anything already covered elsewhere
If a piece of text can be removed without losing meaning, it should be removed.
A Practical Rule of Thumb
I do not measure the file by the number of lines.
Instead, I ask a simple question:
Can I read it in one or two minutes?
If not, the file has probably started taking on responsibilities that belong to other documents.
Conclusion
A good AGENTS.md is rarely long.
Not because long files are inherently bad.
But because every document should hold one kind of context.
README explains what the project is.
ADR explains why decisions were made.
AGENTS.md explains how to work with the project.
Keeping those responsibilities separate makes the entire project easier to understand and maintain.