An AGENTS.md example that tells the agent what your conventions are
AGENTS.md, CLAUDE.md, and .cursorrules all do the same job: brief a coding agent before it touches your repo. Most of them are a list of virtues. Here is one, and the version that actually briefs.
The prompt below is one we wrote to show the pattern. It is not a user’s prompt. The verdict, burns, and rebuild were written by us in the roast voice, not produced by the tool.
# AGENTS.md This is a Next.js project. Write clean code. Follow our conventions. Use TypeScript. Don't break anything. Run tests before committing. Be careful with the database. Ask if unsure. Keep PRs small.
Indictment: “Follow our conventions” in a file whose entire job was to state the conventions.
“Follow our conventions.”
The agent has never seen your conventions. This line is a pointer to a document that doesn't exist, in the one document where it was supposed to live.
add: the conventions themselves: folder layout, naming, where server code goes versus client code, how errors are handled, what the lint config enforces
A rules file has to contain the rules. A reference to rules stored in someone's head is an empty file.
“Be careful with the database.”
“Careful” isn't a command. The agent will feel careful while it writes the migration that drops the column.
swap: “be careful” → “schema changes go in scripts/NNN_name.sql with a matching down migration; never run SQL against production; never edit an existing migration file”
Replace every attitude word with the specific action it is meant to prevent or require.
“Ask if unsure.”
Agents run for an hour without a human in the loop. “Ask” either stalls the run or gets silently ignored, and you won't know which.
swap: “ask if unsure” → “when the spec is ambiguous, take the smaller change, and state which reading you chose in the PR description”
Give the agent a tiebreaker it can apply alone, plus a way to make its choice visible to you.
# AGENTS.md
## Stack
Next.js (App Router), TypeScript strict, Tailwind, Supabase (Postgres + auth). Package manager: pnpm. Node 22.
## Commands
- Install: `pnpm install --frozen-lockfile`
- Typecheck: `pnpm exec tsc --noEmit` (must pass before any commit)
- Tests: `pnpm test` (unit) — run the file you touched, then the full suite before opening a PR
- Dev server: `pnpm dev`
## Layout
- `app/` routes and server components. Server actions live in `app/actions/`.
- `components/` client and shared UI. A file starting with `"use client"` must not import from `lib/supabase/admin`.
- `lib/` pure logic and data access. No React here.
- `scripts/*.sql` numbered migrations. The database schema is defined only there.
## Conventions
- Named exports; no default exports outside `app/`.
- Errors from data access return `{ ok: false, error }`; do not throw across a server action boundary.
- Copy in the UI uses sentence case and the existing voice; do not add exclamation marks.
- No new dependencies without a note in the PR explaining why an existing one doesn't work.
## Do not touch without being asked
- `lib/prompts/` prompt text, model ids, and temperatures.
- Anything under `app/api/webhooks/`.
- Existing migration files. Add a new numbered file instead.
## Database
- Schema changes: new file `scripts/NNN_short_name.sql` with a matching down migration in a comment block. Never run SQL against production from the agent.
- Never delete rows or drop columns in a migration without an explicit instruction in the task.
## When the spec is ambiguous
Take the smaller change. State which reading you chose, in one sentence, in the PR description. Do not stop to ask mid-run.
## Definition of done
Typecheck passes, tests for touched files pass, the PR description lists every file changed and why, and the diff contains only what the task asked for.A coding agent reads AGENTS.md once, at the start of a run, and then works alone for as long as the task takes. The file is the only briefing it gets. “Follow our conventions” and “be careful” cost the same tokens as the actual conventions and the actual database rules, and buy nothing.
The rebuilt file is mostly commands, paths, and prohibitions, because that is what an agent can act on. The two sections that matter most are the do-not-touch list and the ambiguity tiebreaker: the first prevents the expensive mistakes, and the second replaces “ask” with something an unattended agent can actually do.
- What is an AGENTS.md file?
- A markdown file at the root of a repository that briefs coding agents on the project: how to install and test, where things live, the conventions to follow, what not to touch, and what counts as done. Agents from several vendors read it automatically at the start of a task.
- What is the difference between AGENTS.md, CLAUDE.md, and .cursorrules?
- They serve the same purpose for different tools. AGENTS.md is a vendor-neutral convention read by several agents, CLAUDE.md is read by Claude Code, and .cursorrules is read by Cursor. The content should be the same brief; many teams keep one file and have the others point to it.
- What are .cursorrules best practices?
- State commands and paths rather than virtues, list what the agent must not touch, give an explicit tiebreaker for ambiguous specs since the agent works unattended, and define done in checkable terms such as typecheck and tests passing. Keep it under a page and update it when a rule changes.
Paste your own AGENTS.md. Get it roasted.
Meerkat reads it, names every problem, and rebuilds it sharp. Free. No signup.
- custom GPT instructionsA custom GPT instructions template that actually holds up
- Claude skill fileA SKILL.md example that Claude will actually trigger
- support agent system promptA customer support agent system prompt that knows when to stop
- business review prep promptA business review summary prompt that survives the executive reading it