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
/initrather 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
zodto 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
/initwhen 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
/compactwhen 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
/clearwhen 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
/compactrun earlier in a long session tends to produce a cleaner, more useful summary than one run under pressure. - Treat
/clearas 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
Which of these practices matters most to get right first?
Writing CLAUDE.md with concrete, checkable rules rather than vague generalities. Nearly everything else in this list (mentions, resets, nesting) works better once the project's baseline memory is specific and accurate.
Do I need to nest CLAUDE.md files for every project?
No. Nesting earns its keep once a codebase has genuinely distinct areas - a small, single-stack project usually does fine with a well-written root file alone.
Should I run /compact or /clear more often?
Neither is inherently "more often" - they fit different situations. /compact for an in-progress task in a long session, /clear for switching to something unrelated. Building the habit of choosing correctly matters more than favoring one.
What's the most common context management mistake?
Reflexively @mentioning files "just in case" rather than because a task genuinely needs them. It's an easy habit to fall into and a straightforward one to catch once you're aware of it.
How do I know when a CLAUDE.md rule is too vague?
If you can't picture Claude Code checking its own output against the rule, it's probably too vague. "Write clean code" fails that test; "use zod to validate all external input" passes it.
Is it ever okay to skip auditing context bloat?
For short, one-off sessions, yes - the audit is most valuable on long-running or frequently reused projects where bloat can accumulate quietly over many sessions.
Why does hard-rule enforcement outside the model matter if the rule is in CLAUDE.md?
CLAUDE.md is context the agent reads and reasons over, not a technical guardrail. For anything genuinely critical, a CI check or branch protection rule closes the gap that a missed or deprioritized instruction could leave open.
Should nested CLAUDE.md files repeat the root file's rules for safety?
No - repeating them adds redundant context cost on every session in that area. Nested files should assume the root file already applies and add only what's specific to their own scope.
What's the fastest way to tell if my CLAUDE.md has gotten too long?
Ask whether every section still changes what Claude Code would actually do differently. If parts are restated ideas, generic advice, or stale references, that's padding worth trimming regardless of overall length.
Do these practices apply the same way to a solo project and a team project?
The core practices (concrete rules, careful mentions, deliberate resets) apply either way. Team projects add more weight to reviewing CLAUDE.md changes and keeping nested files consistent, since more people are relying on the same shared memory.
How often should I revisit this list?
Whenever a project's structure changes meaningfully, a new team member joins, or a session starts feeling heavier than expected - it's meant as a recurring habit check, not a one-time setup task.
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.