CLAUDE.md & Context Management Best Practices (2026 Guide)

Two teams adopt Claude Code. Six months later, one has an agent that knows the build commands, respects the repo's conventions, and never touches the legacy directory. The other re-explains the same three things in every session and wonders why the agent keeps running the wrong test command. The difference is rarely the model. It is whether anyone wrote a good CLAUDE.md.

CLAUDE.md is Claude Code's persistent memory: a Markdown file the harness loads into context at session start, automatically, every time. It anchors the Context Management & Reliability domain (15% of the CCA-F exam) and leaks into the Configuration domain (20%) too. This guide covers the hierarchy, what belongs in the file, and the context-window principles behind all of it.

The Memory Hierarchy

Claude Code assembles persistent context from several locations, and the exam expects you to know what lives where:

More specific scopes layer on top of broader ones, and project files are the ones your teammates inherit when they clone the repo. The file supports imports: an @path/to/file reference pulls another file into memory, so a large project can split conventions into composable pieces instead of one monolith.

What Belongs in CLAUDE.md (and What Does Not)

The file is loaded into every session, which makes it precious and expensive at the same time: everything in it consumes context before the first user message. The discipline the exam rewards:

Belongs in CLAUDE.md:

• Commands the agent cannot guess: build, test, lint, deploy invocations with their flags
• Architecture facts that are true for months: where things live, what talks to what
• Hard conventions: "database migrations are applied manually," "never edit generated/"
• Repository-specific gotchas that would otherwise burn a session to rediscover

Does not belong:

• Long procedures used occasionally: that is a skill, loaded on demand instead of every session
• Anything enforceable: "always run the formatter" belongs in a hook, because prose compliance is probabilistic
• Prompt-of-the-day experiments and session-specific context
• Documentation that already exists elsewhere: link it, don't duplicate it

The heuristic that resolves most exam questions: CLAUDE.md is for what the agent must know every session; skills are for what it must know some sessions; hooks are for what must happen regardless of what it knows.

Writing style matters more than people expect. The file is instructions, not an essay. Short declarative bullets outperform paragraphs; specific beats general ("run npm run test:unit, the bare npm test runs the slow e2e suite" beats "run appropriate tests"). Review it periodically: a CLAUDE.md that has drifted from reality is worse than none, because the agent trusts it.

The Context Window: Why All of This Matters

Every Claude Code session runs inside a finite context window shared by the system prompt, CLAUDE.md, the conversation, file contents, and tool results. Three consequences drive both real-world practice and exam questions:

Context is a budget. Every token of memory-file boilerplate is a token unavailable for actual work. Bloated CLAUDE.md files degrade the very sessions they are meant to help. Lean memory plus on-demand skills is the architecture that scales.

Signal degrades as the window fills. Long sessions accumulate file dumps and tool output. Claude Code compacts the conversation when it approaches limits (summarizing older turns), and the PreCompact hook exists precisely so critical state can be preserved before summarization. Durable state should live in files, commits, and logs rather than conversation history: conversation is lossy, the filesystem is not.

Isolation beats accumulation. When a job requires reading fifty files, the answer is not a bigger window but a subagent whose context absorbs the noise and returns a conclusion. Context management and orchestration are the same discipline at two scales.

Reliability Patterns Built on These Foundations

The Context Management & Reliability domain pairs the window mechanics with operational judgment:

• Checkpoint long work. Commits, files, and structured logs survive compaction and crashes; the transcript does not.
• Re-anchor after compaction. Critical invariants ("we are migrating to v2 API, never write v1 calls") belong in CLAUDE.md, which is reloaded fresh, rather than only in early conversation turns that compaction may summarize away.
• Design for resumability. A task that can resume from artifacts (a progress file, a TODO list on disk) tolerates interruption; one whose state lives only in the conversation cannot.

Worked Example: A CLAUDE.md That Earns Its Tokens

# Project: acme-billing

Commands

• Build: pnpm build (tsc + vite)
• Unit tests: pnpm test:unit (bare pnpm test runs slow e2e, avoid)
• Lint: pnpm lint --fix

Architecture

• src/core/ pure domain logic, no IO
• src/adapters/ all external services live here
• Invoices are IMMUTABLE after issue; corrections are new credit notes

Boundaries

• Never edit src/generated/ (regenerated by pnpm codegen)
• DB migrations are applied manually in production, never auto-run

@docs/conventions/typescript.md

Thirty lines, every one of which prevents a real failure or a wasted exploration. That density is the standard to aim for, in production and in exam answers alike.

How This Shows Up on the Exam

• Where does a convention every teammate should inherit belong? (Project CLAUDE.md, committed to the repo.)
• A 400-line CLAUDE.md full of deploy runbooks slows every session. What is the fix? (Move runbooks to skills; keep memory lean.)
• A critical instruction from early in a long session stops being followed. Why, and what prevents it? (Compaction summarized it away; persistent invariants belong in CLAUDE.md.)
• What survives a session crash? (Artifacts on disk; nothing conversational.)

The Claude Code course drills this in Level 3 (Context & Memory) with graded exercises, and Preporato's CCA-F practice tests cover the domain across 390 explained questions, with the flashcard deck carrying the hierarchy tables for spaced review.

Sources:

• Claude Code Documentation: Memory
• Anthropic Academy
• Anthropic: Effective Context Engineering for AI Agents

Last updated: July 10, 2026