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. Claude Code reads it natively only as a fallback, so the dependable route there is 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

Since v2.1.277 (September 2026), Claude Code reads AGENTS.md on its own — but only when there’s no CLAUDE.md or CLAUDE.local.md in the working directory or above, and older versions don’t read it at all (we tested when it loads). The bridge that works on every version and in every setup 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. Claude Code 2.1.277+ can read nested AGENTS.md files on its own, but only in a repo with no CLAUDE.md above them; once any exists, the shims are what keep the package files loading (tested).

Companion reading

• Claude Code reads AGENTS.md now — but five ordinary setups still leave it unread — when the native fallback loads, measured, and why the shim above still wins.
• 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.
• Shopify’s CEO threatened to ban Claude Code over AGENTS.md — every bridge tested, and why the shim below is the one to use on a mixed-platform team.
• 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.