What is AGENTS.md, and what belongs 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": 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 just put it in the README?

Because the two files have different readers, and writing for both makes a worse document for each.

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

That clutter argument is the real one. The instructions an agent needs are tedious in a way a human contributor does not require: the exact test command including the flags, the directories not to touch, the reason a module is structured oddly. Put all of it in the README and you have made the front door of your project worse for the people you are trying to attract. Leave it out and every agent rediscovers it, badly, once per session.

What actually belongs in it?

The convention has no required schema, which is a feature and also the reason most of them are mediocre. What earns its place is anything an agent would otherwise guess:

• Build and test commands, exactly. Not "run the tests" but the command, with the flags, and how to run a single one. This is the single highest-value section and the one most often written too vaguely 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 is the section that prevents an agent 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.

The test for any line: would an agent get this wrong without being told, and would getting it wrong cost me a round trip? If not, it is documentation, and it belongs elsewhere.

Where do teams get it wrong?

Four ways, in roughly descending frequency.

Writing it once and never again. The file describes a codebase that has moved. A stale build command is worse than no build command, because the agent follows it confidently into a failure that looks like its own fault.

Filling it with adjectives. "Write clean, maintainable code" instructs nothing. Every line should be checkable, or it is decoration.

Making it enormous. Long context degrades. A file that tries to be the complete architectural history buries the four commands that actually matter.

Assuming it is a control. This is the important one, and it is why the file's popularity is slightly dangerous. AGENTS.md is advisory. It is instructions a cooperative agent reads, and nothing enforces a single line of it. A "do not touch the payments module" written there is a request, not a permission boundary, and the difference only becomes visible on the day it matters.

How does it relate to context engineering?

It is the cheapest, most durable slice 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 addresses the most stable part of that context, the part that is true of the repository regardless of which task is being worked on.

What it cannot carry is the part that changes per task: what this piece of work means, what would make it acceptable, and what evidence would show it was done. That is not a repository-level fact, so it does not belong in a repository-level file, and trying to put it there is how AGENTS.md files become enormous and stale at the same time.

Two different jobs, then. AGENTS.md says how work is done here. The task says what this 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, it is read by every major agent without configuration, and it is plain Markdown with nothing to install.

Treat it the way you treat a build script: kept current because it is used, not because a policy says so. The signal that yours is working is a fall in the number of times an agent asks or assumes something the file already answers.

Cognibl sits on the other side of that line. AGENTS.md gives an agent the project's standing conventions; a task in Cognibl carries the per-task half, the definition of done it will be judged against and the evidence it has to attach, which is enforced rather than advisory.