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 dataMonorepo CLAUDE.md Strategy
In a monorepo, use the file hierarchy to your advantage. The root CLAUDE.md covers project-wide concerns: stack, monorepo commands, git conventions, and deployment. Each workspace or app directory gets its own CLAUDE.md that covers domain-specific context: key files, API route patterns, component conventions, and environment variables for that workspace. Claude loads all ancestors automatically, so the workspace file only needs to add what is new or different.
This hierarchy also works for nested directories. If your web app has a platform directory with complex tool pages, a CLAUDE.md inside app/platform/ can describe the tool page pattern, the Zustand store structure, and the server action conventions. Claude will load the root CLAUDE.md, the apps/web CLAUDE.md, and the platform CLAUDE.md in order, building up a complete picture of the context.
Use the /init command to have Claude Code generate an initial CLAUDE.md for your project. It analyzes your codebase and produces a solid first draft. Review it, trim it to under 150 lines, and add any conventions or known issues it missed.
Settings and Permissions
The .claude/settings.json file controls what Claude Code is allowed to do without asking for confirmation. By default, Claude asks permission before running any shell command or editing files. This is safe but slow. The permissions system lets you pre-approve common operations like running your build, lint, and test commands, while keeping dangerous operations behind a confirmation prompt.
There are three scopes for settings files. The project-level file at .claude/settings.json is checked into your repository and shared with the team. The user-level file at ~/.claude/settings.json applies to all your projects. The local-level file at .claude/settings.local.json is gitignored and holds personal overrides. When the same permission appears in multiple files, the most restrictive interpretation wins for deny rules.
Permissions Configuration Template
{
"permissions": {
"allow": [
"Bash(npm run *)",
"Bash(pnpm *)",
"Bash(npx *)",
"Bash(git status)",
"Bash(git diff *)",
"Bash(git log *)",
"Bash(git add *)",
"Bash(git commit *)",
"Bash(git checkout *)",
"Bash(git branch *)",
"Read(*)",
"Write(src/**)",
"Write(apps/**)",
"Write(packages/**)",
"Edit(src/**)",
"Edit(apps/**)",
"Edit(packages/**)"
],
"deny": [
"Read(.env*)",
"Write(.env*)",
"Edit(.env*)",
"Bash(git push *)",
"Bash(rm -rf *)",
"Bash(curl *)",
"Bash(wget *)"
]
}
}Always deny access to .env files and any file containing secrets, API keys, or credentials. Claude Code does not need to read these files to do its work, and accidentally including secret values in its context creates a data exposure risk. Also deny destructive commands like rm -rf and network commands like curl or wget that could exfiltrate data.
MCP Server Configuration
Model Context Protocol servers extend Claude Code with external capabilities. They run as sidecar processes that Claude can call as tools during a session. The .mcp.json file in your project root defines which servers to start and how to connect to them. When Claude Code launches, it reads this file and starts each configured server automatically.
The two most impactful MCP servers for most teams are Context7 and Playwright. Context7 gives Claude access to up-to-date documentation for any library, eliminating hallucinated API calls against outdated or invented function signatures. Playwright gives Claude the ability to control a real browser for end-to-end testing, visual verification, and debugging UI issues that are invisible from code alone.
MCP Configuration Template
{
"mcpServers": {
"context7": {
"command": "npx",
"args": ["-y", "@upstash/context7-mcp@latest"]
},
"playwright": {
"command": "npx",
"args": ["-y", "@anthropic-ai/playwright-mcp"]
},
"filesystem": {
"command": "npx",
"args": [
"-y",
"@anthropic-ai/fs-mcp",
"--read-only",
"/path/to/allowed/directory"
]
}
}
}Other useful MCP servers include the filesystem server for controlled access to directories outside your project, the GitHub server for PR and issue management, and the PostgreSQL server for direct database queries. Keep the list lean. Each running server consumes memory and adds startup latency. Start with Context7 for documentation and Playwright for browser testing, then add others only when you have a clear use case.
Setup Quality Checklist
The Impact of Proper Setup
Before
No CLAUDE.md, default permissions, no MCP servers. Every session starts with Claude exploring the codebase, guessing conventions, asking for permission on every command, and hallucinating library APIs. Average ramp-up time: 5 to 10 minutes per session. Frequent mistakes require manual correction.
After
Complete CLAUDE.md, tuned permissions, Context7 and Playwright configured. Claude starts working immediately with full project knowledge, runs commands without interruption, and references accurate documentation. Ramp-up time: under 30 seconds. Output matches team conventions from the first edit.
80%
Reduction in session ramp-up time
From 5-10 minutes of exploration down to under 30 seconds with a well-structured CLAUDE.md
3x
Fewer convention violations
Explicit rules in CLAUDE.md eliminate guesswork about coding standards and patterns
60%
Fewer permission interruptions
Pre-approved commands in settings.json let Claude execute without stopping to ask
Zero
Hallucinated API calls
Context7 MCP server provides real-time documentation so Claude uses actual function signatures
Treat your CLAUDE.md like production code. Review it in pull requests, update it when conventions change, and prune it when sections become irrelevant. A stale CLAUDE.md is worse than no CLAUDE.md because Claude will follow outdated instructions with full confidence.