AGENTS.md template — a copy-paste starter that doesn't waste tokens

AGENTS.md is the shared instructions file 60k+ open-source projects now use to brief coding agents — Codex, Cursor, VS Code agent mode, and Windsurf read it natively, and Claude Code reads it through a one-line shim. What most repos get wrong isn’t missing the file; it’s filling it with things agents already know. This page is the opposite: a minimal starter where each section exists because agents demonstrably fail without it.

The template

# AGENTS.md

## Project
One paragraph: what this codebase does, the stack, and the one
architectural fact agents keep getting wrong about it.
(e.g. "API and worker share types from packages/core — change
them together or CI fails.")

## Commands
- Install: `pnpm install`
- Build: `pnpm build`
- Test one file: `pnpm vitest run <path>`   # agents default to the
                                            # full suite; give the fast path
- Lint + typecheck: `pnpm lint && pnpm tsc --noEmit`
- Never run: `pnpm deploy` (CI-only), `pnpm db:reset` (destructive)

## Conventions
- TypeScript strict. No `any` — fix the type, don't cast around it.
- Imports absolute from `src/`. No relative `../../`.
- Errors: throw typed `AppError` subclasses, never bare strings.
- New code follows the patterns of its nearest neighbor file.

## Boundaries
- Don't edit `src/generated/**` — regenerated on every build.
- Don't modify existing files in `db/migrations/` — append new ones.
- Secrets come from env vars. Never hardcode, never commit fixtures
  containing real data.

## Done means
- `pnpm test` green, no new lint or type errors.
- If you changed behavior, you changed or added a test.

Fill in your stack, delete the comments, keep the five headings. If a section tempts you past ~10 lines, that content probably belongs in a linked doc, not in every agent’s context window.

The Claude Code shim

Claude Code doesn’t read AGENTS.md natively — Anthropic’s docs say it verbatim: “Claude Code reads CLAUDE.md, not AGENTS.md.” The officially documented bridge is a CLAUDE.md whose first line imports it:

# CLAUDE.md
@AGENTS.md

# Claude-only notes (only what differs from the shared file)
- Use the ripgrep MCP server for search, not bash grep.

One source of truth, every tool reads it. On Windows, skip the symlink alternative — it needs Administrator privileges; the import doesn’t.

Why these five sections, and no others

• Project exists because agents infer architecture from whatever files they happen to open. One paragraph of orientation beats them re-deriving it wrong every session.
• Commands is the highest-value section in the file. The single-file test command alone pays for the whole template: without it, agents run your full suite after every edit. The “never run” line is your blast-radius insurance.
• Conventions should hold only rules a fresh, competent model would get wrong — your deviations from defaults, not a style guide. Agents already write idiomatic TypeScript; they don’t know you ban any casts.
• Boundaries prevents the expensive failure mode: an agent helpfully “fixing” generated code or old migrations and burning an hour of cleanup.
• Done means turns “I think I’m finished” into a checkable claim. Agents stop earlier and verify more when the exit condition is written down.

The discipline behind the brevity is documented pain: instruction files are prepended to every turn, so size costs you twice — tokens and attention, and a bloated shared file multiplies that across every tool on the team. The community keeps arriving at the same conclusion — a recent write-up even proposes RFC-2119-style MUST/NEVER phrasing to keep rules compact and unambiguous. You don’t need the formality; you need the restraint.

What to leave out

• Personal preferences (“I like verbose commit messages”) — they belong in your personal ~/.claude/CLAUDE.md or equivalent, not in the shared file.
• Anything the linter enforces — the agent gets the error message anyway; duplicating it is pure tax.
• Long architecture docs — link them (“see docs/architecture.md”) so agents read on demand instead of carrying them every turn.
• Tool-specific config for tools that have their own files (Cursor rules, hooks). The shared file is for what’s true regardless of which agent shows up.

Monorepo variation

Drop a root AGENTS.md with the global facts, then a short one per package with only the local deltas:

repo/
  AGENTS.md              # stack, shared commands, org-wide boundaries
  apps/web/AGENTS.md     # "Next.js app. Test: pnpm --filter web test"
  packages/core/AGENTS.md

Cursor reads nested AGENTS.md files natively; Codex applies the nearest file up the tree. For Claude Code, mirror the same structure with per-directory CLAUDE.md shims (@../../AGENTS.md plus the local one) — its memory hierarchy merges them top-down.

Companion reading

• CLAUDE.md vs AGENTS.md — which one does Claude Code actually read? — the full state of the standard, and when to make which file canonical.
• How big can your instructions file get before it hurts? — the research behind the size budget.
• Five habits that quietly burn tokens — the audit checklist for a file that’s grown.
• How to write a great CLAUDE.md — file craftsmanship, whichever name it lives under.