CLAUDE.md template for Claude Code (copy-paste)
A short, tested CLAUDE.md you can drop into any repo: exact commands, project layout, how the agent should work, and a definition of done that stops "all tests pass" when they don't. The same text works as AGENTS.md for Cursor, Codex, and other coding agents.
Free below. Want it pre-built for a whole project? App Builder Agent Pack ($19) or all 5 premium packs for $29.
The template
Raw markdown: /guides/claude-md-template.md. Replace every {{placeholder}}, delete lines that don't apply, and save it as CLAUDE.md in your repo root.
# CLAUDE.md
## Project
- What this is: {{one sentence, e.g. "Next.js 15 app for booking dog walks"}}
- Stack: {{language, framework, database, hosting}}
- Package manager: {{npm / pnpm / bun / uv}}. Never switch it.
## Commands
- Install: {{pnpm install}}
- Dev server: {{pnpm dev}}
- Tests: {{pnpm test}} (single file: {{pnpm test path/to/file}})
- Lint and types: {{pnpm lint && pnpm typecheck}}
- Build: {{pnpm build}}
## Layout
- {{src/app/}}: routes and pages
- {{src/lib/}}: shared logic, no UI
- {{tests/}}: tests mirror the src/ tree
- Do not edit: {{generated/, migrations already applied, vendor/}}
## How to work
1. For anything bigger than a one-line fix, write a short plan first and wait for my OK.
2. Make one small change at a time, then run the tests and lint before moving on.
3. Match the existing style in the file you are editing. Don't reformat unrelated code.
4. Don't add a new dependency without asking. Prefer what's already installed.
5. If something is unclear, ask one question instead of guessing.
## Code rules
- {{TypeScript strict, no `any`}}
- {{Errors: throw typed errors, never swallow them}}
- {{Secrets come from env vars; never hard-code keys or commit .env}}
## Definition of done
Before you say a task is done, list each claim (tests pass, bug fixed, feature works)
and mark it VERIFIED with the exact command and its real output, or FAILED, or NOT RUN.
Never say "all tests pass" unless you ran them in this session and quote the result.
Don't skip, delete, or weaken a test to make it pass.
## Gotchas
- {{e.g. "The dev DB resets on every `pnpm dev`; seed with `pnpm seed`"}}
- {{e.g. "Auth is mocked in tests via tests/setup.ts"}}
Why each section is there
- Project and Commands: the agent can't guess your test or build command. Wrong commands mean it either skips verification or invents output.
- Layout: tells it where things belong and what it must never edit, so it stops creating duplicate helpers and touching generated files.
- How to work: plan first, small steps, check after each one. This is the single biggest quality jump for vibe coding.
- Definition of done: coding agents often write their final summary from what they meant to do. Requiring quoted evidence for each claim catches that. The full rule plus an auditor prompt is in our free Agent Done-Check pack.
- Gotchas: the project-specific traps that cost you an hour once. Write them down so they never cost you again.
Tips
- Keep the commands section exact and copy-pasteable. Agents follow commands literally, and a wrong test command is the most common reason they 'verify' nothing.
- Write rules as instructions, not descriptions: 'Run pnpm test before saying done' beats 'We value testing'.
- When the agent makes the same mistake twice, add one line to Gotchas. That's how the file earns its keep.
- Check it into git so your whole team, and every agent, gets the same rules.
- Review it monthly and delete stale lines. Outdated rules are worse than none.
FAQ
Where does CLAUDE.md go?
Put it in the root of your repository so it is loaded for every session in that project. Claude Code also reads a personal file at ~/.claude/CLAUDE.md for preferences you want in every project, and CLAUDE.md files in subfolders for rules that only apply there.
How long should CLAUDE.md be?
Short. It is loaded into context every session, so every line costs tokens and attention. Aim for one screen: commands, layout, how to work, and a definition of done. Move long docs into separate files and point to them.
What's the difference between CLAUDE.md and AGENTS.md?
CLAUDE.md is read by Claude Code. AGENTS.md is an open convention read by many other coding agents, such as OpenAI Codex, Cursor, and others. The content can be the same. To avoid two files drifting apart, keep the real rules in AGENTS.md and make CLAUDE.md import it with a line containing @AGENTS.md, since Claude Code reads CLAUDE.md but not AGENTS.md on its own. Add any Claude-only notes below that import.
How do I stop the agent repeating the same mistake?
When it gets something wrong, ask it which one-line rule in CLAUDE.md would have prevented the mistake, and paste that line into Gotchas. A fix in chat only lasts for that session; a line in the file lasts for every session.
Can Claude Code write CLAUDE.md for me?
Yes. Running /init in Claude Code scans the project and drafts one. Use it as a starting point, then add the parts it can't guess: how you want it to work, what not to touch, and your definition of done.
Does this template work in Cursor?
Yes. Paste the same text into AGENTS.md, which Cursor reads, or into a Cursor rule file in .cursor/rules/ with alwaysApply: true in its frontmatter.
Skip the setup: App Builder Agent Pack
A finished CLAUDE.md and AGENTS.md plus six Cursor rules files (.mdc) with coding standards and a verify-before-done agreement already in them, and a plan-then-build workflow: spec, step-by-step plan, one-step-at-a-time builds with checks, self-review, and a handoff note. Plain Markdown you own, works with Claude Code, Cursor, and other agents.
Get the App Builder pack — $19 Or all 5 for $29