TL;DR: AGENTS.md is a plain Markdown file at the root of a repository that tells AI coding agents how to work in that project: how to build and test, which conventions to follow, what never to touch. Think of it as a README written for machines - the onboarding doc an agent reads at the start of every session.
How it works
When an AI coding agent starts a session in a repository, it looks for an instruction file and loads the contents into its context before doing anything else. The file then acts like a project-scoped system prompt: standing instructions that shape every action the agent takes, without the developer restating them in each request. There is no special syntax - it is ordinary Markdown, readable by humans and written for models.
What goes in it is whatever an agent would otherwise get wrong or waste time rediscovering. A typical file states the build and test commands ("run npm test, not npx jest directly"), the conventions ("TypeScript strict mode; no default exports"), the layout ("API routes live in src/routes, one file per resource"), and the hard rules ("never edit files under dist/ - only the build writes there"). The best entries are corrections from experience: every time an agent makes the same mistake twice, the fix becomes a line in the file. Monorepos nest them, with a root file for global rules and per-package files that add or override locally - the nearest file wins.
The convention has several names. AGENTS.md emerged in 2025 as a cross-tool standard now recognized by a wide range of coding agents; CLAUDE.md is the same idea for Claude Code; Cursor and Copilot have their own rules-file formats. The differences are mostly filename and lookup order - the underlying practice, a version-controlled instruction file the whole team shares, is identical, and many teams simply symlink one file to the other names.
Restraint is what separates a good file from a counterproductive one. Every line is loaded into every session, so a bloated file spends the agent's attention before work begins - a discipline that belongs to the wider practice of context management. Keep it to rules that change behavior; link out to deeper docs rather than pasting them in. And because agents follow written contracts far better than unwritten ones, a maintained instruction file quietly becomes the foundation that heavier practices like spec-driven development build on.
Where it sits in the AI stack
The instruction file sits between the repository and the agent's context, turning tribal knowledge into standing orders:
Key tools and implementations
-
AGENTS.md
The vendor-neutral convention, recognized across a broad set of coding agents and editors.
-
CLAUDE.md
Claude Code's instruction file, with support for global, project, and nested per-directory scopes.
-
Cursor rules
Cursor's rules files, which can attach instructions to specific paths and file patterns.
-
Copilot instructions
GitHub Copilot's repository instruction file, applied to chat and code review in the GitHub flow.
Related entries
- AI coding agent Software that plans and executes multi-step coding tasks - reading files, editing code, and running tests with minimal supervision.
- Context management Keeping an AI agent's working context relevant and small through compaction, memory files, and delegating work to subagents.
- System prompt Hidden instructions sent before user messages that set a model's role, rules, and tone for the conversation.
- Spec-driven development Writing a detailed specification first so AI coding agents implement, and get reviewed, against an agreed plan.