CLAUDE.md Examples: Production Templates for Claude Code

What Is CLAUDE.md?

CLAUDE.md is a Markdown file that acts as persistent memory for Claude Code. Every time you start a session, Claude reads this file before doing anything else. It is the single highest-leverage configuration you can set up because it shapes every response, every code suggestion, and every decision Claude makes during your session.

There are three levels where CLAUDE.md files can live:

• ~/.claude/CLAUDE.md - Your global identity file. Loads in every session, everywhere. Put your name, universal preferences, and communication style here.
• ~/.claude/projects/{path}/CLAUDE.md - Project-specific overrides. Loads when you work in a matching directory. Put per-project context here without cluttering your global file.
• ./CLAUDE.md - Repository-level config. Lives in the repo root, shared with your team via git. Put architecture decisions, conventions, and deploy processes here.

The files stack. Global loads first, then project-level, then repo-level. Later files can override earlier ones. This hierarchy is what makes CLAUDE.md powerful for both solo developers and teams.

Basic CLAUDE.md Template (Beginner)

If you are just getting started with Claude Code, start here. This covers the essentials in under 20 lines. You can always add more later.

# About Me
Name: Sarah Chen
Role: Frontend developer at a fintech startup

# Preferences
- Use TypeScript for all new code
- Prefer functional components with React hooks
- Keep explanations short and direct
- Ask before making destructive changes (deleting files, force pushing)

# Current Project
Building a customer dashboard with React, Vite, and Tailwind CSS.
API lives at /api and returns JSON. Auth is handled by Clerk.

# Communication
- Be direct, skip the preamble
- If something is a bad idea, say so
- Explain tradeoffs when making architecture decisions

That is it. Twenty lines and Claude already knows your stack, your style, and what you are working on. The difference between a session with this file and one without it is immediate. Claude stops asking what language you prefer and starts writing code that fits your project.

Developer CLAUDE.md Template (Intermediate)

For developers who run daily sessions and want Claude to operate more like a pair programmer than an assistant.

# Identity
Name: Marcus Rivera
Role: Full-stack engineer, Series B SaaS company
Stack: TypeScript, Next.js 15, Postgres, Prisma, Vercel

# Execution Rules
- Always run `npm run build` before claiming code works (never just `tsc`)
- Write tests first with Vitest, then implement (TDD)
- Use existing patterns in the codebase before inventing new ones
- Prefer small, focused commits with descriptive messages
- Never push directly to main. Always use feature branches.

# Code Style
- Strict TypeScript: no `any`, no `as` casts unless unavoidable
- Zod for runtime validation at API boundaries
- Server components by default, client components only when needed
- Error handling: fail loudly in dev, gracefully in prod
- No barrel exports (index.ts re-exports)

# Project Context
Monorepo with apps/web (Next.js) and packages/shared (domain logic).
Database: Supabase Postgres. Auth: Clerk. Payments: Stripe.
CI runs on GitHub Actions. Deploy to Vercel on merge to main.

# Testing
- `npm test` runs Vitest in watch mode
- `npm run test:ci` runs the full suite with coverage
- Minimum 80% coverage on new code
- Integration tests for API routes, unit tests for utilities

# Communication
- Skip tutorials for things I do daily (React, TypeScript, git)
- Teach me when using tools I am less familiar with (Prisma migrations, Stripe webhooks)
- Name the tradeoff, not just the choice
- When you catch a potential bug, flag it immediately

The key difference here is the Execution Rules section. This is where you encode your engineering standards so Claude follows them without being reminded. "Always run npm run build" prevents the classic mistake where Claude claims code compiles when it actually has type errors. "Write tests first" enforces TDD at the tool level.

Power User CLAUDE.md Template (Advanced)

For developers running long, multi-step sessions where context management and workflow enforcement matter.

# Identity
Name: Priya Kapoor
Role: Staff engineer, platform team
Stack: Go, gRPC, Postgres, Redis, Kubernetes, Terraform

# Skill Enforcement
Before you write any implementation code, follow this sequence:
1. Read existing code in the affected area first
2. Write failing tests that define the expected behavior
3. Implement the minimum code to pass the tests
4. Refactor only after tests are green

Never skip step 2 for "simple" changes. Simple changes break things too.

# Context Management
- At 50% context usage: start delegating verbose exploration to subagents
- At 70%: compact the conversation, preserve file paths and decisions
- At 85%: hand off with a structured summary before context degrades
- Never explore large directories in the main context window

# Execution Rules
- Run `go test ./...` before claiming anything works
- Run `golangci-lint run` before committing
- Use table-driven tests with descriptive subtest names
- All errors must be wrapped with context: fmt.Errorf("doThing: %w", err)
- No global state. Inject dependencies via constructors.
- Feature flags for anything that touches production traffic

