Key Takeaway
CLAUDE.md is the single highest-leverage file in your entire repository when working with Claude Code. Without it, every session starts from zero and Claude must rediscover your project structure, conventions, and constraints through trial and error. A well-crafted CLAUDE.md under 150 lines eliminates this cold-start problem entirely, producing consistent output that respects your architecture decisions, coding standards, and deployment workflows from the first prompt.
Why Project Context Is Non-Negotiable
Claude Code reads your codebase, runs commands, and edits files. But without explicit project context, it makes assumptions. It might use npm when you use pnpm. It might create class components when your codebase is entirely functional. It might deploy to a staging branch when your team auto-deploys from main. Each of these mistakes costs five to fifteen minutes of correction time per session. Over a week of active use, that adds up to hours of wasted effort.
The context system solves this with a hierarchy of CLAUDE.md files that load automatically based on your working directory. Claude reads every CLAUDE.md from the repository root down to the directory you are working in, plus any in parent directories above the repo. This means you can define global rules once and override or extend them at any level of your project tree.
Think of CLAUDE.md as a new-hire onboarding document that you only write once. Every session with Claude Code is essentially a new hire who has perfect recall but zero institutional knowledge. The CLAUDE.md file provides that institutional knowledge instantly.
CLAUDE.md Structure and Rules
Keep your root CLAUDE.md under 150 lines. This is not arbitrary. Claude Code loads the file into its context window at the start of every session, and bloated files consume tokens that would be better spent on your actual task. Focus on information that changes behavior: project stack, commands, conventions, known gotchas, and architecture boundaries. Do not include tutorials, explanations of why decisions were made, or documentation that belongs in a wiki.
- 1
Project identity block
State the project name, stack, and deployment target in two to three lines. Include the package manager, framework version, and any critical infrastructure like Clerk, Stripe, or Supabase.
- 2
Commands block
List every command Claude might need: dev server, build, lint, type-check, test, database migrations, and formatting. Use the exact commands including workspace filters if you use a monorepo.
- 3
Conventions block
Define your code style rules: server components by default, import paths, font usage, Tailwind patterns, and any anti-patterns to avoid. Be specific. Say text-gray-600 for body text, never text-gray-400 on light backgrounds rather than use appropriate text colors.
- 4
Git block
Specify your branch strategy, commit message format, co-author line, and any pre-commit checks. If you auto-deploy from main, say so explicitly so Claude never creates feature branches unless asked.
- 5
Architecture block
Provide a directory tree showing the key boundaries: marketing pages, authenticated routes, API routes, shared libraries, and packages. This is the map Claude uses to decide where to put new files.
- 6
Known issues block
List active technical debt, dual systems that need consolidation, hardcoded mock data, or services in test mode. This prevents Claude from building on top of broken foundations.
Sample CLAUDE.md Template
# Project Name
## Project
Brief description. Live at [domain.com](https://domain.com).
- **Stack**: Next.js 15 + React 19 + Tailwind 4 + Clerk + Drizzle/Postgres
- **Monorepo**: Turborepo + pnpm 9
- **Deployment**: Vercel auto-deploys from `main`
## Commands
```bash
pnpm --filter web dev # Dev server (port 3000)
pnpm --filter web build # Production build
pnpm --filter web check-types # TypeScript check
pnpm --filter web lint # ESLint
pnpm format # Prettier
pnpm db:generate # Drizzle migrations
pnpm db:migrate # Run migrations
```
## Conventions
- Server components by default — only "use client" when state/effects needed
- Import UI from @org/ui/components/{name}
- Body text: text-gray-600 — NEVER use text-gray-400 on light backgrounds
- Hydration safety: Never typeof window in JSX — use useState + useEffect
## Git
- Single branch: main (auto-deploys)
- Always create NEW commits, never amend
- Run check-types before every commit
## Architecture
```
apps/web/
app/(marketing)/ # Public pages
app/(auth)/ # Auth pages
app/platform/ # Protected routes
app/api/ # API routes
lib/ # Shared libraries
components/ # Shared components
packages/
db/ # ORM schema and client
ui/ # Component library
```
## Known Issues
- Rate limiter needs consolidation (two systems)
- Dashboard stats are hardcoded mock dataUnlock the full Knowledge Base
This article continues for 22 more sections. Upgrade to Pro for full access to all 96 articles.
That's just $0.10 per article
- Full access to all blueprints, frameworks, and playbooks
- Interactive checklists with progress tracking
- Downloadable templates (.xlsx, .pptx, .docx)
- Quarterly Technology Radar updates