AGENTS.md: The One Rule File Every AI Coder Reads

The Verdict

AGENTS.md has become the single most practical way to make an AI coding agent follow your project’s rules. Write one Markdown file at the repo root, list your build commands, test commands, code conventions, and hard guardrails, and every major agent picks it up on its own: Codex, Cursor, Copilot, Claude Code, Gemini CLI, and more. You stop repeating the same corrections in chat. The agent stops guessing. For teams that run more than one AI tool, this one file replaces a stack of tool-specific config files.

If you take one action from this article, make it this: create AGENTS.md in your next repo, fill it with five concrete sections (project map, build, test, conventions, do-not-touch list), and keep it under 150 lines. The rest of this guide shows you what goes in each section and how the file relates to CLAUDE.md, .cursorrules, and Copilot instructions.

Why Your Agent Keeps Making the Same Mistakes

You give an AI agent a task. It reads a few files, writes new code, runs something, and reports success. Then you check the diff. It used the old test command from the README, which no longer works. It added a dependency your team banned six months ago. It reformatted three files nobody asked it to touch. You correct it in chat, it apologizes, and the next session repeats the same errors.

Also Read:

Do You Still Need to Learn to Code?

The agent failed at the onboarding step every human contributor gets: nobody told it how your project works. Humans read the README, the contributing guide, and the CI config. They absorb the unwritten rules by watching code review. An agent session starts cold. Without project context, it falls back to generic defaults, and generic defaults clash with your specific setup.

Context files fix this at the source. A rule file hands the agent the same briefing a senior teammate would give a new hire: here is the stack, here is how you build it, here is how you test it, here are the lines you never cross. The difference shows up in the first diff. Commands run green on the first try. Conventions match the existing code. Review cycles shrink because the reviewer stops flagging the same avoidable mistakes.

This pattern matters more as agents grow more capable. The better the model, the more damage confident guessing causes. A sharp agent that misunderstands your project ships wrong code faster than a weak one. Context is the brake pedal.

Also Read:

Who Owns AI-Generated Code? What the Law Says

Five Formats, One Idea

Each major tool invented its own name for the same concept before the ecosystem converged. You will still meet all five in real codebases, so it helps to know what each one is and where it lives.

The shape is the same in every case: plain Markdown, no required schema, headings you choose. The point was never the format. The point is the location. Because dozens of tools agree to look for AGENTS.md in the same place, one file configures every agent that touches the repository instead of each vendor keeping its own.

AGENTS.md started with OpenAI’s Codex team and grew through collaboration across the ecosystem. In December 2025 the project moved under the Agentic AI Foundation, a Linux Foundation body, alongside the Model Context Protocol and the goose agent. Institutional stewardship means no single vendor redefines the format on its own next quarter. The self-reported count of adopting repositories sits above 60,000, which lines up with how fast the reader list keeps growing.

Also Read:

Vibe Coding vs Traditional Coding: When Each Wins

Tool-specific files still have their uses. CLAUDE.md supports features like Claude Skills and subagent scoping that AGENTS.md does not describe. Cursor’s path-scoped rules target single directories. But for the shared core (build, test, conventions, guardrails), maintain it once in AGENTS.md. Let the vendor files carry only the extras that one specific tool needs. If you are starting a new project today, write AGENTS.md first and add tool-specific files only when you hit a real limitation.

What Belongs in the File

Good rule files read like a runbook, not an essay. The agent needs instructions it can act on, not background it can admire. Five sections cover almost every project:

1. Project map. Two or three sentences on what the project is and which directories matter. Name the entry points: where the app boots, where tests live, where generated code sits. This keeps the agent from exploring blind.

2. Build and run commands. The exact commands, copy-paste ready. npm run dev, cargo build, docker compose up. GitHub’s own analysis of more than 2,500 repositories carrying AGENTS.md found the same lesson again and again: specific runnable commands beat vague prose. An agent can execute npm test. It cannot act on “make sure things work.”

3. Test and verification. How the agent proves its change is safe before it reports done. Include the full test command, the lint command, and any typecheck step. If a subset runs faster, list it for quick iteration and the full suite for final checks.

4. Code conventions. The three to five rules your reviewers enforce most. Naming style, import order, error handling pattern, the formatter and its config. Point at the config file instead of restating it.

5. Guardrails. The hard no list. Files the agent must never touch (migrations, lockfiles, generated clients). Commands it must never run (deploy, database reset, anything destructive). Secrets it must never print. This section earns its keep the first time it stops a bad command.

Leave out everything the agent does not need to act. Product roadmaps, architecture essays, and marketing copy belong in the README. Every non-essential line dilutes the signal, and long files get skimmed. The reference implementation in OpenAI’s own codex repo runs over 300 lines and works because the reader is tuned for it. Your file should aim for 60 to 150 lines. Short, current, and specific beats comprehensive.

A Template You Can Copy

Start from this skeleton and fill in the blanks. It covers the five sections above in under 60 lines:

Project: <name>
One-line description of what this project does.

