How to Write an AGENTS.md File Agents Actually Follow

To write an AGENTS.md file that agents actually follow, put it at the repo root and fill it with operating instructions rather than documentation: the exact commands to build, test and lint, the directory map, the conventions that are non-negotiable, and the things that will break production if touched. Every line should be something an agent can act on or check. Anything an agent cannot verify is decoration, and decoration is what gets ignored.

The format is an open specification, published at agents.md and donated to the Linux Foundation's Agentic AI Foundation in December 2025. Adoption is the reason to care: tens of thousands of repositories use it and more than twenty coding tools read it, including Codex, Claude Code, Cursor, GitHub Copilot, Aider, Zed, Windsurf and Jules. One file, most of your team's tools. It matters just as much solo: choosing the right AI coding agent for solo work usually comes down to which one actually reads a file like this.

Why most AGENTS.md files do nothing

Open a random AGENTS.md and you will usually find a project description, a paragraph about the tech stack, and some adjectives. "Write clean, maintainable code." "Follow best practices." "Ensure good test coverage."

None of that changes behaviour, because none of it is falsifiable. An agent cannot check whether it wrote clean code. It can check whether npm run lint exits zero. The single highest-leverage edit you can make to an existing AGENTS.md is to delete every line that is not a command, a path, a number, or a hard prohibition.

The second reason they fail is length. These files are prepended to the agent's context on every task. A 4,000 word AGENTS.md is 4,000 words competing with the code the agent needs to read, which is the same context budget problem that makes agents lose track in large codebases. Aim for one screen of dense, specific instruction. If it does not fit, the overflow belongs in linked files the agent can read on demand.

What to write in an AGENTS.md file

Commands, first and exact

Put these at the top. Agents look for them and will guess badly if they are missing, and a wrong guess costs a failed run and a confused retry.

## Commands

- Install: `pnpm install --frozen-lockfile`
- Dev server: `pnpm dev` (port 5173)
- Build: `pnpm build`
- Typecheck: `pnpm typecheck`
- Lint: `pnpm lint` (must exit 0 before any commit)
- Test all: `pnpm test`
- Test one file: `pnpm test -- path/to/file.test.ts`

That last line matters more than it looks. Without it, an agent verifying a one-line change runs the entire suite, waits four minutes, and burns context on output it did not need.

A map, not a tour

Tell the agent where things live so it can search instead of reading directories at random.

## Layout

- `src/routes/` file-based routes, one folder per route
- `src/lib/server/` server-only code, never import from client components
- `src/lib/db/schema.ts` Drizzle schema, source of truth for the database
- `supabase/migrations/` generated, never hand-edit
- `tests/e2e/` Playwright, requires the dev server running

Conventions, stated as rules

Write these as things to do and not do, with the reason attached where the reason is not obvious. Agents comply better when a rule has a stated consequence, and so do humans.

## Conventions

- Named exports only. Default exports break our barrel files.
- Errors: throw `AppError` from `src/lib/errors.ts`, never a bare `Error`.
- No `any`. Use `unknown` and narrow it.
- Database access only through `src/lib/db/`. No raw SQL in route handlers.
- New dependencies need a note in the PR description explaining why.

The do-not-touch list

This is the section that prevents the expensive failures. Be blunt.

## Do not touch

- `supabase/migrations/*` regenerate with `pnpm db:generate`, never edit by hand
- `src/lib/legacy/billing.ts` scheduled for removal, do not refactor
- `.env*` never read, never modify, never print values
- Anything under `vendor/` is a vendored copy, patch upstream instead

Definition of done

Give the agent a checklist it can run before it claims to be finished. This one change does more for output quality than any amount of prose about care and craftsmanship.

## Before you say you are done

1. `pnpm typecheck` passes
2. `pnpm lint` passes
3. Tests for changed files pass
4. No new `console.log` in `src/`
5. If you changed the schema, you ran `pnpm db:generate`

A complete short example

Here is a full file for a small service. It fits on one screen, and every line is checkable.

# AGENTS.md

Python API for invoice parsing. FastAPI, Postgres, deployed on Fly.

