What is AGENTS.md and what goes in it?

AGENTS.md is a Markdown file in your repository root that AI coding agents read before they start work. Its own site calls it "a README for agents". It holds the build commands, test commands, code conventions and boundaries an agent would otherwise have to be told in every prompt. It is used by over 60,000 open-source projects and read by most of the coding agents in common use.

Why not put it in the README?

Because the two files have different readers. Writing one file for both makes it worse for each.

The AGENTS.md project explains the split clearly. READMEs "are for humans: quick starts, project descriptions, and contribution guidelines". AGENTS.md holds "the extra, sometimes detailed context coding agents need: build steps, tests, and conventions that might clutter a README."

The clutter point is the one that matters most. An agent needs detail that a human contributor does not: the exact test command with its flags, the directories not to touch, the reason a module is structured oddly. Put all of it in the README and the README gets worse for the people you want to attract. Leave it out and every agent has to work it out again, badly, in every session.

What belongs in it?

The convention has no required schema. That keeps it flexible, and it is also why most of these files are mediocre. Include anything an agent would otherwise have to guess:

• Build and test commands, exactly. Write the full command with its flags, and how to run a single test, instead of "run the tests". This section is worth the most, and it is the one most often too vague to use.
• Code style, as rules rather than adjectives. "Match the surrounding code" is unusable. "Two-space indent, named exports only, no default exports" is a rule an agent can follow and you can check.
• Boundaries. Generated directories, vendored code, anything where an edit will be silently reverted or will break a build in a way that looks unrelated.
• The non-obvious reason. Where the codebase does something surprising, say why. This section stops an agent from helpfully "fixing" a deliberate workaround.
• Commit and pull request conventions, if you have them, because otherwise you will be reformatting every message by hand.
• Security notes: what must never appear in code or logs, which credentials exist and where they live.

Test each line with two questions. Would an agent get this wrong without being told? Would that mistake cost me a round trip? If not, it is documentation, and it belongs somewhere else.

Where do teams get it wrong?

Four ways, roughly from most to least common.

Writing it once and never again. The file ends up describing a codebase that has since changed. A stale build command is worse than none, because the agent follows it confidently into a failure that looks like its own fault.

Filling it with adjectives. "Write clean, maintainable code" tells the agent nothing. Every line should be something you can check.

Making it enormous. Agents do worse as context gets longer. A file that tries to hold the complete architectural history buries the four commands that matter.

Assuming it is a control. This is the most important one, and it is why the file's popularity carries some risk. AGENTS.md is advisory. It holds instructions a cooperative agent reads, and nothing enforces any line of it. A "do not touch the payments module" written there is a request. It does not set a permission boundary, and you only see the difference on the day an agent does not follow it.

How does it relate to context engineering?

It is the cheapest and most durable part of it.

The 2026 consensus is that agents fail from missing context rather than from model weakness. Redis's survey found 73% of practitioners saying agents fail more often from broken context than broken models. AGENTS.md covers the most stable part of that context: what is true of the repository whatever task is being worked on.

It cannot carry the part that changes with each task: what this piece of work means, what would make it acceptable, and what evidence would show it was done. That is not a fact about the repository, so it does not belong in a repository file. Putting it there is how AGENTS.md files become enormous and stale at the same time.

So the two do different jobs. AGENTS.md says how work is done in this repository. The task says what this piece of work is and how you would know it worked.

Should you write one?

Yes, if agents touch your codebase at all. It takes half an hour. Every major agent reads it without configuration, and it is plain Markdown with nothing to install.

Treat it like a build script. Keep it current because it gets used, not because a policy says so. Yours is working if agents ask or assume fewer things that the file already answers.

Cognibl handles the other half. AGENTS.md gives an agent the project's standing conventions. A task in Cognibl carries the per-task half: the definition of done the agent will be judged against, and the evidence it has to attach. Cognibl enforces that half, where AGENTS.md is advisory.