Context Management Best Practices

These are the patterns that make Claude Code's context management tools actually work for you across a project, from the first CLAUDE.md to a long-running, multi-session codebase.

How to Use This List

• Treat the CLAUDE.md practices as foundational - get those right first, since everything else builds on a solid project memory file.
• Revisit the @mentions and session-hygiene practices as habits, not one-time setup.
• The nesting and auditing practices matter more as a project grows - don't force them onto a small, single-stack repo.
• Come back to this list whenever a new team member joins or a project's structure changes meaningfully.

A - CLAUDE.md Foundations

• Start with /init rather than a blank file. Let Claude Code draft the structural first pass (stack, folder layout, existing commands) so you're only writing what it couldn't infer.
• Write rules as concrete, checkable statements. "Use zod to validate all external input" is followable; "write clean code" is not - specificity is what makes a rule actually get obeyed.
• Give hard rules their own section. Isolate genuine non-negotiables ("never commit to main") from general conventions so they're impossible to miss.
• Point rules at a real example file when possible. A convention paired with "see src/repositories/OrderRepository.ts" is easier to apply correctly than the same rule stated in the abstract.
• Back critical rules with enforcement outside the model too. CLAUDE.md is context the agent reasons over, not a permissions system - pair genuinely critical rules with a CI check or branch protection.
• Keep it as short as it can be while staying specific. CLAUDE.md loads on every session; padding costs context budget repeatedly without adding real guidance.

B - Keeping CLAUDE.md Current

• Re-run /init when the project's structure has shifted meaningfully. It updates the file based on current state rather than duplicating it, giving you a fresh structural baseline to review.
• Diff CLAUDE.md after any regeneration or major edit. Confirm hand-written hard rules and team conventions survived the update before moving on.
• Treat CLAUDE.md like a living document, not a one-time setup step. A stale rule is trusted as current context by default, so an inaccurate file can actively mislead the agent.
• Commit CLAUDE.md changes through the same review process as code. Since it's a normal file in the repo, changes to it should get the same scrutiny as any other shared convention.

C - Using @mentions Well

• Mention files you actually know are relevant, not files you might need. Each mention pulls the full file's content into context - reflexive mentions are a common, avoidable source of bloat.
• Prefer prose over a mention when only part of a large file matters. Describing the specific function or section usually costs less context than mentioning the whole file.
• Chain a small number of targeted mentions for genuinely multi-file tasks. A few precise mentions beat one vague, codebase-wide description when you already know which files are involved.
• Let Claude Code search when you genuinely don't know where something lives. Mentions are for known targets; exploratory or "find where X happens" tasks are what search is for.

D - Managing the Context Window

• Reach for /compact when a task is still active but the conversation has grown long. It preserves the gist while freeing up space, so you can keep momentum on in-progress work.
• Reach for /clear when switching to something unrelated. Dragging even a summarized version of a finished or unrelated task forward just adds noise to the next one.
• Compact proactively rather than waiting until things feel critical. A /compact run earlier in a long session tends to produce a cleaner, more useful summary than one run under pressure.
• Treat /clear as a routine habit between tasks, not just a recovery move. Clearing when you finish a task, the way you'd close a browser tab, keeps sessions focused by default.
• Watch for the usual bloat sources as a session runs. Large files read in full, a growing list of @mentions, and verbose tool output are the recurring culprits worth noticing before they pile up.

E - Scaling to Larger Projects

• Move to nested CLAUDE.md files once areas genuinely diverge. A monorepo, a clear backend/frontend split, or a legacy exception area are signs a root-only file is starting to strain.
• Let nested files assume the root file's context rather than restating it. A nested CLAUDE.md should only add what's specific to its own scope, not re-explain project-wide conventions already covered above it.
• State exceptions to root rules explicitly, not implicitly. If a subtree genuinely breaks a project-wide convention, say so directly in its nested file, along with why - don't leave it for the agent to notice on its own.
• Audit periodically on long-running or heavily reused projects. Check for large files read repeatedly, stale or oversized CLAUDE.md content, and mention habits that have crept up over time, even without an obvious symptom.
• Don't nest or split prematurely. A bloated single file's first fix is usually trimming it - nesting is for genuinely scope-specific content, not just length.

FAQs

Related

• What CLAUDE.md Actually Does - the foundational concept behind section A and B.
• Writing a CLAUDE.md File That Actually Gets Followed - the full pattern behind concrete, checkable rules.
• Auditing What's Eating Your Claude Code Context Window - the detailed audit workflow behind section E.
• Nested CLAUDE.md Files and How Scope Inheritance Works - the full mechanics behind section E's nesting guidance.
• Why /compact and /clear Exist - the reasoning behind section D's reset guidance.

Stack versions: Written against the Claude model lineup current as of ~June 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (the default), and Claude Haiku 4.5. Model names, pricing, and product features move quickly - verify current specifics at platform.claude.com/docs before relying on them.