The complete guide to CLAUDE.md in 2026

Agentic Atlas · July 2026 · 8 min read

Every team using Claude Code has a CLAUDE.md. Almost none of them have a good one. Most were generated once with /init, committed, and never touched again - which means the AI writing half your code is working from a stale, generic description of your project.

This guide covers what we've learned building and auditing these files for client teams: what belongs in a CLAUDE.md, what doesn't, how to structure context across a real codebase, and the mistakes we find in nearly every audit.

What CLAUDE.md is actually for

CLAUDE.md is loaded into the model's context at the start of every session. It is not documentation for humans - it is standing instructions for an extremely capable contractor who starts fresh every morning with no memory of yesterday. Everything in it should change the model's behavior. If a line wouldn't change what Claude does, it's wasting context budget.

Three categories earn their place:

Constraints the code can't show. "Payments logic lives in services/billing, never in controllers." "We support IE11 - no optional chaining in the legacy bundle."
Commands and workflows. How to run tests, build, lint, deploy to staging. Exact commands, not prose descriptions.
Decisions that were expensive to make. "We use polling, not websockets, because of proxy X - do not suggest websockets."

What to leave out

Anything the model can discover by reading the code - file listings, dependency inventories, restated function signatures. They go stale and burn context.
Generic best practices - "write clean code", "add tests". The model already knows. Only include standards where your team deviates from defaults or needs enforcement.
Long prose. Bullet points, imperative voice. A good CLAUDE.md is under 60 lines per level.

Structure it in layers

In 2026, context is hierarchical. Use it:

~/.claude/CLAUDE.md        # personal: your style, your shortcuts
repo/CLAUDE.md             # project: architecture, commands, constraints
repo/services/billing/CLAUDE.md   # module: domain rules for payments
repo/.claude/rules/        # shared team rules, versioned in git

The root file states what's true everywhere. Module-level files carry domain rules that only matter when the model works in that directory. This keeps every session's context lean and relevant.

The five mistakes we find in every audit

The museum piece. Generated at adoption, never updated. Treat CLAUDE.md like code: it changes in the same PR that changes the behavior it describes.
The novel. 400 lines of project history and aspirations. The model deprioritizes bloated context; your one critical security rule drowns on line 312.
No security section. If the file doesn't say "never log PII" or "all new endpoints need rate limiting", the model won't reliably enforce it. Guardrails must be written down.
One file for a monorepo. The frontend team's rules pollute the backend team's context and vice versa. Split by module.
Rules with no teeth. The strongest setups pair CLAUDE.md rules with hooks that enforce them - a lint hook that blocks commits, a permission policy that gates dangerous commands. Instructions plus enforcement beats instructions alone.

A minimal template that works

# Project: [name]

## Commands
- Test: npm test (single file: npm test -- path/to/file)
- Build: npm run build
- Lint: npm run lint (runs in pre-commit hook)

## Architecture rules
- [The 3–7 rules that are always true and expensive to violate]

## Security
- [Non-negotiables: secrets, PII, input validation]

## Conventions
- [Only where you deviate from ecosystem defaults]

## Gotchas
- [The things that waste an hour if you don't know them]

How do you know it's working?

Measure it. Before and after a config change, track: how often reviewers reject AI-assisted PRs, how often developers override or re-prompt, and whether the model respects your architecture boundaries unprompted. A context file that isn't measured is a hope, not a system.

Want to know where your setup stands? Take our free 2-minute readiness scorecard - instant score, personalized roadmap.