How to Write an AGENTS.md That AI Coding Agents Follow

Published 2026-10-16 · 3 min read · by AgentKit Co

An AGENTS.md file is a README for coding agents. The format is deliberately simple: plain Markdown, no required fields, and the closest file to the code being edited takes precedence. The hard part is not the format. It is deciding what to write so the agent follows it. This guide covers the sections that earn their place and the habits that keep the file useful.

Start with five sections

1. Project: one or two lines. What it is and the stack with versions.
2. Commands: install, run, test all, test one file, lint, type-check, build. This is the highest-value section, because agents run what you list.
3. Layout: where things live, only where it is not obvious.
4. Conventions: rules that differ from the language defaults, each with a file to copy from.
5. Boundaries: what to ask about first and what to never touch.

Add a short Git note if you have commit or pull request rules.

## Commands
- Install: `pnpm install`
- Test one file: `pnpm test path/to/file.test.ts`
- Before finishing: `pnpm tsc --noEmit && pnpm lint && pnpm test`

## Boundaries
- Ask before adding a dependency.
- Never edit files in `migrations/`; create a new one.
- Never read, print or commit `.env*` files.

Eight rules for lines agents follow

1. Commands before prose. "Run pnpm test before finishing" beats "make sure it works".
2. Be checkable. "Components live in src/components/<Name>/" can be verified. "Keep code organized" cannot.
3. Say what to copy. "New endpoints: copy src/api/users/route.ts" gives the agent a working example.
4. Only the non-obvious. Skip advice any agent already follows, such as "use meaningful names".
5. Name the hazard. "Never edit applied migrations" is better than "be careful with the database".
6. Give the reason when a rule is surprising. A reason helps the agent apply the rule sensibly.
7. One home per fact. If the same command is in the README, AGENTS.md and CLAUDE.md, one of them will go stale.
8. Prune after mistakes. Add a line when the agent makes the same mistake twice, and delete lines it already follows.

Keep it short, and keep it honest

Anthropic suggests under 200 lines for a CLAUDE.md, and the same advice applies to any instruction file. When a file grows, split area-specific rules into nested AGENTS.md files or path-scoped rules. Remember too that these files are guidance: an agent can still ignore a line, so back critical limits with permission settings or hooks.

Let the agent audit the file

Once you have a draft, ask your agent to check it. This prompt sorts every line into keep, verify, cut, merge or move, and waits for your approval:

Audit the file [PATH TO INSTRUCTION FILE]. Do not edit it yet.

Sort every line into one of five groups:
KEEP: concrete, checkable, and not obvious from the code.
VERIFY: refers to a command, path or tool. Check that it exists and report what you found.
CUT: vague ("write clean code"), generic advice any agent already follows, or a copy of README content.
MERGE: duplicates or overlaps another line.
MOVE: only matters for part of the repo, so it belongs in a path-scoped rule or a nested file.

Output a table: line number | group | reason. Then show the trimmed file and a one-line summary of how many lines you removed. Wait for my approval before writing anything.

Then check that every command in the file really exists. A stale command costs more than a missing one, because the agent trusts it.

Make your first file now

The free AGENTS.md generator builds a starting file from your stack and commands, and also outputs a matching CLAUDE.md, Cursor rule and Copilot instructions file. For finished templates covering twelve stacks and the rest of the audit prompts, see the Config Kit below.

Format details checked against agents.md and the Claude Code, Cursor and GitHub Copilot docs on 2026-10-16. This guide was written with AI assistance. AgentKit Co is not affiliated with those companies.

Keep reading