Before you start: keep it short and imperative
The single biggest factor in whether an agent follows your AGENTS.md is format. Agents reliably follow short, explicit, imperative lines — “Run pnpm test before finishing.” They’re far worse at extracting rules from long paragraphs. So write in scannable bullet points, put the most important rules first, and aim for well under a page. A focused 30-line file beats a rambling 200-line one.
Step 1 — Add a one-line project overview
Start with a sentence or two: what the project is and the core stack. This gives the agent context for everything below.
## Project
A FastAPI service exposing the billing API. Python 3.12, Postgres, Pydantic v2.Step 2 — List the exact setup & commands
Give the real commands, with the exact package manager — pnpm, npm, uv, poetry all behave differently, and an agent that guesses wrong wastes a turn. Include install, dev/run, build, and test. Tell the agent to run the tests before considering a task complete.
## Setup & commands
- Install: `uv sync`
- Run: `uv run uvicorn app.main:app --reload`
- Test: `uv run pytest` — run before marking any task done.
- Lint/format: `uv run ruff check` and `uv run ruff format`Step 3 — State your code style
Write down the conventions a new teammate would need — typing, formatting, and the patterns you expect. Be specific enough to be checkable.
## Code style
- Type hints on every function signature.
- Pydantic models for all request/response bodies.
- Follow PEP 8; format with `ruff format`.
- async/await only — no raw promise chains or blocking calls in handlers.Step 4 — Describe the project structure
A few lines on where things live so the agent puts new files in the right place and doesn’t duplicate what exists.
## Structure
- `app/routers/` — API routes, thin; no business logic.
- `app/services/` — business logic lives here.
- `app/models/` — Pydantic + DB models.
- `tests/` — mirror the `app/` layout.Step 5 — Write the guardrails (most important)
This is the section that saves you the most cleanup. List the explicit “never do this” rules — the things agents reliably get wrong. Be blunt and specific.
## Guardrails
- Never log request bodies that may contain secrets or tokens.
- Never hand-edit Alembic migration files after they’re generated.
- Don’t put business logic in route handlers — keep them thin.
- Never commit secrets or `.env` files.
- Keep DB sessions request-scoped; don’t open global connections.Step 6 — Test it, then keep it current
Once the file is in place, give your agent a small real task and watch whether it follows the rules. If it does something you didn’t want, that’s usually a missing or vague guardrail — add it. The file is living documentation: when your scripts or conventions change, update AGENTS.md in the same commit, or it slowly drifts out of sync and agents start trusting stale rules. A quick lint now and then catches gaps.
Mistakes that make agents ignore your file
- Prose over bullets. Long paragraphs bury the rules; agents skim them.
- No guardrails. Without explicit “don’t” rules, the agent fills the gaps with guesses.
- Vague commands. “Run tests” instead of the exact command.
- Contradicting reality. Rules that no longer match the codebase teach the agent the wrong thing.
- One giant file in a monorepo. Use a scoped AGENTS.md per package so each gets the right rules.
The shortcut: generate it
You don’t have to write all this from scratch. The free agentsmd generator detects your stack and produces a tuned AGENTS.md — with the right commands, conventions and guardrails already filled in — in about thirty seconds. You can edit from there and export the same file to CLAUDE.md, .cursorrules and Copilot’s format. For a finished reference, see the AGENTS.md examples.
Frequently asked
How long should an AGENTS.md be?
As short as it can be while still covering setup, code style, structure and guardrails — usually well under a page. Scannable bullets, not prose.
What’s the most important part to get right?
The guardrails — the explicit “never do X” rules. They’re what agents most reliably get wrong, so they save the most cleanup.
Should I write it by hand or generate it?
Generating gives you a correct, stack-tuned starting point in seconds; then edit it to match your project. Writing from scratch works too, but it’s slower and easy to leave gaps.
How do I keep it from going out of date?
Update AGENTS.md in the same commit that changes your scripts or conventions, and lint it occasionally. A file that disagrees with your codebase is worse than none.
Can one AGENTS.md cover a monorepo?
You can, but it’s usually better to add a scoped AGENTS.md inside each package. Agents read the nearest file, so each package gets rules tuned to it.