AGENTS.md is a Markdown file at the root of a code repository containing project instructions written for AI coding agents: how to install dependencies, how to run tests, what the code style is, which directories not to touch, and what format commit messages take.
It's often described as a README for agents. A README is written for people — what the project is and how to contribute. AGENTS.md holds the details an agent needs while working that would clutter a README or aren't relevant to human contributors.
Grab It in One Sentence First
AGENTS.md is the new-hire onboarding doc, except the reader is an AI.
Picture a skilled contractor who knows nothing about your project. Their engineering is fine, but they don't know you use pnpm rather than npm, that lint must pass before committing, that legacy/ is deprecated, or that every date field is UTC. Unless you write it down, they'll rediscover each of those the hard way. AGENTS.md puts your project's house rules in one predictable place so every agent reads them before starting.
Where It Came From, and Where It Stands
The file started life under different names in different tools: CLAUDE.md in one, .cursorrules in another, something else elsewhere. The result was several near-duplicate files sitting in the same repository.
In August 2025, an effort led by OpenAI with participation from Google, Cursor, and Factory formalized it as an open format, AGENTS.md. In December 2025 the specification was donated to the Linux Foundation's Agentic AI Foundation for neutral governance. It is now used by more than 60,000 open-source projects, and over twenty AI coding tools read it.
Note that not everything has converged: Claude Code still reads CLAUDE.md by default, and a common workaround is a symlink to AGENTS.md so both point at the same content.
What to Write, and How
There's no required structure — it's ordinary Markdown, headings are up to you, and the agent simply parses the text. In practice the useful content includes:
Environment and commands. Which package manager, how to install, how to start the dev server, how to run tests, what the build command is. This section has the highest payoff, because guessing wrong costs an agent a chain of failed attempts.
Project structure. What each directory is for, which outputs are generated and must not be hand-edited, which code is deprecated.
Code conventions. Language and framework versions, naming rules, when new dependencies are acceptable, comment and documentation expectations.
What not to do. Routinely underrated and often the most valuable section — files not to modify, things not to commit, dependencies not to auto-upgrade, and not claiming completion without running tests.
How to verify. What "done" means. Spell out the steps that can be checked automatically and the agent can judge for itself instead of handing that to you.
Scoping rules. In a monorepo you can put one in each package; the file closest to the edited file wins. An explicit instruction from the user in chat takes precedence over the file.
Versus Neighboring Concepts
Versus agent skills. AGENTS.md says what this project is and is read every time; skills say how to perform a specific capability and load on demand. One is project context, the other is reusable capability.
Versus spec-driven development. SDD's "constitution" — durable project-level rules — usually lives in AGENTS.md. The spec describes what to build this time; AGENTS.md describes what applies to everything you build.
Versus agent memory. It's the simplest and most widespread memory implementation: file-based memory. No vector store, no extra service, with Git providing versioning and review. The cost is that it doesn't filter itself, so a long file eats context window budget.
Versus a prompt. A prompt is one-shot and spoken; AGENTS.md is durable, committed, and shared. A convention one person corrects gets written down and every teammate's agent benefits.
Where People Get It Wrong
"More detail is better." The most common mistake. The file is read into context in full every time, so a few thousand lines spends a large chunk of the window on every task and dilutes the handful of rules that really matter. Keep it to a screen or two, separate "must follow" from "for reference," and leave the latter as links.
"If it's written, the agent will comply." It's context, not enforcement. Rules that genuinely must hold need machine backing too: lint, type checks, CI, pre-commit hooks. The file expresses intent; tooling provides the floor.
"Write it once and forget it." Projects change and so must the rules. A stale command or an obsolete convention is worse than none, because the agent will faithfully execute a wrong instruction. Treat it as a living document and review it alongside code.
"It's a vendor's proprietary format." AGENTS.md is an open specification under neutral foundation governance, not tied to a single vendor.
Is It Worth Writing?
If you use AI coding tools for anything beyond a one-off change, yes. It's among the highest-return context engineering moves available: half an hour of tidying saves dozens of later round trips of "no, we use pnpm."
Start with three things — how to run it, how to verify it, what not to touch. Those cover where agents most often go wrong. Then, as you work, add the sentence you find yourself repeating each time you correct it, and the file will grow into what your project actually needs.