CLAUDE.md Best Practices: What to Write, What to Automate, What to Skip

CLAUDE.md is the single most underrated file in any Claude Code project. It loads automatically at the start of every session, injecting persistent instructions directly into the agent's system prompt. Write it well and Claude Code behaves like a senior developer who already knows your codebase. Write it poorly — or not at all — and every session starts from zero.

Most developers either skip CLAUDE.md entirely or stuff it with everything they can think of. Both approaches waste tokens. The optimal CLAUDE.md is specific, concise, and focused on things Claude Code can't figure out on its own. Here's exactly what belongs in it, what should be automated instead, and what you should leave out.

What CLAUDE.md Actually Does

When you create a `.claude/CLAUDE.md` file (or `CLAUDE.md` in your project root), Claude Code reads it at the start of every session and treats its contents as persistent instructions. Think of it as a configuration file for agent behavior — not documentation for humans, but directives for the AI.

Key mechanics:

• Loaded every session. CLAUDE.md content is injected into the system prompt before your first message. The agent sees it before anything else.
• Counts against your context window. Every word in CLAUDE.md consumes input tokens every session. A 2,000-word CLAUDE.md costs roughly 2,500 tokens per session — $0.0075 on Sonnet per session, which adds up across 10-20 daily sessions.
• Hierarchical. You can have CLAUDE.md files at the home level (`~/.claude/CLAUDE.md`), project level (`.claude/CLAUDE.md`), and subdirectory level. All matching files are merged.
• Shapes behavior, not knowledge. CLAUDE.md is most effective for "how to work" instructions, not "what the codebase contains" information. The agent can discover codebase facts by reading code — it can't discover your team's conventions without being told.

Understanding these mechanics is essential. They determine what belongs in CLAUDE.md and what doesn't.

What to Write: The High-Value Instructions

The best CLAUDE.md content is information that Claude Code cannot discover by reading your code but needs to follow consistently. These fall into four categories.

Project Architecture Overview

Give Claude Code the 30-second mental model of your project. Not a file listing — a conceptual map.

```markdown

Architecture

• Monorepo: apps/web (Next.js 14), apps/api (Express), packages/shared
• Data layer: Prisma ORM with PostgreSQL, Redis for caching
• Auth: NextAuth.js with JWT strategy, sessions in Redis
• Deployment: Vercel (web), Railway (api), Neon (db)

```

This takes 50 words but saves the agent from reading 10-15 files to piece together the same understanding. It's the highest-ROI content you can put in CLAUDE.md — dense architectural context that prevents exploration overhead.

Coding Conventions

Every team has conventions that aren't enforced by linters. These are exactly what CLAUDE.md is for:

```markdown

Conventions

• Use named exports, never default exports
• Error handling: always use Result<T, E> pattern from packages/shared/result.ts
• API routes return { data, error, meta } shape — never raw values
• Tests: colocate with source files as *.test.ts, use vitest
• Commits: conventional commits format (feat:, fix:, chore:)

```

Without these instructions, Claude Code will generate valid code that doesn't match your patterns. It'll use default exports because that's common in the ecosystem. It'll return raw objects from API routes. It'll put tests in a `__tests__` directory. All technically correct, all wrong for your project.

Testing Requirements

Be specific about how your project handles testing:

```markdown

Testing

• Run tests: `npm run test` (vitest)
• Always run affected tests before committing: `npm run test -- --related`
• Integration tests require: `docker compose up -d` (Postgres + Redis)
• Minimum coverage for new code: 80% line coverage
• Mock external services using msw, never jest.mock for HTTP calls

```

This prevents Claude Code from writing tests that don't run, using the wrong test runner, or skipping integration test setup.

Deployment and Environment Notes

Include anything about your deployment that affects code decisions:

```markdown

Deployment

• Environment variables: never hardcode, always use env.ts schema
• Database migrations: create with `npx prisma migrate dev --name <name>`
• Preview deployments on Vercel for every PR — test there before merging
• Production secrets are in 1Password, never committed

```

These four categories — architecture, conventions, testing, deployment — typically total 150-300 words. That's roughly 200-400 tokens per session. Dense, high-value, and impossible for Claude Code to discover on its own.

What to Automate: Let Tools Handle the Dynamic Stuff

Some information belongs in the agent's context but shouldn't be manually maintained in CLAUDE.md. It changes too often, grows too large, or can be computed automatically.

File References and Codebase Structure

Developers often put file trees or key file lists in CLAUDE.md:

```markdown

DON'T do this

Key Files

• src/auth/login.ts — handles user login
• src/auth/session.ts — session management
• src/db/prisma.ts — database client
• src/db/migrations/ — migration files

... (50 more lines)

```

This is a maintenance nightmare. Every time you add, rename, or delete a file, CLAUDE.md is outdated. And it consumes hundreds of tokens per session to convey information that a context engine can serve dynamically.

A tool like vexp indexes your entire codebase structure into a dependency graph. When Claude Code needs to know which files handle authentication, vexp serves exactly those files — current, complete, and ranked by relevance. No manual file list required. The graph updates automatically as your code changes.

Dependency Information