# Git Workflow
- Branch naming: type/description (feat/add-rate-limiter, fix/null-pointer-cache)
- Commit messages: imperative mood, under 72 chars, body explains why
- Always rebase feature branches on main before opening a PR
- Never force push to shared branches

# Projects
- rate-limiter: Token bucket implementation for the API gateway
- migration-tool: Zero-downtime schema migration runner
- observability: OpenTelemetry instrumentation across services

# Communication
- I know Go, distributed systems, and Kubernetes well. Skip basics.
- Teach me about areas I am learning: eBPF, Rust FFI, WASM runtimes
- When I am wrong about something, say so directly
- Use diagrams (ASCII or Mermaid) for architecture discussions

The Skill Enforcement section is where this template earns its weight. Instead of hoping Claude follows good practices, you define the workflow as a numbered sequence that Claude treats as mandatory. The Context Management section prevents the silent quality degradation that happens when you burn through your context window without noticing.

Team CLAUDE.md Template (Shared Repository)

This template lives in your repo root at ./CLAUDE.md and gets committed to version control. Every developer on the team gets the same baseline when they use Claude Code in this project.

# Project: Acme Billing Platform

## Architecture
- Monorepo: apps/api (Express), apps/web (React), packages/shared
- Database: PostgreSQL 16 on RDS, migrations via Drizzle
- Queue: SQS for async jobs (invoice generation, webhook delivery)
- Auth: JWT issued by our auth service, validated via middleware

## Conventions
- API routes: /api/v1/{resource} with RESTful verbs
- Shared types live in packages/shared/src/types/
- All money values stored as integers (cents), never floats
- Dates stored as UTC timestamps, displayed in user's timezone
- Environment variables: SCREAMING_SNAKE_CASE, validated at startup

## Commands
- `npm run dev` - Start all services locally
- `npm run build` - Production build
- `npm test` - Run all tests
- `npm run lint` - ESLint + Prettier check
- `npm run db:migrate` - Run pending migrations
- `npm run db:seed` - Seed local database

## Deploy Process
1. Create PR against `staging` branch
2. CI runs tests, lint, build, and type-check
3. Get at least one approval from a team member
4. Merge to staging - auto-deploys to staging environment
5. Verify on staging, then create PR from staging to main
6. Merge to main - auto-deploys to production

## Known Gotchas
- The invoice PDF generator uses Puppeteer and needs Chrome installed
- Webhook retry logic has a 5-second delay between attempts
- The shared package must be built before running the API locally
- Never delete a migration file. Always create a new one to undo changes.

Notice there is no personal identity section. This is a team file. Personal preferences go in each developer's ~/.claude/CLAUDE.md. The repo-level file documents what everyone needs to know: how the system works, what the commands are, and where the landmines are buried.

Tips for Writing an Effective CLAUDE.md

Keep it under 100 lines

CLAUDE.md consumes tokens from your context window every session. A 200-line file eats into the space you need for actual work. Be concise. If you need extensive documentation, link to it instead of inlining it.

Be specific, not aspirational

Bad: "Write clean, well-tested code." Claude already tries to do this. It tells Claude nothing.

Good: "Use Vitest for tests. Run npm run test:ci before claiming code works. Minimum 80% coverage on new files." This is actionable. Claude can follow it.

Update it as your project evolves

A CLAUDE.md that references a database you migrated away from six months ago is worse than no CLAUDE.md. Treat it like documentation that ships with your code. When the stack changes, update the file.

Use the hierarchy

Do not jam everything into one file. Your name and communication preferences go in the global file. Project-specific stack details go in the project file. Team conventions go in the repo file. Claude reads all of them and merges the context.

Common CLAUDE.md Mistakes

• Too long. Over 150 lines and you are burning context that should go toward actual work. Move reference docs to separate files and point to them.
• Too vague. "Be helpful" and "write good code" are noise. Claude ignores instructions it cannot act on. Every line should be something Claude can concretely follow.
• Never updating it. An outdated CLAUDE.md actively misleads Claude. If you switched from Jest to Vitest but your file still says Jest, Claude will write Jest tests. Stale config is worse than no config.
• Putting secrets in it. The repo-level CLAUDE.md gets committed to git. Never put API keys, tokens, or passwords in it. Use environment variables and reference them by name.
• Duplicating across levels. If your global file says "use TypeScript," do not repeat it in every project file. The hierarchy exists to prevent duplication. Use it.

The best CLAUDE.md is one you actually maintain. Start with the basic template, use it for a week, and notice what you keep repeating to Claude. Every time you say the same thing twice, add it to the file. That is how you build a config that actually makes you faster.