# CLAUDE.md template for Claude Code (copy-paste)

> Free, short CLAUDE.md template with commands, layout, working rules, and a definition of done. Also works as AGENTS.md for Cursor, Codex and other coding agents.

Source: https://agentpromptsatoz.com/guides/claude-md-template/ · License: free to use and adapt · Publisher: Agent Prompts A to Z

## The template

````markdown
# 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"}}
````

## 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.

## Go further (premium)

[App Builder Agent Pack](https://payhip.com/b/EuRgw) ($19): finished CLAUDE.md, AGENTS.md and six Cursor rules files with a plan-then-build workflow. Or [all 5 premium packs](https://payhip.com/b/J8eUb) for $29.