Skip to content
Open the dashboard
Documentation

What is AGENTS.md, and which coding agents read it?

6 min read

AGENTS.md is a plain Markdown file, usually at the root of a repository, that tells AI coding agents how to work in that codebase: how to build and test, what conventions to follow, what never to do. It is read by OpenAI Codex, Cursor, GitHub Copilot’s coding agent and code review, and Claude Code, and it has no required structure, which is both its strength and the reason it drifts.

Each tool’s own documentation, as of October 2026:

Agent Reads AGENTS.md? Its own file What happens when both exist
OpenAI Codex Yes, it introduced the format none n/a
Cursor Yes, in the root and in subdirectories .cursor/rules/*.mdc Both apply; .mdc rules can be scoped to file globs, AGENTS.md cannot
GitHub Copilot (coding agent, code review) Yes, the nearest file in the directory tree .github/copilot-instructions.md, .github/instructions/*.instructions.md Both apply
Claude Code (2.1.277 and later) Yes, when no CLAUDE.md exists in the working directory or above it CLAUDE.md CLAUDE.md wins, unless it imports AGENTS.md with a line @AGENTS.md, in which case both load
Gemini CLI, Windsurf, others Varies by tool and version GEMINI.md, .windsurfrules Check the tool’s documentation

Two consequences follow. A team on Codex and Cursor can keep one file. A team that also uses Claude Code needs a CLAUDE.md that imports AGENTS.md, or Claude will read a different set of instructions from everyone else; see CLAUDE.md, Cursor rules and Copilot instructions: one source.

The file is loaded into the agent’s context on every task, so every line costs attention. The things that earn their place:

  • How to build, test and run: the commands, in fenced blocks, so the agent runs them rather than guessing.
  • Conventions the agent cannot infer from the code: the HTTP client to use, where handlers live, which layer may import which.
  • Rules with a reason: “never commit .env files; commit .env.example with placeholders” is followed more reliably than “no secrets”.
  • What to do before finishing: run the tests, run the check, keep changes small.

What does not belong: architecture essays, history, anything the agent can read from the code itself, and anything you are not willing to keep current. Claude Code’s documentation recommends staying under about 200 lines; Codex caps the file at 32 KiB by default.

AGENTS.md is hand-written, it is one of several files saying the same thing, and nothing checks it. Three months in, the Cursor rules say one thing, AGENTS.md says another, the wiki says a third, and the agents follow whichever they read. The fix is not a better template. It is one source that the files are generated from, and a check that runs on every change so a rule the agent ignored is caught before merge.

That is what Groundrule does with the file: npx @groundrule/cli sync writes a managed block into AGENTS.md from the standards in .groundrule/, and leaves everything you wrote by hand in place. The same standards produce CLAUDE.md, the Cursor rules and the Copilot instructions, so the four files cannot disagree. Agent instruction files shows exactly what is written and where.