## Commands
- Setup: `uv sync`
- Run: `uv run fastapi dev app/main.py`
- Test: `uv run pytest`
- Test one: `uv run pytest tests/test_parse.py::test_name`
- Lint: `uv run ruff check . && uv run ruff format --check .`
- Types: `uv run mypy app`

## Layout
- `app/routers/` one module per resource
- `app/services/` business logic, no FastAPI imports here
- `app/models/` SQLAlchemy models
- `alembic/versions/` generated migrations, never hand-edit

## Conventions
- Services take and return dataclasses, never request or response objects.
- All money is `Decimal` in minor units. Never float.
- Times are UTC, stored as `timestamptz`.
- Every new endpoint needs a test that asserts the 4xx path too.

## Do not touch
- `app/legacy_ocr/` frozen, being replaced
- `alembic/versions/*` generate with `uv run alembic revision --autogenerate`
- `.env`, `secrets/` never read or print

## Before you say you are done
1. `uv run ruff check .` passes
2. `uv run mypy app` passes
3. `uv run pytest` passes
4. No `print()` left in `app/`

Roughly 200 words. That is the right order of magnitude.

Nested files for monorepos

The specification supports AGENTS.md at any directory level, and the nearest file to the code being edited wins. In a monorepo, keep a thin root file with the things that are true everywhere, then a specific file inside each package. For a deeper look at where those package-level files should sit, see how to structure a monorepo for AI coding agents.

AGENTS.md                  # commit style, security rules, monorepo commands
apps/web/AGENTS.md         # Next.js conventions, component patterns
apps/api/AGENTS.md         # FastAPI conventions, migration workflow
packages/ui/AGENTS.md      # design tokens, Storybook, no app imports

This keeps each file short and stops a frontend task from carrying database migration rules it will never use.

Mistakes worth avoiding

• Writing it for humans. A README explains the project to a new hire. AGENTS.md tells a machine what to run. Keeping both is fine; merging them is not.

• Letting it rot. A stale command is worse than a missing one, because the agent trusts it and fails confusingly. Update the file in the same PR that changes the command.

• Restating the obvious. Do not tell the agent to write tests if your definition of done already requires them to pass. Redundancy costs context.

• Vague prohibitions. "Be careful with the auth code" does nothing. "Do not modify src/auth/session.ts without a passing pnpm test:auth" does.

• Skipping the reason on surprising rules. A rule that looks arbitrary gets rationalised away. Two words of justification prevent that.

• No verification step. Without a definition of done, agents report success on code they never ran.

How to know if it is working

Run the same task twice, once with the file and once with it renamed, on a fresh session each time. You are looking for concrete differences: did the agent run the right test command, did it put the file in the right directory, did it use your error type. If the outputs are indistinguishable, your file is documentation and needs rewriting into instructions.

After that, treat it as a living record of every mistake worth preventing twice. When an agent does something wrong, and the mistake was predictable from information you had, that is a missing line. This compounds quickly, and it pairs well with keeping a proper prompt library for the tasks your team repeats. If you are still choosing between tools, the survey of AI coding tools covers which ones read this file.

Common questions

Do I need AGENTS.md if I already have CLAUDE.md or .cursorrules?

AGENTS.md is the format most tools read, so it is the one worth maintaining. Several tools support importing it from their own config file, which lets you keep one source of truth and a one-line shim for anything that has not adopted it.

How long should an AGENTS.md file be?

Under 400 words for most repositories. It is prepended to every task, so length is a direct tax on the context available for actual code.

Should it be committed to the repository?

Yes. It is shared configuration, it should be reviewed like code, and its history tells you which rules were added after which incident.

Will an agent always obey it?

No. It is strong context, not enforcement. Rules that matter should also be enforced by something that cannot be talked out of it: a linter, a test, a CI check. Treat AGENTS.md as the layer that stops mistakes early and code review as the layer that catches what it missed.

The same discipline that makes a good AGENTS.md file useful applies to documentation for humans. See how to use AI to write documentation for your codebase for the workflow, including how to keep it from going stale.