When Claude Code enters a project, the first thing it reads is CLAUDE.md. This is the single file that determines whether the agent understands your project — or guesses.
Think of it as the difference between dropping a new developer into your codebase with zero context versus giving them a 10-minute walkthrough first. The walkthrough doesn't need to cover everything — just enough to prevent the obvious mistakes.
The file sits at the root of your repository. It's plain Markdown. There's no special syntax, no frontmatter, no magic. Claude reads it before looking at any code.
The five sections that matter
After setting up dozens of projects, I've landed on this structure. Most projects don't need more.
Commands
Dev, build, test, lint. The agent calls these every session.
Structure
Top-level layout. What each directory does. Not a full file tree.
Boundaries
What can import what. Server vs client. Prevents 80% of mistakes.
Anti-patterns
What the agent should never do. Every rule learned the hard way.
Where new code goes
Decision table: "If you're writing X, put it in Y." Two columns, no ambiguity.
A real example
From a production monorepo. Notice what's here — and what's not.
# CLAUDE.md
## Commands
pnpm dev # Start dev server on :3000
pnpm build # Production build
pnpm lint # ESLint across all packages
pnpm test:e2e # Playwright E2E tests
## Structure
apps/web/ # Next.js app
packages/db/ # Supabase client + types
packages/ui/ # Shared components
packages/api/ # TRPC routers
## Boundaries
- packages/ NEVER imports from apps/
- @jd/db has zero internal deps
- Use @jd/db/server for server, @jd/db/browser for client
## Anti-Patterns
- Never import @jd/db/server in client components
- Never call AI providers directly — use sendWithFallback()
- Never modify database.types.ts manually
No React tutorial. No Supabase explainer. Only what Claude can't figure out from reading the code.
That five-section structure is not something I invented. It appears consistently across well-optimized setups. The most battle-tested open-source Claude Code configurations — the ones used in production by teams running dozens of agents — include example CLAUDE.md files for different stacks: SaaS Next.js, Go microservices, Django APIs. Every one of them follows the same five-section pattern. The specific rules change for each stack, but the shape is the same. That is not a coincidence — it is the minimal set of information an agent needs to avoid mistakes.
The /init shortcut
Claude Code has a built-in command: /init.
It scans your project and generates a CLAUDE.md automatically. It's a decent starting point —
but it's not the finished product.
The generated file typically includes too much (framework descriptions, generic patterns) and too little (your specific anti-patterns, the mistakes you've already made). Use it as scaffolding, then cut it down.
The goal is to get under 200 lines. If your CLAUDE.md is longer than that, the agent spends context budget reading instructions instead of doing work. Every line has a cost.