How to write an AGENTS.md file for coding agents
Write a short AGENTS.md with setup and test commands, rules and boundaries, make Claude Code and Gemini CLI load it, and test it with a small task.
An AGENTS.md file is a plain Markdown file at the root of your repository that tells coding agents how to work on the project: which commands to run, where code lives and what to leave alone. It has no required sections. Keep it short, make every rule checkable, and confirm that each agent loads it.
This guide covers what to include, a template, how Claude Code and Gemini CLI find the file, and a quick test. The same steps apply when you start agents from your phone with Mono by Reunified.
1. Decide what belongs in the file
The agents.md site calls it a README for agents. Include the facts every session needs, and skip anything the agent can learn from the code.
| Put it in AGENTS.md | Leave it out |
|---|---|
| Setup, test and lint commands | Passwords, API keys and tokens |
| Where the main code lives | A full file tree or dependency list |
| Conventions that differ from the defaults | Long procedures (link to a doc instead) |
| Files never to edit, actions to ask about first | Personal preferences (use your agent’s user-level file) |
In a monorepo, you can add an AGENTS.md inside each package. The nearest file takes precedence, and a direct instruction in your chat overrides it.
2. Start from a short template
Here’s a made-up example for “tidy-recipes”, a TypeScript web app that uses pnpm:
# AGENTS.md
## Overview
TypeScript web app for saving recipes. Components live in src/components.
## Setup
- `pnpm install`
## Test and lint
- `pnpm test` and `pnpm lint`
## Code style
- TypeScript only. One component per file.
## Boundaries
- Never edit db/migrations/.
- Ask before adding a dependency.
## Before you finish
- Run `pnpm test` and `pnpm lint`.
- List the files you changed and the test results.List only commands you’ve run in this repository. The agent will trust a wrong one.
3. Write rules an agent can check
A good rule lets you check afterwards whether the agent followed it.
| Vague | Concrete |
|---|---|
| Test your changes | Run pnpm test and pnpm lint before you finish |
| Keep files organized | Components go in src/components |
| Be careful with the database | Never edit db/migrations/ |
| Summarize your work | List the files changed and the test results |
Write boundaries as “never” and “ask first” rules, one per line.
4. Make Claude Code and Gemini CLI read it
The agents.md site lists Codex, Gemini CLI, opencode and other agents that support the format, but some need a setting first.
By default, recent versions of Claude Code read AGENTS.md only when there’s no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in the working directory or above it (see its memory docs). If you have one of those files or an older version, import AGENTS.md from CLAUDE.md. The tidy-recipes project has an old CLAUDE.md, so add this line at the top and keep Claude-only notes below:
@AGENTS.md
Prefer small commits.Start a new session, run /context and check that CLAUDE.md appears under Memory files. Without a CLAUDE.md, /memory lists the AGENTS.md path instead.
Gemini CLI reads GEMINI.md by default. To add AGENTS.md, put this in the project’s .gemini/settings.json (see its GEMINI.md docs):
{
"context": {
"fileName": ["AGENTS.md", "GEMINI.md"]
}
}Start a new session, then run /memory show to see what loaded. For other agents, check their docs.
5. Test the file with a small task
In a new session, give the agent this task:
First list the project rules you loaded and the file each came from. Then change the button text “Save recipe” to “Save” in src/components/SaveButton.tsx. Change nothing else.
Check the result against the file:
- It named AGENTS.md (or CLAUDE.md with the import).
- It ran
pnpm testandpnpm lintand reported the results. - It left db/migrations/ alone and added no dependency.
- It listed the files it changed.
Confirm the edit yourself with git diff (see reviewing AI code changes). If the agent can’t name a rule, the file probably didn’t load, so go back to step 4. If it named a rule and skipped it, make the rule more concrete.
6. Keep it short and current
Claude Code’s docs suggest keeping CLAUDE.md under 200 lines, since longer files use more context and are followed less reliably. Aim for the same with AGENTS.md. The context window guide covers what happens when the context fills up.
Update the file when an agent repeats a mistake, and delete stale commands and conflicting rules. Commit it and review changes to it like code.
The file guides the agent; it doesn’t enforce anything. To block an action, use the agent’s permission settings or deny its request (see the tool permissions guide).
In Mono, the agent starts in the project’s working directory on your computer, where it looks for these files. You can open AGENTS.md, CLAUDE.md or .gemini/settings.json in Mono’s editor, from your phone too, and edits save themselves. To create the file, ask the agent or open a terminal from the project card. Mono doesn’t check the file or change which one an agent loads. Mono isn’t available yet, but you can join the waitlist.
