AGENTS.md
Same job as CLAUDE.md, different address. CLAUDE.md is the project-context file Claude Code reads at the start of every session; the CLAUDE.md template on this site covers it. AGENTS.md is the vendor-neutral version of the same idea, and enough tools have adopted the convention (Codex, Cursor, Copilot, and a growing list of others) that it is now the closest thing to a standard location for "here is what any agent needs to know about this repo."
Whether you need it depends on who, and what, touches your repo. If you use Claude Code exclusively, CLAUDE.md alone is fine and this file is a maybe. The moment a second tool enters the picture, a collaborator on Cursor, a CI bot, you trying a different agent for an afternoon, the calculus flips, because context that lives only in a Claude-specific file is invisible to everything else, and an agent without context reverts to guessing. You already know how guessing goes.
Do not maintain two full copies; two copies of the same facts diverge, and then your agents disagree about reality depending on which file they read. Put the real content in AGENTS.md and make CLAUDE.md a pointer: a single line saying "Read AGENTS.md," plus anything genuinely Claude-specific, like skill or subagent notes. One source of truth, every tool sees it, nothing drifts.
The content rules are the same as for CLAUDE.md, so I'll compress: write facts an agent can act on, not vibes ("use pnpm, never npm" beats "we care about consistency"), keep it current or it becomes a well-formatted lie, and treat "What NOT to do" as the section that pays the rent.
# AGENTS.md
Instructions for any coding agent working in this repository.
Read this fully before making changes.
## Project
[Project name]: [one paragraph. What it is, who uses it, what "working"
means. An agent that understands the point makes better small decisions
everywhere.]
Status: [active / maintenance / experimental]
Owner: [name / handle]
## Setup and commands
[Exact commands, copy-paste runnable. This section gets used every session.]
- Install: [`pnpm install` / `uv sync`]
- Dev server: [`pnpm dev`, runs at localhost:PORT]
- Tests: [`pnpm test` / `pytest`]
- Lint / format: [`pnpm lint` / `ruff check .`]
- Build: [`pnpm build`]
Run tests and lint before declaring any task done. "It should work" is
not a status.
## Stack
- Language: [Python 3.12 / TypeScript on Node 20 / etc.]
- Framework: [FastAPI / Next.js / etc.]
- Database: [PostgreSQL 16 / SQLite]
- Package manager: [pnpm / uv, and ONLY this one; do not introduce another]
- Deployed on: [Vercel / a Mac mini in a closet / etc.]
## Layout
[Only the directories that matter, with one-line purposes. Skip the
obvious ones.]
- `src/`: [application code; frontend in `src/app`, API in `src/server`]
- `specs/`: [one markdown spec per feature; read the relevant one before
building or changing that feature]
- `docs/adr/`: [architecture decision records; do not re-propose options
these documents already rejected]
- `tests/`: [mirrors src/ structure]
## Conventions
- Style: [formatter name; run it, don't hand-format]
- Naming: [snake_case files / PascalCase components / kebab-case routes]
- Errors: [e.g. no silent catches; failures surface to logs with context]
- Commits: [conventional commits / freeform; small and single-purpose either way]
- Dependencies: propose before adding. Every dependency is a small marriage.
## What NOT to do
[The highest-value section. Every line here is a mistake that has either
happened or visibly almost happened.]
- Do NOT commit secrets. Config comes from environment variables;
`.env.example` lists them with placeholder values.
- Do NOT edit the database schema directly. Schema changes go through
migration files in [path].
- Do NOT touch [`vendor/`, `_archive/`, generated files] by hand.
- Do NOT reformat or refactor files unrelated to the current task.
- Do NOT push to main. Work on a branch; a human merges.
- Do NOT [the thing specific to this repo that an agent would plausibly
do and you would spend an evening undoing].
## Verification
- A task is done when: tests pass, lint passes, and the change is
demonstrated (test output, or exact steps a human can follow to see it).
- Bug fixes include a test that failed before the fix.
- When uncertain about intent, ask. A wrong guess costs more than a question.
## Agent-specific notes
[Optional. Per-tool quirks live here, not in separate diverging files.]
- Claude Code: [e.g. skills/subagents notes; CLAUDE.md points here]
- [Other tool]: [its quirks, if any]Adaptation notes:
- Starting a repo that already has a CLAUDE.md: move the content here, leave CLAUDE.md containing "Read AGENTS.md first" plus anything genuinely Claude-specific. Ten minutes, and the two-diverging-copies problem is structurally impossible.
- Large monorepos can nest AGENTS.md files: one at the root for global rules, one per package for local ones. Most projects need exactly one at the root; start there.
- This file is read by tools with different capability levels, so state the workflow rules explicitly (branch discipline, no pushes to main) rather than assuming permission systems will enforce them. The dumbest agent that reads this file is the one the rules are for.
- Update it when reality changes, in the same commit. The "Setup and commands" section is where staleness shows up first and costs the most, because every session starts there.
- The classic mistake is writing it once, at length, and never opening it again. A short file that is true beats a long file that was true in March.