AI coding agents need context, and that part is obvious by now. What is less obvious is that context quality is only half the problem. The other half is context shape.
An instruction file that works well in one repository, one harness, or one workflow can be the wrong format for another. A dense single file may be perfect for one setup and awkward for another. A concise operational doc may be ideal in one environment and too shallow in another. A multifile structure may dramatically improve retrieval in one workflow while feeling unnecessary in a smaller repo.
So the real question is not only:
“Do you have an
AGENTS.md?”
It is also:
“Is it in the right format for the way your agent actually consumes it?”
That is the part I think we should talk about more.
Table of Contents
- Overview
- The Hidden Problem: Context Shape
- Why One
AGENTS.mdFormat Is Not Enough - Profiles: How Much Context Should an Agent Get
- Layouts: How Should Context Be Packaged
- Why the Best Format Depends on the Harness
- Single vs Split vs Multifile
- Why This Matters in Real Repositories
- Conclusion
Overview
A lot of discussion around coding agents still treats repository guidance as a content problem. The assumption is simple: if the instructions are correct, the agent should behave better. That is true, but it is also incomplete.
In practice, even good repository guidance can underperform when it is delivered in the wrong shape. A document can be accurate and still be too dense. It can be detailed and still be hard to navigate. It can be comprehensive and still be poorly suited to the way a given harness retrieves or loads information.
That means AGENTS.md is not just documentation. It is a delivery format for operational context, and as soon as you see it that way, the important design question changes. It becomes less about “write one good markdown file” and more about this:
What format gives this agent the best chance of using repository knowledge correctly?
The Hidden Problem: Context Shape
When an agent fails to follow repo conventions, we often blame the model. Sometimes that is fair, but sometimes the problem is much more boring than that. The instructions exist, the rules are written down, the commands are there, and the conventions are documented. The problem is that the information is packaged in a way that is awkward for the actual workflow.
That can happen in several ways. The document may be too long for the way the harness front-loads context. The operational rules may be buried under explanatory material. The file may be too concise and lack useful examples or nuance. The document may be logically organized for humans, but not for retrieval. Or the agent may be forced to repeatedly scan one large file when section-level access would work better.
In other words, the issue is not always missing context. Sometimes it is mis-shaped context, and that distinction matters because once you move from “missing information” to “information packaging,” the design space gets much more interesting.
Why One AGENTS.md Format Is Not Enough
There is a quiet assumption in a lot of agent workflows that AGENTS.md should always look roughly the same: one file, one structure, one level of detail, one universal best practice. That sounds neat, but real repositories do not behave that way.
A small service with a narrow stack does not need the same instruction surface as a polyglot monorepo. A repo with highly stable conventions does not need the same explanatory depth as one with lots of exceptions. A harness that pulls one root document into context does not behave the same way as one that can navigate multiple files more selectively.
So a single fixed format quickly starts to look less like a standard and more like an accidental constraint. The better framing is that AGENTS.md is not one artifact, but a family of possible context surfaces. Once you accept that, at least two dimensions become worth choosing deliberately: density, meaning how much detail to include, and layout, meaning how to package that detail.
Those two decisions matter much more than they usually get credit for.
Profiles: How Much Context Should an Agent Get
The first question is density: how much context should the agent actually receive? This is easy to underestimate because more detail often feels safer, but more detail is not always better. Too little context causes guessing, while too much context can create drag, bury key rules, or dilute what matters most.
That is why there is real value in separating at least two broad profiles.
Concise
A concise profile should focus on operational rules. It should answer things like where code goes, how tests are run, what formatting or linting tools are canonical, which naming conventions matter most, and what the agent must not do.
This format is useful when speed and clarity matter more than depth. It is often the better choice when the repository is relatively legible, when the harness already has decent retrieval behavior, or when you want the file to act as a sharp execution guide rather than a full repository reference.
Comprehensive
A comprehensive profile should keep the same core rules, but add richer explanation, examples, representative patterns, exceptions, and more supporting detail. This format is useful when the repository has a lot of nuance, when conventions are not obvious from source alone, or when the agent is likely to benefit from more supporting structure.
The important point is not that one is better. The important point is that they solve different problems. A concise file optimizes for directness, while a comprehensive file optimizes for coverage, and those are not the same objective.
Layouts: How Should Context Be Packaged
The second question is layout. Even if you know how much detail you want, you still have to decide how that detail should be delivered. This is where things get more interesting, because layout changes how context is navigated, retrieved, and reused.
Single File
The simplest option is one complete document. That has obvious benefits: it is easy to find, easy to version, easy to explain, and works well with simple workflows. A single-file layout is often the right baseline, but it is not automatically the best final form.
Split Layout
A split layout separates the document into two levels: a concise operational primary file and a deeper companion reference. This is useful because it preserves a clean entrypoint without losing richness. The primary file stays sharp, while the companion file holds the expanded explanation.
That structure mirrors how many people actually want agent instructions to behave: one file for immediate execution, another for deeper context when needed.
Multifile Layout
A multifile layout goes one step further. Instead of one document with many sections, it creates a root entrypoint plus separate files for areas like testing, formatting, naming, imports, git workflow, tooling, or red lines.
This is not just a documentation choice. It is a retrieval choice.
In some workflows, section-level access is much better than forcing the agent to traverse a single long markdown file repeatedly. That becomes especially true when the repository is large, when different categories of convention are independently important, when the harness benefits from targeted reads, or when different tasks repeatedly touch different instruction subsets.
Again, none of these layouts is universally best. They are different answers to different consumption patterns.
Why the Best Format Depends on the Harness
This is probably the most important point in the whole article. The right format depends not only on the repository, but also on the harness, because different agent environments do not consume instructions the same way.
Some front-load a single root document. Some can navigate multiple files more intelligently. Some behave better with compact operational instructions, while others benefit from richer references they can consult selectively. Some workflows are highly interactive, while others are deterministic and closer to batch processing.
So when people ask what the ideal AGENTS.md looks like, I think the honest answer is this:
There is no ideal AGENTS.md independent of the consumption model.
There is only the best fit for the repository, the task, the harness, the retrieval style, and the context budget. That is why format should be a design choice, not an afterthought.
Single vs Split vs Multifile
A practical way to think about it is fairly simple.
Use a single file when you want the lowest-friction default. This works well for straightforward repositories, smaller projects, or harnesses that just want one obvious source of truth.
Use a split layout when you want a clean operational layer plus deeper reference material. This is a strong middle ground because it keeps the entrypoint lean while still preserving richer explanation nearby.
Use a multifile layout when you want the instructions to be navigable as a structured knowledge surface, not only as one long document. This becomes more compelling as repositories grow, conventions become more layered, or workflows benefit from targeted section retrieval.
The important thing is not to over-theorize it. Just ask:
How will this agent actually read and use the guidance?
That question usually points to the right format much faster than abstract style preferences do.
Why This Matters in Real Repositories
This matters because agent failures are often more structural than they look. An agent that uses the wrong test command may not need better reasoning; it may need better command discoverability. An agent that violates naming conventions may not need stronger coding ability; it may need the naming rules surfaced more directly. An agent that keeps missing repo-specific constraints may not need more context in the abstract; it may need context that is easier to retrieve at the right moment.
That is why I think context design deserves more engineering attention. Not just the content, but the delivery mechanism.
If we care about repository alignment, we should care about what is included, what is omitted, how it is grouped, how it is accessed, how much context is presented up front, and how much is left available as deeper reference. That is not documentation polish. It is part of the runtime interface between the repository and the agent.
Conclusion
A good AGENTS.md is not only about accuracy. It is about fit: fit to the repository, fit to the task, fit to the harness, and fit to the way context is actually consumed.
That is why I do not think AGENTS.md should look the same everywhere. Some projects need one concise operational file. Some need a lean primary doc plus deeper companion material. Some need a structured multifile layout that behaves more like a retrieval surface than a static note.
The important shift is this:
Stop thinking of AGENTS.md as a fixed document template. Start thinking of it as a context interface.
Once you do that, density and layout stop looking cosmetic. They become part of the engineering problem.
So if you are working on agent workflows, that naturally leads to a more useful question:
Is your AGENTS.md written well, or is it also shaped well?
If the content shared in this post resonates, I've built Agentskill which already supports this approach with different profiles and layouts for shaping AGENTS.md, to fit both the repository and the harness that will consume it.
Consider leaving a star on GitHub.
Top comments (0)