AGENTS.md is a plain Markdown file at your repository root that tells AI coding agents how your project works — build steps, test commands, conventions, and boundaries. Where README.md is for humans, AGENTS.md is for the agents that do the work.
Why it exists
Open a repo in any agent and it doesn't know your build command, your conventions, or which directories are generated. Without that context it guesses — and wrong guesses are where the bad work comes from. AGENTS.md removes the need to guess.
A minimal example
# Acme API
Fastify, TypeScript, Drizzle ORM, PostgreSQL.
## Commands
Dev: pnpm dev
Test: pnpm test -- path/to/file.test.ts
Check: pnpm typecheck && pnpm lint
## Do not touch
- db/migrations/ is generated. Create a new migration instead.
How agents find it
One file at the root is the default. In a monorepo you can nest more files — agents read the nearest one in the directory tree, so a package's file overrides the root for work in that package.
Who reads it
Codex, Cursor, GitHub Copilot, Gemini CLI, Devin, Factory, Jules, Amp, VS Code, Windsurf — and 60,000+ projects. It's now stewarded by the Linux Foundation. The one holdout is Claude Code, which a symlink handles (separate post).
Free cheat sheet: the format, an annotated example, and the one-line test — AGENTS.md Cheat Sheet.
Go deeper: the full reference — cross-tool setup, the monorepo hierarchy, and a 30-day plan — AGENTS.md: The Complete Guide to the Cross-Tool Agent Standard.
How many instruction files does your repo have right now — one, or a small museum of them? 👇
Top comments (0)