An AGENTS.md file example for a web project is a plain Markdown file in the repository root. It lists your install, dev, build, test and lint commands, your code style, and explicit Do and Do not rules. Write it once. If you also use Claude Code, add a CLAUDE.md that contains only the line @AGENTS.md, because Claude Code’s native file is CLAUDE.md.
Key takeaways
- Put install, dev, build, test and lint commands in one AGENTS.md at the repo root. agents.md (opens in a new tab) says no fields are required.
- Write checkable lines such as "Run npm test before committing", the style the Claude Code docs recommend.
- Aider needs
read: AGENTS.mdin.aider.conf.yml, and Gemini CLI needscontext.fileNameset in.gemini/settings.json. - Create a CLAUDE.md with the single line
@AGENTS.md, and keep the shared file under 200 lines, because imports do not reduce context cost.
In this article
- An AGENTS.md file example starts with commands an agent cannot guess
- Copy this AGENTS.md template and swap the marked commands
- What does a good AGENTS.md file example look like?
- How do I adapt the AGENTS.md template for a WordPress theme or plugin?
- Which tools read AGENTS.md, and where support needs setup
- Claude Code reads CLAUDE.md, so bridge it with one line
An AGENTS.md file example starts with commands an agent cannot guess
AGENTS.md holds the build steps, test commands and conventions that a coding agent needs and a human contributor does not. agents.md (opens in a new tab) says it is standard Markdown, with no required fields and any headings you like. Your README stays short for people, and the agent gets a predictable place to look for technical information about your site.
The official sample on agents.md is a pnpm and Turborepo snippet full of <project_name> placeholders. That helps if you run a monorepo. If you have one app and want a file you can paste today, it gets you very little.
Add a line whenever the agent makes the same mistake twice. The Claude Code memory docs (opens in a new tab) give the same rule for CLAUDE.md: write down what you would otherwise retype into chat each session.
Copy this AGENTS.md template and swap the marked commands
This copy-paste template covers a single web app with Project, Commands, Code style, Do and Do not sections. Replace every SWAP marker with your real value. If your project is a WordPress theme or plugin, swap the npm lines for whatever your own build and lint scripts are.
# AGENTS.md
## Project
- SWAP: one line on the app, e.g. framework and language
- Package manager: npm. Node version: SWAP
## Commands
- Install: `npm install`
- Dev server: `npm run dev`
- Build: `npm run build`
- Test: `npm test`
- Single test file: `npm test -- SWAP/path/to/file`
- Lint: `npm run lint`
## Code style
- TypeScript strict mode. No `any`.
- 2-space indentation, single quotes, semicolons.
- Components live in `src/components/`. API handlers live in `src/api/handlers/`.
## Do
- Run `npm run lint` and `npm test` before every commit.
- Add or update tests for code you change.
- Fix lint and type errors until both commands pass.
## Do not
- Do not edit `dist/` or lockfiles by hand.
- Do not add a dependency without asking.
- Do not commit `.env` files or secrets.Every line in this template is concrete enough for you to verify. The Claude docs contrast "Use 2-space indentation" with "Format code properly" for exactly this reason: an agent can check the first and can only guess at the second.
Warning: Contradictions cost you. The Claude docs say that if two instructions conflict, Claude may pick one arbitrarily. Reread the file after each edit and delete the older rule.
What does a good AGENTS.md file example look like?
A good AGENTS.md file example is short, exact and checkable. Each line is either a command you can paste into a terminal or a rule you can confirm by reading the diff. If a line needs a human to interpret it, rewrite it or delete it.
The table below shows the pattern. The first row comes from the Claude docs. The other two rows are my own rewrites in the same style.
| Weak line | Better line |
|---|---|
| Format code properly | Use 2-space indentation |
| Test your changes | Run npm test before committing |
| Keep files organized | API handlers live in src/api/handlers/ |
Three rules decide what stays in the file:
- Keep a command if the agent cannot read it from your config. A custom test flag or a single-file test pattern belongs in the file.
- Keep a rule if the agent already broke it once. Rules you wrote "just in case" are the first to cut.
- Delete a line when the problem stops happening. The Claude docs recommend under 200 lines per file, and a short file leaves fewer places for two rules to clash.
How do I adapt the AGENTS.md template for a WordPress theme or plugin?
Replace the npm commands with the scripts your project already runs, and add the PHP checks. The block below is a starting point built from common WordPress tooling (Composer, PHP_CodeSniffer, WP-CLI). I did not run this variant against a live agent, so confirm each command exists in your project before you commit the file.
## Commands
- Install PHP deps: `composer install`
- Install JS deps: `npm install`
- Build assets: `npm run build`
- PHP lint: `vendor/bin/phpcs`
- Single file lint: `vendor/bin/phpcs SWAP/path/to/file.php`
## Do not
- Do not edit files in `vendor/` or `node_modules/`.
- Do not change `wp-config.php` or commit database dumps.
- Do not deactivate a plugin to make a test pass.The last rule matters because plugin conflicts are an easy way for an agent to "fix" a failing check without fixing the cause. If your site already has slow requests or errors you track with WP-CLI, put those exact commands in the file too.
Which tools read AGENTS.md, and where support needs setup
The list on agents.md (opens in a new tab) is the source of truth for supporting tools. It names Codex from OpenAI, Cursor, Windsurf, Zed, VS Code, Aider, Gemini CLI, Junie from JetBrains and the coding agent from GitHub Copilot, among others. Two of those need a config line, and Claude Code is handled separately below.
| Tool | What you do |
|---|---|
| Codex, Cursor, Windsurf, Zed | Listed on agents.md. Check each tool’s official docs for details. |
| Aider | Add read: AGENTS.md to .aider.conf.yml |
| Gemini CLI | Set context.fileName in .gemini/settings.json |
| Claude Code | Reads CLAUDE.md. Bridge it (next section). |
The Aider and Gemini CLI settings come from the agents.md FAQ:
read: AGENTS.md{
"context": {
"fileName": "AGENTS.md"
}
}agents.md also says the agent runs the test commands you list and fixes failures before it finishes. I would not assume that for every tool. Give your agent one small task and watch whether it actually executes npm test.
The Codex page on AGENTS.md (opens in a new tab) is where you should look for Codex specifics. The text I could read gave no file locations, merge order or size limits, so I am not stating any here. In a monorepo, agents.md says the closest AGENTS.md wins and explicit chat prompts override everything.
Claude Code reads CLAUDE.md, so bridge it with one line
The Claude Code memory docs (opens in a new tab) say Claude reads CLAUDE.md and can read a repository’s AGENTS.md in place of it. They also document @path/to/import syntax, so a CLAUDE.md can pull the shared file in. I built the file below from that syntax, and the docs pages I read do not show it as a ready-made example.
Create CLAUDE.md next to AGENTS.md with exactly this content:
@AGENTS.mdDo not wrap it in backticks inside CLAUDE.md. The docs say import parsing skips code spans and fenced blocks, so a wrapped path stays literal text. Relative paths resolve from the file that contains the import. To confirm the import loaded, run /context all in a Claude Code session and look under Memory files.
You can add Claude-only lines below the import. Everything else stays in AGENTS.md, so Codex, Cursor and Claude Code all read the same rules.
The decision rule is short. If your team only uses AGENTS.md-aware tools, skip CLAUDE.md. If anyone uses Claude Code, add the bridge.
Note: Imports organize a file, and the file stays the same size. The docs say imported files load together with the CLAUDE.md that imports them, and they recommend under 200 lines per file. A long shared AGENTS.md still costs Claude Code context.
Next step: paste the template into your repo root, fill in the SWAP values, and give your agent one small task. Add a line to the Do or Do not list for the first wrong move it makes. Then read the Claude Code memory docs (opens in a new tab) section on path-scoped rules for instructions that only matter in part of the codebase.
Frequently Asked Questions
Where do I put an AGENTS.md file on GitHub?
Commit it to the root of the repository like any other file. agents.md says that in a monorepo the closest AGENTS.md to the file being edited wins, so you can add a second one inside a subfolder for rules that only apply there. Explicit prompts you type in chat override both.
What are good AGENTS.md file examples to copy?
Start with the template in this article, then compare it with the sample on agents.md (opens in a new tab). A good file has exact commands, a few checkable style rules and short Do and Do not lists. Cut anything an agent could not verify, such as "write clean code".
Does GitHub Copilot read an AGENTS.md file?
agents.md lists the coding agent from GitHub Copilot among the tools that support the format. The sources I used gave no Copilot-specific file locations or size limits, so check GitHub’s official docs for those details. Test it by giving the agent a small task and watching whether it follows a rule from your file.
Do I need both AGENTS.md and CLAUDE.md?
Only if someone on your team uses Claude Code. Claude Code’s native file is CLAUDE.md, so create one that contains the single line @AGENTS.md and keep your real rules in AGENTS.md. If nobody uses Claude Code, skip CLAUDE.md.
How long should an AGENTS.md file be?
Stay under 200 lines. The Claude Code docs recommend that limit per file, and imported files still load into context, so splitting content across imports does not save space. Remove rules the agent no longer breaks.
Are there required fields or headings in AGENTS.md?
No. agents.md says it is standard Markdown with no required fields and any headings you like. Project, Commands, Code style, Do and Do not make a practical layout, but the format does not enforce it.