Create a Markdown file called AGENTS.md in your repository root with the exact commands to install, run, test and build, a short map of the folders, your coding rules and a definition of done. Keep it under about 60 lines. Many agents read it automatically; for tools that use a different file, point them at it. Then ask the agent how it would test the project to confirm it read the file.
Tools you need
The 9 steps
Decide what the agent needs to know
An agent starts every session knowing nothing about your project. Write down the things you would tell a new teammate on day one: how to run the project, how to test it, where things live, what never to do. Leave out anything the code already makes obvious.
Create the file at the repository root
Create AGENTS.md next to package.json (or your language's equivalent). A plain Markdown file is the whole format, and it is used by many agents, including Codex, Cursor, Zed, OpenCode, Cline, Goose and GitHub Copilot.
Add the exact commands
Commands are the most useful lines. Run each one yourself first so you know it works:
## Commands
- Install: `npm install`
- Run locally: `npm run dev` (opens http://localhost:5173)
- Test: `npm test` (run before every commit)
- Lint: `npm run lint`
- Build: `npm run build`Add a short map of the project
Three to six lines, not a tour:
## Structure
- `src/pages/`: one file per screen
- `src/lib/supabase.js`: the only place that talks to the database
- `src/components/`: shared UI built with shadcn/uiAdd your rules
Rules stop the mistakes you would otherwise fix repeatedly:
## Rules
- Never commit secrets or edit `.env` files. Use environment variables.
- Ask before adding a new dependency and say why.
- Make small changes: one feature per task, touch only the files needed.
- Every database table needs row-level security. Never use a service key in browser code.
- Write a test for any rule about who can see what.Add a definition of done
Tell the agent when it can stop:
## Done means
- The app runs, `npm test` and `npm run lint` pass, and the diff contains only what was asked.
- You have listed what changed and anything you were unsure about.Make other tools read it
Some tools look for their own file. Keep AGENTS.md as the single source and point to it. Claude Code reads CLAUDE.md first and reads AGENTS.md only if there is no CLAUDE.md, so create a CLAUDE.md containing one line: @AGENTS.md. For GitHub Copilot use .github/copilot-instructions.md, and for Gemini CLI or Antigravity use GEMINI.md or set the file name in settings. Check each tool's docs for the current rule.
Test that it works
Open a new agent session and ask: What commands would you run to test this project, and what rules must you follow? If the answer does not match your file, the agent is not reading it. Check the file name, the folder and the tool's settings.
Keep it short and keep it honest
A long rules file is partly ignored. Keep it under about 60 lines. Each time the agent repeats a mistake, add one line; each time a line stops mattering, delete it. Commit AGENTS.md with the code so it changes with the project.
Make it yours
- Add a Testing section that lists the three tests that must always pass.
- Write a second file for a frontend folder with its own rules; the nearest file to the code usually wins in tools that support nested files.
- Add a Security section that links to your project's checklist.
- Ask the agent to draft AGENTS.md from your repository, then edit it down by hand.
Troubleshooting
| Problem | Fix |
|---|---|
| The agent ignores the file | Check the file is named exactly AGENTS.md at the repository root and that your tool supports it. If it uses a different file, point that file at AGENTS.md. |
| The agent follows only some rules | The file is probably too long. Move the three rules that matter most to the top and delete the rest. |
| Claude Code does not use my AGENTS.md | It reads CLAUDE.md first. Add a CLAUDE.md with the line @AGENTS.md. |
| Commands in the file no longer work | Run every command again after dependency or script changes and update the file in the same commit. |
Frequently asked questions
What is AGENTS.md?
A plain Markdown file at the root of a repository that tells AI coding agents how to build, test and work on the project. It is an open format and many agents read it.
What is the difference between AGENTS.md and CLAUDE.md?
AGENTS.md is the shared open format. CLAUDE.md is the file Claude Code reads first. Keep your rules in AGENTS.md and have CLAUDE.md import it with @AGENTS.md.
How long should an AGENTS.md be?
Short enough that every line matters, roughly under 60 lines. Commands, a tiny project map, your rules and a definition of done cover most projects.
Should I copy a rules file from a list online?
Use community collections such as awesome-cursorrules as inspiration, but read each rule and delete anything that does not apply to your project.
Learn this with mentors
Programmes for builders and engineers with admissions open: live classes, mentors and project work.
