AGENTS.md

What is AGENTS.md?

AGENTS.md is a plain Markdown file, usually at the root of a repository, containing instructions for AI coding agents that work on that codebase. There is no schema and no required sections — an agent reads it as context before it starts making changes.

The usual one-line explanation is that README.md is for humans and AGENTS.md is for agents. A README explains what a project is and how to get started. An AGENTS.md records the operational detail a contributor would otherwise pick up by osmosis: the exact test command, the lint rules that will fail CI, the directories that are generated and should never be hand-edited.

Why it exists

Coding agents were largely inventing this file for themselves, under a different name per tool — CLAUDE.md, .cursorrules, .github/copilot-instructions.md, GEMINI.md and others. Maintainers who wanted to support more than one agent ended up keeping several near-identical files in sync.

AGENTS.md is an attempt to converge on one filename that any agent can look for. That is the whole of the idea: no spec to implement, no version negotiation, no transport. The value is entirely in tools agreeing on where to look.

What goes in an AGENTS.md file

Useful content is specific, verifiable and hard to infer from the code. Vague style advice tends to be ignored or misapplied; exact commands are not.

• Build, test and lint commands — the precise invocations, including any flags that matter.
• Project layout — what lives where, and which paths are generated or vendored.
• Conventions — naming, error handling, formatting rules an agent should match rather than replace.
• Boundaries — files, directories or migrations the agent must not touch without being asked.
• Verification steps — how to confirm a change actually works before declaring it done.

# AGENTS.md

## Commands
- Install: `pnpm install`
- Dev server: `pnpm dev` (port 3000)
- Test: `pnpm test` — must pass before any commit
- Lint + types: `pnpm lint && pnpm tsc --noEmit`

## Layout
- `src/` application code
- `src/generated/` — generated from the OpenAPI schema, never edit by hand
- `migrations/` — append-only; never modify an existing migration

## Conventions
- Match the style of surrounding code rather than reformatting it.
- Prefer named exports; default exports only for React pages.

## Before you finish
Run `pnpm test` and `pnpm lint`. Do not report a change as complete
if either fails.

Nested files in monorepos

Support varies by tool, but the common pattern is that an agent uses the closest AGENTS.md to the file it is editing. A repository root file can carry organisation-wide rules while each package adds its own commands, so a monorepo does not need one enormous file describing every workspace.

How it relates to MCP, A2A and Agent Protocol

This is the part worth being precise about, because AGENTS.md is often filed alongside the protocols as though it competed with them. It does not. The protocols define how software talks to software; AGENTS.md is static context an agent reads. Nothing implements it, and there is no wire format.

The two are complementary in practice. An agent might read AGENTS.md to learn that tests run with pnpm test, then use MCP to actually reach a terminal or file system. See MCP vs A2A vs Agent Protocol for how the protocol layers themselves divide up.

Where it stands

AGENTS.md emerged in 2025 and spread quickly, helped by being trivial to adopt — you add a file and nothing breaks if a tool ignores it. Support is real but uneven, and because there is no specification there is nothing to be compliant with. Two agents can read the same file and act on it differently.

Treat the current tool support as a moving target rather than a settled standard, and check your own agent's documentation for whether it reads the file, and whether it honours nested ones.