Layout:
> src/ is application code, entry point at src/index.ts
> tests/ holds unit tests mirroring the src/ structure
> scripts/ holds helper scripts, never run in production

Build and run:
> Install with: npm ci
> Dev server: npm run dev
> Build: npm run build

Test and verify:
> Full suite: npm test
> Quick check: npm run test:unit
> Lint and format: npm run lint then npm run format
> Run lint and the quick check before reporting a task done

Conventions:
> TypeScript strict mode, no `any` without a comment
> Error handling with typed result objects, never bare throws
> Follow the Prettier config in .prettierrc

Guardrails:
> Never edit prisma/migrations/ or package-lock.json by hand
> Never run npm run deploy or any database reset command
> Never print tokens, keys, or .env contents in output

Notice what the template does not contain: no philosophy, no history, no restated documentation. Each line either names a path, gives a command, or sets a boundary. When a convention changes, you update one line and every agent session that follows picks up the new rule. Teams that keep this file current report the same pattern: the agent’s first attempt lands closer to mergeable, and code review shifts from catching setup errors to judging design choices. For more on writing rules that agents follow, see How to Write Rules Files for AI Coding Agents.

Monorepos: One File Per Package

A single root file strains when a repository holds three stacks. The format has an answer for this: agents walk the directory tree and read the nearest AGENTS.md to the code being edited. Put a short root file with organization-wide rules and shared commands, then add per-package files that describe what differs.

A typical setup looks like this. The root file sets the non-negotiables: the monorepo tool, the shared lint config, the global guardrails. Each package file then adds its own build command, its own test filter, and its own conventions. The closest file wins on conflicts, so a package can override a root rule without editing shared text. This keeps each file short and each package’s instructions honest about that package’s reality.

The OpenAI codex repository itself demonstrates the pattern at scale, carrying dozens of AGENTS.md files across its subprojects. You do not need dozens. Start with the root file, and split off a package file the first time a package’s commands differ from the root defaults. Two or three files beat one bloated file every time.

Mistakes That Defeat the File

Most rule files fail in one of three ways. All three are easy to spot and easy to fix.

Too long. A 400-line file full of aspirational guidance reads like a wiki page, and agents treat it like one: they skim. Cut anything that does not change what the agent does. If a section has not influenced a diff in a month, delete it. Length is a tax on every session.

Too vague. “Write clean code” helps nobody. “Run `npm run lint` and fix every error before committing” helps a lot. Vague lines survive because they feel safe to write; they cost you every time the agent nods along and then does whatever it wants. Replace each vague line with a command, a path, or a concrete example.

Stale. A file that says npm test when the team moved to pnpm test:e2e is worse than no file, because the agent follows it with confidence. Treat AGENTS.md like code: review it in the same PRs that change the commands it documents. The cheapest habit is a one-line check during code review: does this PR change a command, path, or convention the file describes?

One more trap deserves a mention: secrets. Never paste tokens, keys, or credentials into a rule file. These files get committed, shared, and read by tools. Point the agent at the secret manager or the env file name instead of the value.

A practical review pass exists for teams that want a checklist of what working rule files contain: AI Coding Agent Rules Files That Actually Work breaks down the patterns that survive contact with real agents.

Where the Standard Goes Next

The interesting part of the AGENTS.md story is not the file itself. It is the convergence. For a year, every vendor shipped its own format and teams paid the tax of maintaining several. Now the readers list grows every quarter while the format stays plain Markdown. The Agentic AI Foundation’s stewardship gives the convergence an institutional home, with AWS, Anthropic, Google, Microsoft, and OpenAI among the members.

What comes next is depth, not more formats. Expect tooling that lints your AGENTS.md against your actual repo (does the test command exist, do the paths match), templates per stack, and agents that update the file when they learn a new project rule mid-session. The file stays dumb and readable. The tooling around it gets smarter.

For teams choosing tools today, the practical advice stays simple. Write the standard file first. Add CLAUDE.md extras only if you use Claude Code’s agent features, keep Cursor’s path rules only where a directory needs different rules, and let Copilot read the shared file instead of maintaining a separate instructions doc. One source of truth for project context, with vendor files as thin overlays. If you are comparing the agents themselves, this benchmark of Claude Code vs Cursor vs GitHub Copilot and this Windsurf vs Cursor comparison cover how the tools differ in practice.

For the fullest picture of the format’s history and adoption, this review of the AGENTS.md standard and this practical guide on DEV walk through the details, while this 90-second setup recipe and this FAQ on the format answer the questions teams ask first.

Final Take: Start Today, Thank Yourself Next Week

Pick your most active repository. Spend fifteen minutes writing down the commands you already chant at new contributors, the conventions your reviewers enforce, and the three things an agent must never do. Commit the file. Then watch your next agent session: it will run the right test command, follow your style, and stay inside the guardrails without being told twice.

The file costs almost nothing to maintain and pays back in every session. Your README speaks to humans. Your AGENTS.md speaks to the agents doing an increasing share of the typing. Give them the briefing, and hold them to it in review. The teams that do this well stop debugging their tooling and get back to judging the work, which is where human attention belongs.