AGENTS.md Explained: How to Write One File Every Coding Agent Can Read

Every AI coding agent needs the same handful of facts before it can be useful in your repository: how to install dependencies, how to run tests, which directories are off-limits, and which conventions the team actually enforces. For a while, every agent invented its own file to hold that context - CLAUDE.md for Claude Code, .cursorrules for Cursor, .windsurfrules for Windsurf, .github/copilot-instructions.md for Copilot. Teams working across more than one agent ended up copy-pasting the same instructions into three or four files, and watching them drift apart within a week.

AGENTS.md is the fix: one plain Markdown file, at the repository root, that any agent can read.

What is AGENTS.md?#

AGENTS.md is an open, vendor-neutral specification for a Markdown file that lives at the root of a repository (or a subdirectory, for monorepos) and gives coding agents the operational context a human contributor would get from onboarding: setup commands, test commands, code style, project structure, and boundaries the agent should not cross.

It was published by OpenAI in August 2025 as a way to standardize what had become a fragmented mess of per-tool rule files, and quickly picked up support from other agent builders. By 2026 the spec had moved to neutral governance under the Linux Foundation's Agentic AI Foundation, with Google, Cursor, Factory, and Amp among the parties involved in stewarding it - a deliberate move to keep it from being any single vendor's format.

The file itself is unopinionated by design. There is no required schema, no frontmatter, no XML. It is Markdown with a small number of conventional sections, which is exactly why so many tools were willing to adopt it: reading it is just reading a Markdown file.

flowchart LR
  subgraph Repo["Your repository root"]
    A["AGENTS.md"]
  end
  A --> Codex["OpenAI Codex"]
  A --> Cursor["Cursor"]
  A --> Copilot["GitHub Copilot"]
  A --> Jules["Google Jules"]
  A --> Aider["Aider / Zed / Devin"]
  A -.import.-> Claude["Claude Code (via CLAUDE.md import)"]

Which agents actually read it#

Support has grown fast since launch. As of 2026, AGENTS.md is read natively by OpenAI Codex, Cursor, GitHub Copilot, Google Jules, Factory, Aider, Zed, VS Code's agent mode, and Devin, among others - by some counts, more than thirty tools and upward of 60,000 open-source repositories have adopted it.

Claude Code is the notable exception worth knowing about: it still looks for CLAUDE.md specifically rather than reading AGENTS.md directly. The workaround is one line - see Claude Code compatibility below.

AGENTS.md vs CLAUDE.md vs .cursorrules vs .windsurfrules#

If you already maintain one of the tool-specific files, here is how they map:

The practical upshot: AGENTS.md doesn't replace every tool-specific file overnight, but it collapses the content into one place. Instead of writing your build commands four times, you write them once in AGENTS.md and point the tool-specific files at it, or drop them entirely where the agent already reads AGENTS.md natively.

Claude Code compatibility#

Claude Code reads CLAUDE.md, not AGENTS.md, so if you want a single source of truth that also works for Claude Code, make CLAUDE.md a one-line import:

@AGENTS.md

That's the entire file. Claude Code follows the import and treats AGENTS.md as its instructions, so you keep one file to maintain instead of two. We cover Claude Code's instruction-file conventions in more depth in How to Write the Perfect CLAUDE.md File for Claude Code - most of that advice on structure and specificity applies directly to AGENTS.md too, since Claude Code ends up reading the same content either way.

What to put in AGENTS.md#

There's no enforced schema, but the repositories that get consistent results from agents tend to converge on the same sections:

1. Project overview - one or two sentences on what the repo is and how it's structured (monorepo, single app, etc.).
2. Setup commands - the exact commands to install dependencies and start the project, as runnable code blocks, not prose.
3. Test commands - how to run the full suite and, if relevant, a single test file or pattern.
4. Code style - formatter, linter, naming conventions, import ordering - whatever is enforced in CI.
5. Repository structure - where things live, especially anything non-obvious (a monorepo with three build systems, a generated directory, a legacy folder nobody touches).
6. PR / commit conventions - message format, whether commits should be squashed, required checks.
7. Boundaries - what the agent should never do: never commit directly, never touch /migrations without a review, never install a new dependency without asking.
8. Security notes - secrets handling, anything that must never be logged or committed.

A minimal but real example:

# AGENTS.md

## Setup
npm install

## Test
npm test              # full suite
npm test -- <pattern> # single file

## Style
- Format with Prettier before committing (`npm run format`)
- No default exports
- Co-locate tests next to source as `*.test.ts`

## Structure
- `apps/web` - Next.js app
- `packages/*` - shared libraries, published internally only
- `apps/web/.next` - generated, never edit

## PRs
- Conventional commit messages
- Never commit directly to `main`

The pattern that matters most: write for a parser, not a person. One rule per bullet, runnable commands in fenced blocks, no paragraphs an agent has to infer intent from. Agents follow instructions they can act on literally far more reliably than instructions phrased as context or philosophy.

Monorepos: more than one AGENTS.md#

For a monorepo, you're not limited to a single root file. Most agents that support AGENTS.md will also read one nested in a subdirectory and prefer the more specific file for work happening in that directory - the same override pattern you'd expect from .gitignore or .eslintrc. A root AGENTS.md can hold conventions that apply everywhere (commit format, security notes), while apps/web/AGENTS.md and apps/worker/AGENTS.md hold the commands and structure specific to each app. This mirrors how this very site is set up: a root AGENTS.md for shared rules, with a more specific file inside apps/web for that app's Next.js conventions.

Common mistakes#

• Writing it once and never updating it. An AGENTS.md that references a test command that was renamed six months ago is worse than no file - the agent runs the wrong thing confidently instead of asking.
• Burying the important rule in paragraph four. Agents weight instructions unevenly across a long file the same way people skim past the middle of a page. Boundaries and hard constraints belong near the top.
• Treating it as documentation for humans. AGENTS.md can double as onboarding material, but if you're writing prose explanations instead of imperative instructions, you're optimizing for the wrong reader.
• Letting it drift from the files it's supposed to unify. If you keep .cursorrules around for legacy reasons, make sure it doesn't contradict AGENTS.md - conflicting instructions are worse than a missing file.

Watch: AGENTS.md in three minutes#

Write yours now#

You don't need to start from a blank file. The free AGENTS.md generator walks through setup commands, code style, repo structure, and PR conventions with a live Markdown preview, and exports a file ready to drop into your repo root - no signup required. If you're standardizing across tools, the CLAUDE.md generator, .cursorrules generator, and .windsurfrules generator share the same underlying sections, so you can generate the tool-specific files from the same source of truth.

Keeping it accurate after the first commit#

Writing AGENTS.md once is the easy part. The hard part is the same problem documentation has always had: the test command changes, a new package gets added, a directory gets renamed, and the file quietly stops being true. An agent that trusts a stale AGENTS.md doesn't fail loudly - it runs the wrong command, edits the wrong directory, or misses a convention the team added last sprint.

Moxie Docs connects to your GitHub repository and keeps generated documentation - including instruction files like this one - aligned with what actually changed in the codebase, surfaced as reviewable pull requests rather than silent overwrites. If your team is already writing AGENTS.md by hand, that's a good sign your docs matter to you; the next step is making sure they don't rot the way most docs/ folders do. See how it fits your workflow on the free plan - one repository, no card required.