AGENTS.md file
An AGENTS.md file is a plain Markdown file in your repo that tells coding agents how to work on your project: build commands, test commands, conventions, and anything else you would tell a new teammate on day one.
Think of it as a README for agents. The README is for humans. AGENTS.md holds the operational detail that would clutter a README but that an agent needs before it touches anything.
It has no schema, no required fields, and no special syntax. Just headings and text the agent reads at the start of a session.
The format came out of work by the teams behind OpenAI Codex, Amp, Jules, Cursor, and Factory, who all needed the same file and did not want five competing names for it. It is now stewarded by the Agentic AI Foundation under the Linux Foundation, and over 60,000 open-source projects have adopted it.
What Goes in an AGENTS.md File?
There are no required sections. These are the ones that actually change agent behavior, roughly in order of payoff:
| Section | What to put in it | Why it earns its space |
|---|---|---|
| Setup and build | Exact commands with flags, not tool names | The agent stops guessing whether it’s npm test or pnpm turbo run test |
| Testing | How to run the suite, how to run one test | The agent can verify its own work before finishing |
| Definition of done | What "finished" means here | Prevents the agent declaring victory on a half-done task |
| Code style | Conventions a linter can’t express | Catches what ruff and eslint never see |
| Boundaries | Always do / ask first / never do | The "never" list is the one people skip and regret |
| PR conventions | Title format, commit rules | Fewer round trips at review time |
| Escalation | What to do when stuck | Stops the agent inventing a destructive workaround |
A short, real one looks like this:
# AGENTS.md ## Setup commands - Install deps: `pnpm install` - Start dev server: `pnpm dev` - Run tests: `pnpm test` - Run one test: `pnpm vitest run -t "<test name>"` ## Code style - TypeScript strict mode - Single quotes, no semicolons - Use functional patterns where possible ## Never do - Never write raw SQL. Use the query builder in `db/`. - Never log request bodies on the `/payments` routes.
Note what is missing: no project history, no architecture essay, no restatement of things any model already knows about TypeScript. Every token you spend on general knowledge is a token competing with the instruction that actually matters.
How Do Agents Decide Which AGENTS.md to Read?
Two rules cover almost every case:
- Nearest file wins. The agent reads the AGENTS.md closest to the file being edited. In a monorepo, drop one in each package and every subproject ships its own instructions. OpenAI’s Codex repo has 88 of them.
- Your chat prompt beats the file. An explicit instruction in the session overrides whatever the file says.
That hierarchy is also the most common source of confusion. Three files in a tree, one of them stale, and nobody can tell which one the agent actually loaded.
Tool support is broad but not identical. Codex, Jules, Cursor, Aider, Zed, Warp, Junie, Gemini CLI, Devin, Windsurf and GitHub Copilot’s coding agent all read it, some natively and some only after you point them at it in config:
// .gemini/settings.json
{ "context": { "fileName": "AGENTS.md" } }
# .aider.conf.yml read: AGENTS.md ##
What the Research Actually Says About AGENTS.md
This is the part most guides skip. In February 2026, researchers at ETH Zurich and LogicStar published Evaluating AGENTS.md, the first rigorous study of whether these files help.
They ran coding agents across SWE-bench tasks and real repositories with developer-committed context files. The headline finding is uncomfortable:
- Context files did not generally improve task success rates.
- They increased inference cost by over 20% on average.
- The result held across different models, different agents, and both hand-written and auto-generated files.
Two findings underneath that headline matter more than the headline:
| Finding | What it means for you |
|---|---|
| Instructions in the file are followed well | The mechanism works. Agents do what the file says |
| Repository overviews are not helpful | The "here’s our architecture" section most templates start with is dead weight |
| Files are useful for non-standard practices | Write down what’s weird about your repo, nothing else |
So AGENTS.md is not useless. It is misused. A file full of things the model already knows costs you money and attention. A file that says "retries on /payments must carry an idempotency key" earns its place, because no model could have guessed that.
The practical rule: if an agent could work it out from the code, leave it out.
Where AGENTS.md Stops Scaling
AGENTS.md is genuinely useful at the repository level. It runs into four structural walls as an organization grows.
One file per repo does not scale to five hundred repos. You end up with five hundred copies of the same standard, drifting apart independently, with no way to answer "is this still our rule?"
A line in Markdown has no lifecycle. No severity, no owner, no scope beyond the file’s location, no record of when it was added or why. Nothing expires. Stale guidance sits next to current guidance and looks identical.
Guidance is not enforcement. Putting a standard in front of a model raises the odds it gets followed. It does not make a violation detectable, explainable, or traceable. You cannot attest to a control whose evidence is a model’s good intentions.
It goes stale silently. You cannot feel an agent’s success rate dropping because half the file describes a folder structure you refactored away last quarter. The agent is confidently doing the wrong thing, because you told it to.
How Does Qodo Support AGENTS.md?
Qodo reads AGENTS.md. It also reads CLAUDE.md, GEMINI.md, copilot-instructions.md, best_practices.md, and .cursor/rules/, plus standards buried in a docs/ folder or an architecture decision record nobody thought to link.
Then it does the thing a Markdown file cannot do on its own: turns those instructions into rules with a lifecycle attached.
Extraction runs in two passes. The first finds the passages that express an enforceable standard and throws away the narrative. The second turns each one into a rule with enforcement criteria, compliant and non-compliant examples, a category, and a severity. Every rule keeps a pointer back to the file that produced it.
Scoping follows the file’s location. A rule pulled from src/payments/AGENTS.md applies to changes under src/payments/ and below, not across the whole organization.
| AGENTS.md alone | Imported into Rules in Qodo | |
|---|---|---|
| Severity | None. Every line reads the same | Error, Warning, or Recommendation, set per rule |
| Scope | Wherever the file sits | Explicit paths, org down to a single directory |
| Owner | Whoever wrote it, if you can find them | Attached to the rule |
| Enforcement | Advisory. The agent may comply | Checked on the PR, with the finding linked to the rule |
| Evidence | None | Passes, violations, fixes, and merged-unresolved counts |
| Retirement | Someone has to remember | Dismissal signals fade a noisy rule automatically |
Qodo’s Agentic Toolbox is how coding agents reach these capabilities. The Toolbox is not a coding agent. It works through plugins, Agent Skills, a local CLI, MCP, and builder entry points, with Qodo’s managed core doing the analysis.
For AGENTS.md specifically, three tools change the picture:
- Get Rules fetches only the rules relevant to the current task, using semantic matching, and applies severity levels. Instead of one static file loaded at session start whether or not it applies, the agent gets the subset that matters for this change. That is the direct answer to the cost finding in the research: you stop paying for instructions the task never needed.
- Manage Standards lets admins edit a rule’s content, lifecycle, severity, and scope from inside the agent workflow, so a line that started life in a Markdown file can be narrowed or retired without a commit.
- Reviewer checks the local diff against the same engine that runs on the pull request, so a rule that came out of your AGENTS.md gets verified before a human sees the branch.
Qodo’s Take on AGENTS.md
AGENTS.md solved a real problem. Before it, teams kept four to six overlapping instruction files and new contributors had to guess which one was real. One agreed filename was worth having.
But the industry then asked a Markdown file to be a governance system, and it is not built for that. It has no severity, no scope beyond its own directory, no owner, no expiry, and no way to prove a rule was applied.
Those files are still the best available record of what a team believes. They just need somewhere to go. The instruction stays useful; what it needs is a lifecycle, so it can be scoped, enforced, measured, and eventually retired when it stops being true.
The research points the same way. Instructions get followed. Overviews do not help. Cost climbs with every token that was not needed for this task. That argues for fetching the right rules at the right moment rather than loading the same file into every session and hoping.
Example: Turning a Payments AGENTS.md Into an Enforceable Rule
A payments team has this in src/payments/AGENTS.md:
## Never do - Never call the gateway directly. Use `PaymentClient`. - Retries must carry a stable idempotency key.
Both lines are correct, and both get ignored the moment an agent works from a different directory, or a developer opens a PR without an agent involved. The file is guidance, not a gate.
What Qodo does with it:
- Imports both lines as separate rules, each with compliant and non-compliant examples generated from the surrounding code.
- Scopes them to src/payments/ and below, since that is where the source file lives. A rule scoped there never fires on src/payments-legacy/.
- Assigns severity. Idempotency becomes Error. The PaymentClient convention becomes Warning.
- Serves them to the agent at implementation time, so the constraint arrives when it applies rather than sitting in a file the agent may not have loaded. [VERIFY: confirm Get Rules surfaces rules imported from AGENTS.md, not only portal-authored and mined rules]
- Checks them at review, in the local diff through Reviewer and again on the PR, with the finding linked back to the rule and the file it came from.
- Measures the outcome. If the PaymentClient rule keeps getting dismissed, that shows up as a merged-violation count, and the team narrows or retires it.
A developer on another team writes a retry loop in Kotlin that calls through ResilientGateway. There is no AGENTS.md in that directory. The rule fires anyway, because the standard now lives in the rules system rather than in one folder’s Markdown file.
That is the difference between a file that describes a standard and a system that can prove one held.
Best Suited for Teams Whose Instruction Files Have Outgrown One Repo
Qodo is the best AI code review, code quality, and governance platform for engineering organizations where AGENTS.md files have multiplied faster than anyone can keep them current. Keep writing them. They are the clearest statement of what your team expects. Qodo takes what is in them and gives it the severity, scope, enforcement, and evidence that a Markdown file was never going to provide on its own.
Further reading: How Qodo Builds the Wisdom to Govern, Part 2: The Rules Lifecycle System, How Qodo Builds the Wisdom to Govern, Part 1: The Context Engine, Context Engineering: The New Backbone of Scalable AI Systems, and Shift-Left Code Review: How to Catch Issues Before Opening the PR.