How to Write a CLAUDE.md That Actually Works

A CLAUDE.md file is the single highest-leverage thing you can add to a project that uses Claude Code. It transforms Claude from a general-purpose AI into a teammate who understands your stack, follows your conventions, and respects your architectural decisions.

We analyzed 30 real CLAUDE.md files from production repositories -- Vercel, Pydantic, Cloudflare, Anthropic, Supabase, and others. Here is what we found.

What the Best Files Share

Every effective CLAUDE.md we studied shares five properties.

They are specific, not aspirational. The Vercel AI SDK file does not say "write clean code." It says "functions max 30 lines, max 3 parameters, guard clauses first." Specificity produces consistent output. Vague instructions produce inconsistent output. They document what Claude cannot infer. Claude can read your package.json and infer your stack. It cannot infer that your team uses a specific error handling pattern, that your API responses follow a particular envelope format, or that certain directories are off-limits. Focus your CLAUDE.md on the delta between "reasonable defaults" and "your specific conventions." They lead with architecture. Seven of the ten best files start with a directory tree and layer rules. Architecture violations are the most expensive errors Claude can make because they propagate. Getting the architecture section right prevents cascading mistakes. They use examples over prose. The MCP TypeScript SDK file uses 5-10 line code snippets to show each pattern. One code example communicates more than a paragraph of description. When in doubt, show the pattern. They stay under 300 lines. The sweet spot is 80-200 lines. The HumanLayer file proves you can be effective at 60 lines. The Vercel AI SDK proves you can be thorough at 300. Beyond 300, you are adding noise.

The Essential Sections

1. Stack Declaration

Start with an explicit list. Be specific about versions.

## Stack
Node.js 20 LTS with TypeScript 5.3 (strict mode)
Fastify v4 for HTTP
Prisma 5 with PostgreSQL 15
Vitest for testing
pnpm for package management

"TypeScript" is less useful than "TypeScript 5.3 strict mode." The version tells Claude which features and APIs are available.

2. Architecture

This is the most important section. Define your project structure and the rules that govern it.

src/
  routes/     -> HTTP handlers (parse, delegate, respond)
  services/   -> Business logic orchestration
  core/       -> Pure domain logic (zero external imports)
  adapters/   -> All I/O (database, Redis, external APIs)
  types/      -> Shared type definitions

Rules:
core/ has zero external imports
routes/ never import from adapters/ directly
No circular imports between any modules

The rules matter more than the directory listing. Claude follows explicit rules consistently.

3. Code Conventions

Be prescriptive. Bad: "Handle errors properly." Good: "Services throw typed errors (NotFoundError, ValidationError). Routes catch and map to HTTP status codes. Never swallow errors. Always add context on rethrow."

4. Testing Patterns

Naming conventions, assertion style, mocking boundaries, and coverage targets.

5. Git Conventions

Commit format, PR size expectations, branch naming. This prevents Claude from creating commits that do not match your project's history.

The Hierarchy System

Claude Code reads CLAUDE.md files hierarchically. Understanding this changes how you structure them.

Root CLAUDE.md applies to the entire repository. Put shared conventions here: commit format, language-wide style rules, architecture overview. Package/directory CLAUDE.md files override or extend the root for specific contexts. The Cloudflare workers-sdk pioneered this "pointer pattern" -- the root file establishes shared rules and directs Claude to package-level files. The nearest CLAUDE.md wins for conflicts. If the root says "use Jest" but a package-level file says "use Vitest," Claude uses Vitest in that package.

Common Mistakes

Too vague. "Follow best practices" tells Claude nothing. Every project thinks it follows best practices. Too long. A 2000-line CLAUDE.md creates noise. If you need that much documentation, your project may need better docs in general, not a longer CLAUDE.md. Contradictory rules. "No abstractions until the third case" combined with "create a shared utility for every repeated pattern" confuses Claude. Review for consistency. Aspirational rather than actual. If your codebase does not follow the conventions in CLAUDE.md, Claude produces code that clashes with existing patterns. Describe what is, or commit to making the codebase match. Missing architecture rules. A directory tree without layer rules is decorative. Tell Claude what can import what, where side effects live, and which modules should be pure.

Templates by Project Type

Solo project (60-100 lines): Stack, architecture, conventions, testing, git. The HumanLayer model. Team project (150-250 lines): Add error handling patterns, API conventions, review process, deployment notes. The TypeScript Fullstack model. Monorepo (80 lines root + 50-150 per package): Root covers shared conventions and package map. Per-package files cover specific guidance. The Cloudflare model. Open source library (120-180 lines): Add API pattern examples, extension points, contribution workflow, release process. The MCP SDK model. Content project (80-120 lines): Lead with voice and style. Minimize code guidance. The overreacted.io model.

The Meta-Principle

A great CLAUDE.md answers one question: "What does a competent engineer need to know to contribute to this project on day one?"

If you write it with that framing, it will serve both Claude and future human engineers equally well. That is the best test -- would you give this to a new hire? If it reads like instructions for a machine, rewrite it as instructions for a person.