CLAUDE.md Template and 10 Real Examples

The template

# Project: <name>

<One sentence: what this project is and who it's for.>

## Commands
- Install: <npm install>
- Dev server: <npm run dev>
- Test: <npm test>          (run before saying a task is done)
- Lint/format: <npm run lint>
- Build: <npm run build>

## Stack
- <Framework + version>, <language>, <database>, <hosting>

## Project layout
- src/app/        routes and pages
- src/components/ shared UI
- src/lib/        helpers, API clients

## Conventions
- <e.g. TypeScript strict; no "any">
- <e.g. Server components by default; "use client" only when needed>
- <e.g. Tests live next to the file as *.test.ts>

## Rules
- Never commit secrets or edit .env files
- Ask before adding a new dependency
- Keep changes focused; don't reformat unrelated files

## Context
- <Anything Claude can't discover: business rules, gotchas, links>

Where CLAUDE.md files go

• ./CLAUDE.md or ./.claude/CLAUDE.md — the project file your team shares through git
• ./CLAUDE.local.md — your private notes for this project; add it to .gitignore
• ~/.claude/CLAUDE.md — personal preferences for every project
• Subfolders — a CLAUDE.md in a folder loads when Claude works on files there

Files are combined, not overridden. Claude Code loads every CLAUDE.md from your working directory up to the root at launch, and subfolder files on demand.

If your repository already has an AGENTS.md for other tools and no CLAUDE.md, recent versions of Claude Code read AGENTS.md instead. To use both, add a line containing @AGENTS.md to your CLAUDE.md — that imports it.

Rules for an effective CLAUDE.md

• Stay under ~200 lines — Anthropic's docs note longer files use more context and are followed less reliably
• Be specific: "run npm test before finishing" beats "make sure things work"
• Remove contradictions — if two rules conflict, Claude may follow either
• Use @path imports to organise, e.g. @docs/architecture.md (imports can nest up to four levels)
• Put path-specific rules in .claude/rules/ so they only load for matching files
• Move multi-step procedures into skills; they load only when needed

10 short examples

Each of these is the part that's unique to that kind of project — combine it with the template above.

• 1. Next.js app: "App Router only. Server components by default. Fetch data in server components, never in useEffect. Run npm run build before finishing — it catches type errors."
• 2. Python API (FastAPI): "Use uv for dependencies. Type hints everywhere. Run pytest -q and ruff check . before finishing. Pydantic models live in app/schemas/."
• 3. Monorepo: "Packages in packages/*. Run commands from the root with pnpm --filter <pkg>. Never import across packages except through their public index.ts."
• 4. Mobile (React Native): "Test on iOS and Android. Use the theme tokens in src/theme; no hard-coded colours. Keep native module changes to a minimum."
• 5. Marketing site: "Every page needs a unique title under 60 chars, a description under 155, one h1 and a canonical URL on the www domain."
• 6. Data science: "Notebooks are for exploration only; reusable code goes in src/. Never commit data files. Set random seeds for reproducibility."
• 7. Open-source library: "Public API is in src/index.ts — changes need a changelog entry. Keep zero runtime dependencies."
• 8. Legacy codebase: "Don't refactor code you weren't asked to touch. Match the existing style even where it's old-fashioned. Add a test before fixing any bug."
• 9. Infrastructure (Terraform): "Never run apply. Run terraform fmt and plan, and show the plan. Tag every resource with owner and env."
• 10. Content/blog repo: "Write in American English, short paragraphs, no jargon. Every post needs a meta description and at least two internal links."

Generate a first draft with /init

Run /init inside Claude Code and it analyses your codebase and writes a starting CLAUDE.md with build commands, test instructions and conventions it discovers. If a file already exists, it suggests improvements instead of overwriting it. Use /memory to open and edit your CLAUDE.md files later.

One CLAUDE.md for many agents

CLAUDE.md is shared by every subagent too (unless an agent opts out), so a well-written file improves your whole team of agents at once. That's the idea behind claudeagents: describe your stack once in CLAUDE.md and all 120+ agents follow it. You can also draft one with our free CLAUDE.md generator.