How to Write a CLAUDE.md File That Actually Works

Most CLAUDE.md files fall into one of two extremes: completely empty, or bloated with hundreds of lines that Claude never reads. After months of using Claude Code to build TurboDocx — across several repos spanning TypeScript backends, React frontends, a documentation site, open-source packages, and multiple SDKs — we've learned exactly what makes Claude Code productive and what wastes context tokens.

This guide distills the official Anthropic recommendations, insights from the developer community, and our hands-on experience into actionable best practices. Whether you're configuring Claude Code for a solo project or an enterprise monorepo with API integrations, you'll walk away knowing exactly what to put in your CLAUDE.md — and what to leave out.

Anthropic's official best practices documentation is clear: your CLAUDE.md should be concise. The recommended target is under 200 lines. Some teams go as low as 60 lines. The absolute ceiling is roughly 300 lines before Claude starts losing signal in the noise.

Why? CLAUDE.md is loaded into context every single session. Every line consumes context window budget that could be spent on your actual code. Think of it like onboarding a new developer — you wouldn't hand them a 50-page document on their first day. You'd give them the essentials and point them to detailed docs when needed.

The most common mistake is treating CLAUDE.md like documentation. It's not — it's a context injection file. Here's the definitive breakdown:

Include

Exclude

The most effective CLAUDE.md files follow a clear information hierarchy. We call it the WHY/WHAT/HOW pattern — it mirrors how you'd brief a senior engineer joining your team:

# Project Name (WHAT — 1-2 lines)
SaaS document automation platform. TypeScript monorepo:
backend (Express), frontend (React/Gatsby), docs (Docusaurus).

## Commands (HOW — essential commands only)
```bash
npm run dev       # Start dev server
npm run test      # Run Jest tests
npm run build     # Production build
```

## Project Structure (WHAT — directory map)
```
src/routes/       # API endpoints
src/models/       # DB models (Objection.js)
src/handlers/     # Business logic
```

## Conventions (HOW — only non-default patterns)
- Use Zustand for state management, never Redux
- All API responses use `{ success, data, error }` shape
- Database migrations go in src/database/migrations/

## Reference Documents (progressive disclosure)
### API Architecture — `@docs/api-architecture.md`
**Read when:** Adding or modifying API endpoints

Notice the pattern: context first, then commands, then structure, then conventions, then references. Each section is scannable — Claude can extract exactly what it needs without reading every word. This is the same approach we use for our TurboDocx API & SDK projects where Claude Code helps us build and maintain the API layer.

The single most powerful CLAUDE.md technique is progressive disclosure — keeping task-specific knowledge out of CLAUDE.md and loading it only when needed. Claude Code gives you several mechanisms for this:

## Reference Documents
### Content SEO SOP — `@docs/CONTENT-SEO-SOP.md`
**Read when:** Creating or editing ANY content page
Covers metadata requirements, JSON-LD schemas, internal linking minimums

### API Architecture — `@docs/api-architecture.md`
**Read when:** Adding or modifying API endpoints
Defines route patterns, request/response shapes, auth middleware

This pattern tells Claude when to read each document and what it contains, without loading everything into context every session. At TurboDocx, our root CLAUDE.md references six detailed SOPs — content creation, SEO architecture, deployment, and more — but Claude only loads them when the task requires it. It's the same principle behind how we manage our open-source projects: keep the surface area small, go deep only when needed.

If you're building an application that integrates with external APIs — whether it's adding document signing via JavaScript, connecting to payment processors, or consuming AI services — your CLAUDE.md needs specific API context:

## API Integrations
- TurboDocx API: REST, Bearer token auth, base URL in TURBODOCX_API_URL
  - SDK: @turbodocx/sdk (TypeScript) — always prefer SDK over raw fetch
  - Docs: https://docs.turbodocx.com/API
  - Webhooks: POST to /webhooks/turbodocx, verify X-Signature header

## Error Handling Conventions
- All external API calls wrapped in try/catch
- Retry transient errors (429, 503) with exponential backoff
- Log API errors to structured logger, never swallow silently
- Return standardized error shape: { code, message, retryable }

The key insight: document the conventions around API usage, not the API itself. Claude can read API docs — what it can't infer is your team's patterns for authentication, error handling, retry logic, and webhook processing. For a deeper dive into API integration patterns, see our API integration best practices guide.

If you're working with the TurboDocx API for document generation, your CLAUDE.md might reference the SDK package, the base URL environment variable, and your webhook verification pattern. The full API reference stays in external docs — CLAUDE.md just points Claude in the right direction.

Claude Code loads CLAUDE.md files from multiple locations with a clear hierarchy. Understanding this lets you layer context appropriately:

In a monorepo, put shared conventions in the root CLAUDE.md and service-specific context in child directories. For example, our TurboDocx backend has its own CLAUDE.md covering database migrations and API patterns, while the frontend directory has one covering component conventions and state management.

A CLAUDE.md file isn't set-and-forget. Treat it like code: review it when things go wrong, prune regularly, and commit changes to version control.

• Run /insights weekly to surface patterns from your sessions and add rules
• If Claude repeatedly ignores a rule, the file is too long — prune it
• If Claude asks questions already answered in CLAUDE.md, the phrasing is ambiguous — rewrite it
• Use IMPORTANT or YOU MUST prefixes for critical rules to improve adherence
• When Claude makes a mistake, tell it to update the CLAUDE.md so it doesn't repeat the error

That last point is the most underrated trick. When Claude gets something wrong — uses the wrong import path, breaks a naming convention, misunderstands your project structure — don't just fix it and move on. Tell Claude to add the correction to CLAUDE.md itself. Over time, your CLAUDE.md becomes a living record of your codebase's quirks and preferences, written by the same tool that consumes it. Claude effectively becomes self-aware of your patterns, your style, and the traps it fell into before. The file evolves from a static brief into a feedback loop.