Listing dependencies, their versions, and what they're used for is another common CLAUDE.md anti-pattern. This information lives in `package.json`, `requirements.txt`, or `Cargo.toml` — the agent can read it. And a dependency graph maps not just what's installed but how each dependency is used across your codebase, which is far more useful than a static list.

Symbol Relationships

"Function X calls Function Y which depends on Service Z" — this type of information is exactly what a code graph captures automatically. Writing it manually in CLAUDE.md means it's outdated the moment someone refactors a call chain.

The Automation Rule

If the information can be derived from your code, don't put it in CLAUDE.md. Either let Claude Code discover it (for simple cases) or let a context engine serve it (for structural relationships). CLAUDE.md should contain only human-originated instructions that don't exist anywhere in the code.

What to Skip: Things That Waste Tokens

Some content actively hurts when placed in CLAUDE.md. It wastes context window space, confuses the agent, or creates contradictions.

Verbose File Listings

A full directory tree of your project consumes 500-2,000 tokens and provides almost no behavioral guidance. Claude Code can run `ls` if it needs to see your file structure. Don't pre-load this into every session.

Obvious Conventions

Don't tell Claude Code things it already knows:

```markdown

DON'T include these

• Use TypeScript for .ts files
• Follow JavaScript best practices
• Write clean, readable code
• Use meaningful variable names

```

These instructions consume tokens without changing behavior. Claude Code already writes TypeScript in .ts files and uses meaningful variable names by default. Only include conventions that are specific to your project and differ from community defaults.

Frequently Changing Information

If a piece of information changes weekly or more often, it doesn't belong in a file you rarely update:

```markdown

DON'T include

• Current sprint: Sprint 47 (ends March 15)
• Active feature flags: ENABLE_NEW_CHECKOUT, BETA_ANALYTICS
• Team members: Alice (frontend), Bob (backend), Carol (infra)

```

This information goes stale quickly and creates confusion when Claude Code follows outdated instructions. If the agent needs sprint context, provide it in your prompt. If it needs feature flag states, let it read the configuration file.

Contradictory Instructions

The most dangerous CLAUDE.md mistake is contradicting yourself:

```markdown

Style

• Always use async/await for asynchronous code

API Routes

• Use .then() chains for route handlers to keep them readable

```

Claude Code will follow one instruction and violate the other, unpredictably. Review your CLAUDE.md for contradictions, especially between general rules and specific section rules.

Common CLAUDE.md Mistakes

Too Long

The most common mistake. Developers treat CLAUDE.md like project documentation and write 2,000-5,000 word files. At 5,000 words, you're consuming ~6,500 tokens per session on instructions alone. At 15 sessions/day on Sonnet, that's nearly $0.30/day — about $6/month — just for CLAUDE.md loading.

Target: 150-400 words. If your CLAUDE.md exceeds 500 words, you're almost certainly including content that should be automated or removed.

Too Detailed on Code

CLAUDE.md should tell the agent how to write code, not what code exists. "Use the Result pattern for error handling" is a behavioral instruction. "The Result type is defined in packages/shared/result.ts with Ok and Err variants" is code documentation — the agent can discover this by reading the file.

No Maintenance Schedule

CLAUDE.md files rot. Conventions change, file structures evolve, tools get replaced. Set a calendar reminder to review CLAUDE.md monthly. Read every line and ask: "Is this still true? Is this still useful? Can this be automated?"

Duplicating Linter Rules

If your project has ESLint, Prettier, or similar tools configured, don't repeat their rules in CLAUDE.md. Claude Code runs your linters when making changes. Writing "use 2-space indentation" in CLAUDE.md when Prettier already enforces it is redundant token spending.

The CLAUDE.md + Context Engine Combination

The optimal setup uses CLAUDE.md for human-originated behavioral instructions and a context engine for code-derived structural information. They're complementary, not competing.

CLAUDE.md handles:

• Architectural decisions and their rationale
• Coding conventions not enforced by tooling
• Testing requirements and workflows
• Deployment processes and constraints
• Team-specific practices

A context engine like vexp handles:

• Codebase structure and file relationships
• Symbol dependencies and call graphs
• Which files are relevant to a given task
• Import chains and module boundaries
• Change coupling (files that typically change together)

Together, they give Claude Code both behavioral guidance (from CLAUDE.md) and structural awareness (from the context engine) without wasting tokens on either. The CLAUDE.md stays lean at 200-400 words. The context engine serves dynamic, always-current structural context on demand.

This combination typically reduces total per-session token usage by 60-70% compared to a verbose CLAUDE.md with no context engine — while delivering better agent behavior because the instructions are clearer and the structural context is more complete.

The Template

Here's a CLAUDE.md template that captures high-value instructions in under 300 words:

```markdown

Architecture

[2-3 sentences: what the project is, major components, key technology choices]

Conventions

[5-8 bullet points: coding patterns specific to this project]

Testing

[3-5 bullet points: test runner, test location, coverage requirements, setup steps]

Deployment

[3-4 bullet points: environment handling, migration process, deployment targets]

Context

[1-2 sentences: point to your context engine or explain how the agent should discover codebase structure]

```

Fill in the brackets with your project's specifics. Delete any section that doesn't apply. Resist the urge to add more. A concise CLAUDE.md that Claude Code actually follows is worth infinitely more than a comprehensive one it ignores.