How to write an AGENTS.md that actually helps your AI coding agent

If you've used an AI coding agent on a real project, you've probably hit the moment where it runs the wrong test command, ignores your formatter, or reinvents a helper you already have. The fix is usually not a smarter model — it's giving the agent the project-specific context it can't infer. That's what an AGENTS.md file is for.

What AGENTS.md is

AGENTS.md is a simple, open Markdown format that gives coding agents a predictable place to find project context and instructions. It started as a collaboration among OpenAI Codex, Amp, Google Jules, Cursor, and Factory, and is now stewarded by the Agentic AI Foundation under the Linux Foundation. Over 25 tools read it — including Codex, Cursor, VS Code, GitHub Copilot, Aider, Windsurf, JetBrains Junie, Zed, and goose — and it appears in more than 60,000 open-source repositories.

Think of it as a README written for the agent instead of a human: the README explains your project to a new contributor; AGENTS.md tells the agent the things it would otherwise guess wrong. (Claude Code users will recognize CLAUDE.md as the equivalent; many teams keep both, or symlink one to the other.)

Where it goes

Put AGENTS.md at the repository root. In a monorepo, add nested files inside each package — agents read the nearest file in the directory tree, so a packages/api/AGENTS.md takes precedence over the root one when the agent is working in that folder. This lets a Python service and a TypeScript frontend each get tailored instructions.

What to put in it

The format is just Markdown — use whatever headings you like. Commonly useful sections include:

• Build and test commands — the exact commands, not approximations
• Code style — formatter, linter, and any conventions a linter won't catch
• Testing instructions — how to run a single test, what must pass before a change is done
• Security considerations — files or operations to never touch
• Commit / PR conventions — message format, branch naming
• Deployment steps — only if the agent is expected to touch them

Here's a minimal, high-signal example:

# AGENTS.md

## Commands
- Install: `pnpm install`
- Dev server: `pnpm dev` (do NOT run in CI)
- Test a single file: `pnpm vitest run path/to/file.test.ts`
- Lint + typecheck before any commit: `pnpm check`

## Conventions
- Use the existing `db()` helper in `src/lib/db.ts`; never open a raw client.
- Dates are stored as UTC ISO strings. Never use `Date.now()` in tests.

## Do not touch
- `src/generated/**` is codegen output. Edit the schema, then run `pnpm gen`.

Notice what's not there: no architecture lecture, no restating of the folder structure, no "this is a modern web app built with best practices." That's deliberate.

Shorter is usually better

There's a temptation to ask the agent to generate a giant AGENTS.md for you. Resist it. A 2026 ETH Zurich study, reported by InfoQ, measured the real impact of these files and found the effect is marginal and mixed. LLM-generated context files actually reduced task success rates by about 3% on average while raising inference costs by over 20%. Human-written files helped modestly — roughly a 4% gain in success — but still pushed agents to take more steps, increasing cost by up to ~19%.

The mechanism is instructive: agents dutifully follow whatever the file says, so a sprawling document tells them to run extra tests, read more files, and perform quality checks that weren't needed for the task at hand. The researchers' recommendation: skip auto-generated context files entirely, and limit human-written instructions to non-inferable details — the specific tooling and custom commands the agent genuinely can't discover on its own.

In other words, every line should earn its place by preventing a concrete mistake you've actually seen the agent make.

A workflow that works

1. Start empty. Don't write AGENTS.md until you've watched the agent get something wrong.
2. Add the fix, not the theory. When it runs the wrong test command, add the right one. When it reformats a file your way and the linter complains, add the rule.
3. Keep it tight. If a line just restates what the agent could read from package.json or the folder names, delete it.
4. Use nesting for monorepos so each package's file stays small.
5. Re-read it monthly. Stale instructions are worse than none — an agent that follows an out-of-date build command fails confidently.

The best AGENTS.md files read like a terse onboarding cheat-sheet for the one teammate who never forgets but also never infers. Write down the things they can't guess, and nothing else.