Writing CLAUDE.md

New to CLAUDE.md? — Start with the official CLAUDE.md guide for the basics. This page is the opinionated blueprint for making yours great.

CLAUDE.md is the highest-leverage configuration surface for Claude Code. It’s loaded into every conversation, so every line must earn its place. For how it fits into the broader instruction hierarchy alongside skills, agents, and hooks, see Context Distribution.

What CLAUDE.md Does

When you launch Claude Code in a directory, it walks the directory tree collecting CLAUDE.md files. More specific locations take precedence:

Priority	Location	Scope
1 (highest)	`/etc/claude-code/CLAUDE.md`	Organization-wide
2	`~/.claude/CLAUDE.md`	Personal, all projects
3	`./CLAUDE.md`	Project root
4	`./CLAUDE.local.md`	Personal project overrides (gitignored)
5	Parent directories	Inherited in monorepos
6	Subdirectories	Module-specific, on demand

The 200-Line Budget

The system prompt already contains ~50 instructions. CLAUDE.md adds to that load. Frontier models follow approximately 150-200 instructions with reasonable consistency before quality degrades. Keep yours concise.

What Goes In (and What Doesn’t)

Include
Exclude

One-line project overview with tech stack
Build/test/lint commands (Claude uses these verbatim)
Brief architecture/directory map
Coding conventions Claude can’t infer from existing code
Critical warnings about gotchas
Pointers to detailed docs using @imports

The Pointer Pattern

CLAUDE.md points; it doesn’t explain. One line per concern — what to do and where to read more. Good:

- **Auth flow:** See `@docs/authentication.md` before touching auth code

Bad: A 30-line section explaining five auth rules with examples inline.

CLAUDE.md vs. Hooks

CLAUDE.md relies on LLM compliance — it’s advisory. For things that must always happen (formatting, linting, blocking .env commits), use hooks. Hooks execute as code.

Example

# ShopFront
Next.js 14 e-commerce app. App Router, Stripe payments, Prisma ORM.

## Commands
- `npm run dev`: Dev server (port 3000)
- `npm run test`: Jest tests
- `npm run lint`: ESLint check

## Architecture
- `/app`: App Router pages and layouts
- `/components/ui`: Reusable UI components
- `/lib`: Utilities and shared logic
- `/prisma`: Schema and migrations

## Conventions
- TypeScript strict mode, no `any` types
- Named exports only, never default exports

## Important
- NEVER commit .env files
- Stripe webhook must validate signatures

## Reference Documents
### Auth Flow — `@docs/authentication.md`
**Read when:** Touching auth-related code

No frameworks, no tables of code patterns, no examples of implementation details. Those live in skills or reference docs.

Verifying Your Context

After editing CLAUDE.md, use the /context command inside Claude Code to see exactly what’s loaded into the conversation. This shows every CLAUDE.md file, @import, and skill that Claude can see — so you can confirm your changes landed and nothing is missing or duplicated.

Next Steps

Compose your skills stack — layer domain knowledge on top of CLAUDE.md
Set up hooks — enforce what CLAUDE.md can only suggest
Wire up MCP — connect Claude to your external tools

Level Up

Mindset

Setup

Quick Reference

What CLAUDE.md Does

The 200-Line Budget

What Goes In (and What Doesn’t)

The Pointer Pattern

CLAUDE.md vs. Hooks

Example

Verifying Your Context

Next Steps

​What CLAUDE.md Does

​The 200-Line Budget

​What Goes In (and What Doesn’t)

​The Pointer Pattern

​CLAUDE.md vs. Hooks

​Example

​Verifying Your Context

​Next Steps

What CLAUDE.md Does

The 200-Line Budget

What Goes In (and What Doesn’t)

The Pointer Pattern

CLAUDE.md vs. Hooks

Example

Verifying Your Context

Next Steps