What is AGENTS.md?

AI coding agents are stateless. Every new chat starts from zero, so you re-explain the same things: how to install, how to test, which style the team uses, which files never to touch. AGENTS.md moves those instructions into a file that agents read automatically — one file, every agent, every chat.

The convention is simple: place AGENTS.md at the root of your repository. Tools that follow the convention read it at the start of each session. Some tools also support nested files — an AGENTS.md in a subdirectory takes precedence for work inside that directory, which is handy for monorepos with per-package rules.

A short project overview (what it is, the stack, the working language), the exact commands to build, check and test, the code style the team actually enforces, project-specific rules that would otherwise live in someone’s head, and a short do/don’t list. Keep it under a couple of hundred lines — agents read it every session, and a bloated file wastes everyone’s context window.

Secrets and credentials (environment variables only), volatile information that changes weekly (put it in onboarding docs), aspirational rules the team does not actually follow — agents will happily enforce rules nobody practices, and the mismatch erodes trust in the whole file.

CLAUDE.md and .cursorrules are tool-specific files that predate the convention. AGENTS.md is the cross-tool file: most tools that read their own config will also read AGENTS.md, so a single AGENTS.md can be your source of truth while tool-specific files stay minimal or simply point at it.

Treat an edit to AGENTS.md like an edit to your build config: it changes how every agent works. When a rule turns out to be wrong or ignored, fix or delete it the same week. A stale rule is worse than no rule — agents follow it, humans stop trusting the file.