Why AGENTS.md beats a long README.
Your README is for humans deciding whether to use the project. AGENTS.md is for AI coding agents already inside it. The audiences need different things. Humans want context, motivation, screenshots. Agents want commands, conventions, and the three things you'll yell about in code review if they get them wrong.
Every modern coding agent — Cursor, OpenAI Codex, Claude Code, Aider, OpenCode — reads AGENTS.md automatically when it opens your repo. The file is loaded into the system prompt for every turn, so every word is a permanent tax on every request you'll ever send. That's the trade: high leverage, expensive per byte. Treat it accordingly.
- Half a page beats six. Five well-chosen rules outperform fifty vague ones because the agent will actually attend to all of them.
- Concrete commands beat philosophy.
pnpm test --filter webis useful. "Write good tests" is not. - Project-specific only. "Use TypeScript" is not project-specific. "Don't add new
anys — we have 4 left and we're paying them off" is.
Anatomy of a good file.
The shape that works across thousands of repos is small and almost boring. Five sections, in this order, because each one answers the question the agent is about to ask:
| Section | Question it answers | Length |
|---|---|---|
| Stack | What am I editing? | 1–3 lines |
| Commands | How do I run, test, and lint this? | 4–8 lines |
| Conventions | How do we write code here, specifically? | 5–10 bullets |
| Don'ts | What will get reverted on review? | 3–6 bullets |
| When unsure | What's the escape hatch? | 1–2 lines |
# Project Next.js 15 (App Router), TypeScript strict, Tailwind v4, Drizzle + Postgres. Monorepo: apps/web, apps/api, packages/ui. ## Commands - Install: pnpm install - Dev: pnpm dev (turbo, all apps) - Test: pnpm test (vitest, watch off) - Lint: pnpm lint --fix (eslint + biome) - Types: pnpm typecheck ## Conventions - Server Components by default. Add 'use client' only when you need state or events. - Data fetching in app/**/page.tsx or server actions — never in client components. - Tailwind utilities inline; extract to a component when used 3+ times. - Forms: react-hook-form + zod schemas in lib/validators. - Errors: throw in server code, handle in error boundaries. Never try/catch to swallow. ## Don't - Add new dependencies without checking package.json for an existing equivalent. - Use any. We have 4 left, tracked in TODO-types.md. - Edit generated files in drizzle/ or .next/. - Write tests that hit the network. Mock at the fetch boundary. ## When unsure Ask. A 30-second clarifying question is cheaper than a 30-minute revert.
That's it. If you're tempted to add a sixth section, ask whether it belongs in the README, a CONTRIBUTING file, or a per-package AGENTS.md instead.
Framework specifics.
The agent already knows Next.js exists. What it doesn't know is which Next conventions you care about. These are the lines that pay for themselves on every framework:
| Framework | Lines worth writing |
|---|---|
| Next.js (App Router) | Server vs client component default; data-fetching boundary; route group conventions; server actions yes/no. |
| Astro | Which UI framework lives in src/components; static vs island; content collections schema location. |
| SvelteKit | Where load functions live (+page.ts vs +page.server.ts); form actions vs API routes; runes opt-in. |
| Remix / React Router 7 | Loader vs action vs client loader; nested route data flow; defer usage. |
| Nuxt | Auto-import conventions; useFetch vs $fetch; layer extension; server route casing. |
| Vanilla / Vite | What router; what state lib; what CSS strategy. The agent will guess wrong if you don't say. |
They cover defaults. Your project has opinions on top of defaults — that's the gap AGENTS.md closes. If a senior dev would correct an agent on it during review, write it down.
Monorepo layering.
Cursor, Codex, and Claude Code all read nested AGENTS.md files. A file at apps/api/AGENTS.md layers on top of the root file when the agent is editing inside that directory. Use this to keep the root file short:
- Root file: stack, monorepo layout, repo-wide commands, repo-wide don'ts.
- Per-package file: what's different about this package. The API package's testing story is not the same as the UI package's.
# API package Hono on Cloudflare Workers. Postgres via Drizzle, neon-http driver. ## Routes - One route file per resource, under src/routes/. - Validate body and query with zod before touching the DB. - Return Response.json(data, { status }) — no custom helpers. ## Tests - Vitest in-process; use app.request(), not fetch. - Each test gets a fresh DB transaction, rolled back at the end. ## Don't - Use node:fs or any Node-only API. We run on Workers. - Add middleware to the root app; scope to the router.
Live: generate your AGENTS.md.
Pick a framework, a few conventions, and your common don'ts. The widget renders an opinionated AGENTS.md tailored to your stack. Copy it, drop it at your repo root, edit the bits that don't fit. Everything runs locally; nothing leaves the page.
Read the bytes counter. Every byte here ships on every turn. If you cross 1.5 KB you've passed the point where most agents start skimming.
Common pitfalls.
"Write clean code." "Be thoughtful." "Prefer simplicity." These are unprovable, so the agent ignores them. Replace each with a single concrete example: "Components over 200 lines get split."
npm run dev stops working when you switch to pnpm but the agent still tries it for a week. Audit your commands every time you change scripts. The cheapest CI check you'll ever write is "does AGENTS.md mention any script not in package.json?"
Most "AGENTS.md template" gists are someone's last project's defaults dressed up as universal wisdom. Half the rules won't apply, the agent will follow them anyway, and your code will drift toward a project that isn't yours. Generate one for your stack — even with the widget above — and edit from there.