How to Write an AGENTS.md That Coding Agents Follow

Your coding agent just ran the wrong test command, reformatted forty files and touched the lockfile. It wasn't being rebellious. Nobody told it how your repo works. By the end of this guide you'll have a short AGENTS.md file, the plain markdown file that coding agents read before they work, and a way to check that the agent really obeys it.

AGENTS.md is an open convention described at agents.md. Think of it as a README for machines: it sits in the repo and holds the build steps and conventions that would clutter a human README. Many coding agents read it, and tools that look for their own file (Claude Code reads CLAUDE.md) can be pointed at it.

1. Create the AGENTS.md file at the repo root

One file, plain markdown, no required fields. Put it at the root so every agent finds it. In a monorepo, you can add more AGENTS.md files in subfolders, and the agents.md site says the closest one to the file being edited wins.

touch AGENTS.md

Keep it under roughly 60 lines. Agents read the whole thing on every task, and a long file buries the rules that matter.

2. List exact build and test commands

This is the highest-value section. Agents guess commands when you don't give them, and guesses are where the wrong test runner comes from. Write commands in full, with the flags, in backticks.

## Commands
- Install: `pnpm install --frozen-lockfile`
- Dev server: `pnpm dev`
- Unit tests (fast, run these constantly): `pnpm test --run`
- Single file: `pnpm test --run src/billing/invoice.test.ts`
- Lint and types: `pnpm lint && pnpm typecheck`
- Do NOT run `pnpm test:e2e` locally. It needs a staging database.

Swap in your own tools. The last line matters: telling the agent which command to avoid saves more time than another command it can run.

3. Set boundaries the agent must not cross

Use short, absolute statements. Split them into three tiers so the agent knows what needs a human.

## Boundaries
- Always: follow the existing folder layout, add a test for every bug fix.
- Ask first: new dependencies, schema migrations, changes to CI config.
- Never: edit files in `generated/`, commit secrets or `.env` files, rewrite the lockfile by hand, force-push.

Name real paths. Never write 'be careful with config'; write the file that must not change.

4. Add conventions the linter can't enforce

Only include what the tooling doesn't already catch. If a formatter fixes it, leave it out.

## Conventions
- Money is integer cents, never floats.
- Services return `Result<T, AppError>`; don't throw across module boundaries.
- New endpoints go in `src/api/routes/` with a matching `*.test.ts` beside them.

5. Define done so the agent can check itself

Agents stop when the code looks plausible. Give them a checklist that ends with commands they can run.

## Definition of done
1. `pnpm lint && pnpm typecheck && pnpm test --run` all pass.
2. New behavior has a test; the diff touches only files the task needs.
3. The summary lists what changed, what you ran, and anything you skipped.

Point 3 is a quiet win for reviewers: you see what the agent ran instead of trusting it.

6. Test that your AGENTS.md coding agents actually follow

A rule you haven't tested is a hope. Open a fresh session so no earlier context leaks in, then run probes that each target one rule.

Probe 1 (commands): Add a unit test for src/billing/invoice.ts and run it.
Expect: the single-file command from the file, not a full-suite run.

Probe 2 (boundary): Add the lodash package to help with this.
Expect: the agent stops and asks, because new dependencies are Ask first.

Probe 3 (done): Fix the rounding bug in invoice totals.
Expect: a test added, lint, typecheck and tests run, and a summary of them.

If a probe fails, don't add more words. Make the rule shorter, move it higher, or replace a vague phrase with a command or a path. Re-run the probe until it passes, and keep the probes in the repo so you can re-run them when the file changes.

Gotchas

• Tool-specific files: if your agent reads its own file, such as CLAUDE.md, check its docs for how to import AGENTS.md rather than keeping two copies that drift.
• Stale commands: a renamed script makes the agent fail confidently. Update the file in the same pull request that changes the script.
• Contradictions: a root file saying one thing and a subfolder file saying another produces coin-flip behavior. Remember the nearest file wins.
• Secrets: this file is committed and read by tools. Never put keys or internal URLs in it.
• Wall of text: every line you add dilutes the others. Delete anything an agent hasn't needed in a month.

A short, tested AGENTS.md turns an agent's guesses into your team's workflow, which is what lets you trust its pull requests in production.