The one-sentence version
AGENTS.md is a plain-text README, but written for an AI agent instead of a human. It states your setup commands, your code conventions, your project structure, and the guardrails the agent must never cross. Modern coding agents look for it automatically and read it before starting a task.
Why it exists
Dropped into a repo with no context, an agent guesses. It reinvents patterns you already have, reaches for libraries you don’t use, edits generated files, and ignores your test and commit conventions — so you end up re-explaining the same rules in every prompt. AGENTS.md moves those rules out of your prompts and into the repo, where every agent and teammate reads the same thing.
What goes in it
- Setup — the real install, dev and test commands for your stack.
- Code style — typing, formatting and the patterns you expect.
- Project structure — where things live, so new files land in the right place.
- Guardrails — the “never do this” rules: don’t edit build output, don’t commit secrets, don’t hand-edit migrations. This is the highest-value section.
Where it goes and who reads it
Place it as AGENTS.md at your repository root; agents read the nearest one in the tree, so monorepos can have a tailored file per package. It’s a shared convention across Cursor, Claude Code, OpenAI Codex, GitHub Copilot, Gemini, Windsurf, Zed and more. Tools that use their own filename can be pointed at it with a symlink, so you maintain one source of truth.
The fastest way to write one
A blank file helps no one — the value is the specific rules your stack needs. The free agentsmd generator detects your stack from a manifest and writes a tuned file in about thirty seconds, then exports it to every agent format.
Frequently asked
Is AGENTS.md an official standard?
It’s an emerging open convention adopted across major AI coding tools rather than a single company’s spec. The shared idea is one root-level markdown file of agent instructions.
Do I need AGENTS.md if I already have .cursorrules or CLAUDE.md?
You can consolidate them. AGENTS.md is the tool-neutral home; you can export or symlink the others to it so you maintain one file instead of several that drift apart.
What’s the most important section?
Guardrails — the explicit “don’t do X” rules. They’re what agents most reliably get wrong and what saves you the most cleanup.