One rule per line (or separate with semicolons).
One directory per line, e.g. "src/app — routes".
Paths and areas the agent must never touch without asking.
# my-app
Customer dashboard built with Next.js App Router, Postgres, and Stripe.
**Stack:** Next.js / React · Node / TypeScript
## Commands
```bash
npm install # install dependencies
npm run dev # start the dev server
npm test # run the test suite
npm run lint # lint
npx tsc --noEmit # typecheck
```
Run lint and typecheck before finishing any task — CI runs the same
checks, and a red pipeline costs a full review cycle.
## Conventions
- Prefer server components
- Tailwind for styling
- No default exports
When a case is not covered here, match the surrounding code —
consistency beats personal preference.
## Project map
- `src/app` — routes
- `src/lib` — domain logic
- `src/components` — shared UI
New code goes where its neighbors live. Ask before adding a new
top-level directory.
## Boundaries
Hard limits. Stop and ask a human before crossing any of these.
- Never edit src/generated/**
- Don't touch billing code without asking
## Testing
- Behavior changes ship with a test that fails without the change.
- Run `npm test` before finishing; fix any failure you caused.
- Never delete, skip, or weaken a failing test to get to green.
## Git workflow
- Branch from `main`: `feat/<short-name>` or `fix/<short-name>`.
- Keep commits small and imperative ("Add invoice export", not "changes").
- One concern per PR — leave unrelated refactors out of the diff.
## When unsure
If a task is ambiguous, crosses a boundary above, or needs a new
dependency or schema change, stop and ask instead of guessing. A short
question is cheaper than a wrong PR.
What AGENTS.md and CLAUDE.md actually are
A context file is the standing brief a coding agent reads before it touches your repo. CLAUDE.md is Claude Code's convention: the CLI loads it automatically at the start of every session, from the repo root and from directories it works in. AGENTS.md is the newer cross-agent convention — one file, adopted by Codex CLI, Cursor, and a growing list of tools, so you don't maintain a separate rules file per agent.
Either way, the job is the same: replace the twenty things you'd otherwise repeat in every prompt — how to run tests, which patterns the codebase uses, what never to touch — with one committed file. It is the cheapest piece of infrastructure in an agentic development setup, and one of the highest-leverage.
| File | Read by | Best when |
|---|---|---|
| CLAUDE.md | Claude Code, at session start | You work primarily in Claude Code |
| AGENTS.md | Codex CLI, Cursor, and other adopting tools | You mix tools — keep one source of truth |
| Both | CLAUDE.md contains a single line: @AGENTS.md | One file, every agent reads it |
What belongs in one — and what doesn't
The test for every line: would the agent do something wrong without it? If yes, it stays. If the agent could discover it by reading code, or it's only true this sprint, it goes. Four kinds of content pass that test reliably:
Commands
Conventions
Project map
Boundaries
What doesn't belong: long architecture prose (agents read code faster than essays), anything already stale, aspirational rules nobody follows, and — ever — secrets or credentials. The file is committed and fed verbatim into model context; treat it as public. Per-task detail doesn't belong either: that lives in a spec, which is what the agent spec builder is for.
The #1 mistake: write it once, let it rot
Most context files are written in an enthusiastic afternoon and never touched again. Six months later the test command has changed, the "new" directory structure is old, and the agent is confidently following instructions that are wrong. A stale context file is worse than none — the agent has no way to know which lines to distrust.
The fix is to treat the file like code. When a PR changes a command, a convention, or the directory layout, the same PR updates AGENTS.md — and reviewers check for it, the way they check for updated tests. Some teams add a checklist item; the discipline is the same one that makes spec-driven development work: written artifacts only pay off while they're true.
Per-directory files and imports
One root file doesn't scale to a monorepo. The convention that works: keep the root file short and global — commands, universal conventions, boundaries — and add a small CLAUDE.md or AGENTS.md inside each package with rules that only apply there. Claude Code reads nested files as it works in those directories, so an agent editing packages/api sees the API rules without paying for the frontend's.
CLAUDE.md also supports explicit imports: a line like @docs/testing.md pulls another file into context. That's how the one-line @AGENTS.md bridge works, and it keeps any single file under the ~120-line budget. If terms like context window or MCP are fuzzy, the AI glossary covers the vocabulary these files keep bumping into.