Your project's CLAUDE.md file is the single most underrated feature in Claude Code. It's a markdown file in your project root that acts as a permanent system prompt — every conversation Claude Code has in that project reads it automatically. No setup, no config, no plugins. Just a file.
Most people either skip it entirely or write something so vague it barely helps. That's leaving enormous value on the table. This guide covers how to write one, the CLAUDE.md best practices that matter, and real examples you can copy.
Why it matters
Without a CLAUDE.md file, every Claude Code conversation starts from zero. Claude can read your code, but it doesn't know:
- That you use Tailwind v4, not v3 (and the API changed significantly)
- That your team settled on Vitest after three months of Jest frustration
- That the database connection pool maxes at 10, so don't open connections in loops
- That every API route must go through the service layer
You end up correcting the same things across conversations. Or worse — you don't catch the mistakes until they're in production.
A good CLAUDE.md file eliminates this entire class of problem. You write the rules once. Claude follows them forever.
The anatomy of a good CLAUDE.md
After building dozens of these across different projects, a clear pattern emerges. The best CLAUDE.md files have four sections:
1. Project overview
Two to three sentences about what this project is. Not a novel — just enough context that Claude understands the domain.
# Skill Locker
E-commerce platform selling Claude Code skills. Built with Next.js 16,
Supabase auth, Stripe payments. Deployed on Vercel.
2. Tech stack and conventions
This is where you prevent the most mistakes. Be specific about versions, patterns, and choices your team has made.
## Stack
- Next.js 16 with App Router (NOT Pages Router)
- TypeScript strict mode
- Tailwind CSS v4 (uses @plugin syntax, NOT tailwind.config.js)
- Supabase for auth and database
- Stripe for payments
## Conventions
- All API routes use the service layer pattern
- Server Components by default; "use client" only when needed
- Error handling: never swallow errors silently
- Imports: use @/ path alias, never relative paths deeper than ../
3. Common gotchas
This is the section that separates a useful CLAUDE.md from a great one. Every project has traps — things that look right but break in subtle ways. Document them.
## Gotchas
- Tailwind v4 uses `@plugin` in CSS, NOT `plugins` in config
- Next.js 16 async params: `params` is a Promise, must be awaited
- Supabase auth callbacks need `createServerClient` with explicit
cookie handling — the shared `createClient()` silently swallows
cookie write failures
- Database pool limit is 10 — never open connections inside loops
These are the things that cost you hours when you forget them. With a CLAUDE.md file, you never forget them again.
4. Style and quality standards
Tell Claude what good output looks like for this project.
## Code style
- Functions over classes
- Descriptive names over comments
- Small, focused components (under 100 lines)
- Every exported function gets JSDoc
- Commit messages: conventional commits (feat:, fix:, docs:)
What NOT to put in CLAUDE.md
A few things that don't belong:
- Entire documentation. Keep it concise. If Claude needs deep reference material, point it to specific files.
- Obvious things. "Write clean code" adds nothing. Be specific or leave it out.
- Temporary notes. CLAUDE.md is for persistent project knowledge, not today's task list.
- Secrets or credentials. This file usually goes in version control. Never put API keys or passwords in it.
Real examples that work
Here's a stripped-down version of a CLAUDE.md that's been refined over several months of daily use:
# MyApp
SaaS dashboard for fitness coaches. Next.js 16, Supabase,
Tailwind v4, deployed on Vercel.
## Architecture
- App Router with route groups: (auth), (dashboard), (marketing)
- Server Components default, Client Components for interactivity
- API routes → service layer → Supabase queries
- Auth: magic link via Supabase, PKCE flow
## Rules
- NEVER use `any` type — find or create the right type
- All database queries go through /src/lib/db/ — never query
Supabase directly from components
- Images: next/image with explicit width/height, never raw <img>
- Forms: use server actions, not API routes
## Gotchas
- `cookies()` is async in Next.js 16 — must await it
- Supabase RLS is ON — every query runs as the authenticated user
- Tailwind v4: `@theme` block replaces `theme.extend` in config
- The Stripe webhook secret is different per environment
Notice what this does: it's short enough to scan in 30 seconds, specific enough to prevent real mistakes, and structured enough that Claude can reference the right section for the right task.
CLAUDE.md vs skills vs hooks
People sometimes ask how CLAUDE.md relates to Claude Code skills and hooks. They're complementary — three layers that do different jobs:
- CLAUDE.md is project-specific guidance. It encodes conventions, architecture, and gotchas for one codebase.
- Skills are task-specific guidance. They encode how to approach a type of work — writing tests, reviewing code, creating documentation — across any project.
- Hooks are deterministic enforcement. They run shell commands automatically on events (auto-format every edit, block changes to protected files) — not judgement, rules.
CLAUDE.md says "this project uses Vitest." A testing skill says "here's how to write excellent tests, what to cover, what patterns to follow." A hook guarantees the test runner fires after every change. Together, Claude writes Vitest tests that follow your testing philosophy and your project conventions — and the harness checks they actually pass.
CLAUDE.md best practices (the short version)
If you take nothing else from this guide, these are the CLAUDE.md best practices that separate a file that helps from one that's ignored:
- Keep it under ~200 lines. Scannable beats comprehensive. Long files dilute the signal.
- Be specific, not aspirational. "We use Vitest, not Jest" helps. "Write good tests" doesn't.
- Document gotchas, not the obvious. The traps that cost hours are the highest-value lines in the file.
- State versions explicitly. "Tailwind v4 (uses
@pluginsyntax)" prevents a whole class of wrong assumptions. - One concern per line. Terse, declarative rules outperform prose paragraphs.
- Never put secrets in it. It's usually committed to git — treat it as public project docs.
- Iterate it. Add a rule every time Claude gets something wrong for lack of context.
That checklist is the whole game. Everything above is just the detailed version of these seven points.
The iteration trick
Don't try to write the perfect CLAUDE.md on day one. Start with the basics — stack, major conventions, one or two gotchas you know about. Then, every time Claude does something wrong because it didn't know a project convention, add that convention to CLAUDE.md.
After a week, you'll have a file that captures the things that actually matter. After a month, it'll feel like Claude has been working on your project for years.
FAQ
Where does CLAUDE.md go?
In your project root, alongside package.json. Claude Code detects it automatically.
Can I have multiple CLAUDE.md files?
You can have one per directory. Claude loads all of them from the root to the current directory. Use subdirectory CLAUDE.md files for component-specific or module-specific rules.
Does it slow Claude Code down?
No. It's loaded once at conversation start. A reasonable CLAUDE.md (under 200 lines) has no perceptible impact.
Should I commit it to git?
Yes — with the caveat that it should never contain secrets. CLAUDE.md is project documentation. Your whole team benefits from it.
How long should it be?
Under 200 lines is ideal. If it's longer, you're probably including things that belong in separate reference files. Keep CLAUDE.md sharp and scannable.
Can Claude Code update CLAUDE.md itself?
Yes. You can ask Claude to add a new convention or gotcha to the file. Some teams make it a habit: "Good catch, add that to CLAUDE.md so we don't hit it again."
What are CLAUDE.md best practices?
Keep it under ~200 lines, be specific rather than aspirational, document gotchas not the obvious, state tool versions explicitly, use one terse rule per line, never include secrets, and iterate it whenever Claude gets something wrong for lack of context.
What's the difference between CLAUDE.md and AGENTS.md?
CLAUDE.md is Claude Code's project instruction file. AGENTS.md is a more general, tool-agnostic agent-instructions convention some projects adopt so multiple AI tools read the same file. They serve the same purpose; the principles in this guide apply to both. If you use both, keep one as the source of truth and have the other reference it to avoid drift.
Start now, refine later
The best CLAUDE.md is the one that exists. Even five lines of project context and conventions will make your next Claude Code conversation noticeably better. You can always improve it later. New to Claude Code entirely? The complete guide covers the basics first, then come back here when you're ready to make Claude consistent across a project.
If you want to go further, our CLAUDE.md Generator skill creates a structured CLAUDE.md from your codebase automatically — it reads your project, detects your stack, and produces a first draft you can refine.