AGENTS.md is a plain-markdown file you drop in the root of your repo. It tells any AI coding tool how your project works — how to build it, the rules it must follow, and what it must never touch. More than 28 tools now read it (Codex, Cursor, Copilot, Antigravity, Aider, Cline, Zed and more), it lives in tens of thousands of repos, and since late 2025 it’s governed as a shared standard under the Linux Foundation. Write it once and your project explains itself to whatever agent you reach for next.
Three things, written for a machine that has never seen your project: how to run it, how to write code that fits, and the lines it must not cross.
The exact commands an agent should run to install dependencies, start the dev server, build for production, run tests, and lint. Spell them out so the agent stops guessing — and so a teammate (or future you) can run them too.
How you name things, which framework patterns you use, where files live, and the conventions you actually enforce. Point the agent at the patterns already in your repo instead of letting it invent a second architecture.
Folders, files, and secrets the agent must never edit or read — generated code, migrations, .env files, vendored libraries. Clear boundaries are what keep an agent from quietly breaking the thing that already works.
The point isn’t to bet on one vendor. It’s to build a habit that outlasts every tool: writing a brief so clear that any agent can follow it.
The rules live in your repo, not in one vendor's settings panel. Switch from Cursor to Copilot to Codex tomorrow and your project still explains itself. The craft you build — writing a clear brief a machine can follow — transfers with you, not with whoever is winning this quarter.
AGENTS.md is committed like any other file, so it ships with your clone, your fork, and your pull request. Every agent that opens the project — yours or a collaborator's — reads the same rules. No setup ritual, no tribal knowledge.
No new format to learn, no schema to memorise — plain headings and bullet points. That simplicity is exactly why 28+ tools agreed to read it, and why it now sits under the Linux Foundation as a shared, vendor-neutral standard.
Save this as AGENTS.md in the root of your repo, then edit the commands and rules to match your project. Keep it short and honest — a file that lies about your commands is worse than no file at all.
# AGENTS.md
## Project
A short, plain description of what this project is and who it is for.
Tech stack: e.g. Next.js (App Router), TypeScript, Tailwind.
## Setup
```bash
npm install
```
## Commands
- Dev server: `npm run dev`
- Build: `npm run build`
- Lint: `npm run lint`
- Test: `npm test`
Always run lint and test before you say a task is done.
## Code style
- TypeScript, no `any` unless unavoidable.
- Reuse existing components and helpers before writing new ones.
- Match the file and folder structure already in the repo.
- Keep functions small and named for what they do.
## Do not touch
- Do not edit files in /generated or /migrations.
- Never read, print, or commit .env or any secret.
- Do not add new dependencies without saying why first.
## Definition of done
- The app builds and runs.
- Lint and tests pass.
- The change is small enough to review in one sitting.