Introduction
CLAUDE.md is a special configuration file that Claude Code reads at the start of every session. It lets you encode project-specific knowledge, coding conventions, and team preferences directly into your repository — so Claude always has context without you repeating yourself.
This guide covers everything: what CLAUDE.md is, how Claude processes it, how to structure it for maximum effectiveness, and patterns that work across different project types.
What Claude Reads and When
When you start a Claude Code session, Claude automatically reads CLAUDE.md files in a specific order:
- Your global user-level rules (
~/.claude/CLAUDE.md) - The project root CLAUDE.md
- Any CLAUDE.md files in subdirectories Claude navigates into
This hierarchical loading means you can have global defaults (code style, preferred tools) and project-specific overrides (database schema, API conventions).
Anatomy of a Great CLAUDE.md
A well-structured CLAUDE.md typically has these sections:
# Project Overview Brief description of what this project does and who it's for. ## Tech Stack - Runtime: Node.js 20, TypeScript 5.4 strict mode - Framework: Next.js 15 App Router - Database: PostgreSQL via Prisma ORM - Styling: Tailwind CSS v4 - Auth: NextAuth.js v5 ## Code Style - Use named exports everywhere (no default exports in lib/) - Prefer functional components with explicit return types - Use `const` assertions for config objects - Error handling: always use try/catch in API routes ## File Structure - app/ — Next.js App Router pages and API routes - components/ — Reusable UI components - lib/ — Utilities, DB client, helpers - prisma/ — Schema and migrations ## Commands - `npm run dev` — Start dev server - `npm run build` — Production build - `npx prisma db push` — Sync schema ## Important Constraints - NEVER commit .env files - NEVER use `any` type in TypeScript - Always run `npm run build` before submitting PRs
The Five Pillars of Effective Rules
1. Context over commands. Rather than telling Claude "do X", explain why: "We use named exports because our barrel files rely on static analysis."
2. Specificity over vagueness. "Use TypeScript strict mode" is less useful than "Enable strict mode, noUncheckedIndexedAccess, and exactOptionalPropertyTypes in tsconfig."
3. Constraints over permissions. List what NOT to do. Claude can infer many good practices but will always defer to explicit constraints.
4. Living documentation. Update CLAUDE.md when you make architectural decisions. Treat it like your team's onboarding guide.
5. Project-specific over generic. Avoid restating general programming best practices — Claude already knows them. Focus on your team's unique choices.
Token Budget Awareness
Every byte of CLAUDE.md consumes context tokens. Claude has a finite context window, and a 10,000-word CLAUDE.md leaves less room for your actual code and conversation.
Target under 500 lines. Use bullet points over paragraphs. Reference other files for long specifications:
## API Conventions
See docs/api-conventions.md for the full API design guide.
Key points:
- Always validate with Zod at the boundary
- Return { data, error } shape from all endpoints
- Use HTTP 422 for validation errorsTeam and Repository Setup
Commit CLAUDE.md to version control. Every team member and CI environment then gets the same Claude behavior automatically.
Consider a CLAUDE.team.md for sensitive information (internal tooling, private APIs) that you gitignore, and a public CLAUDE.md for everything else.
Iterating on Your Rules
Start minimal. Add a rule only when you notice Claude making the same mistake twice or when you catch yourself repeating the same correction. Good rules are born from friction, not anticipation.
Review your CLAUDE.md every month. Remove rules that no longer apply. Update rules that have evolved. A stale CLAUDE.md is worse than none — it teaches Claude outdated patterns.