Context in large codebase exploration

Why exploration is where context runs out

Claude Code’s best-practices guide opens with the constraint behind almost all of its advice: the context window fills up fast, and performance degrades as it fills. The window holds every message, every file Claude reads and every command output. A single debugging session or codebase exploration can consume tens of thousands of tokens, and as the window gets full Claude may start “forgetting” earlier instructions or making more mistakes. In practice that looks like answers that drift from the specific classes and call paths found an hour ago toward generic statements about how such systems usually work.

The guide names the failure directly as infinite exploration: asking Claude to “investigate” something without scope, so it reads hundreds of files and fills the context. The fix it gives has two halves — scope the investigation narrowly, or hand it to subagents so the exploration does not consume the main context.

Find first, then read

Anthropic’s context-engineering post describes Claude Code as a hybrid: a small amount of context is loaded up front (CLAUDE.md), and the rest is retrieved just in time with tools such as glob and grep, holding lightweight references like file paths and loading content only when needed. For exploration that means a deliberate order. Use Glob to find files by name pattern and Grep to find where a symbol is defined and used; then Read the few files those searches point to, following imports from the entry point rather than opening every file in the directory. (Choosing between the built-in tools is covered in 2.5.)

Delegate broad searches to subagents

When a question genuinely needs wide reading — “which services write to the orders table?” — delegate it. A subagent runs in its own context window; its intermediate file reads and tool results stay there, and only its final message returns to the main session. The best-practices guide suggests prompts of the form “use subagents to investigate X”, precisely so research does not crowd out the implementation work that follows.

Claude Code ships a built-in Explore subagent for this: read-only (write and edit are denied), aimed at file discovery and code search, and invoked with a thoroughness level — quick, medium or very thorough — to match the question. Custom subagents in .claude/agents/ work the same way when you want a specific prompt, tool set or model. Remember that a subagent starts fresh: put the file paths, symbols and constraints it needs in the delegation prompt (subagent context passing is covered in 1.3).

Investigate how the payments
system works.

Use subagents to find every code
path that issues a refund.
Start from api/refunds.py and
grep for callers of
RefundService.create.
Return: entry points, the call
chain for each, and any path
that skips fraud_check().
File paths and line numbers
only; no code excerpts.

Write findings down so they survive

Long explorations will eventually compact. Claude Code summarises the conversation and reloads a few things from disk — project-root CLAUDE.md and unscoped rules, auto memory, the plan written in plan mode, and up to five recently modified files — but individual discoveries made along the way exist only in the summary. Anthropic’s context-engineering post recommends structured note-taking for exactly this: have the agent keep a notes file of key findings (entry points, call chains, decisions, open questions) outside the context window, and reread it when needed. After compaction or in a new session, the file is still there.

# Exploration
- Record findings in NOTES.md as you go: file paths,
  call chains, decisions, open questions.
- Use subagents for any search likely to read more
  than ~10 files; ask them for paths and line numbers.

# Compaction
- When compacting, always preserve the list of files
  modified, the test command, and open questions.

The last instruction uses a documented technique: the best-practices guide suggests customising compaction in CLAUDE.md with lines such as always preserving the list of modified files and test commands. You can also compact deliberately with a focus — /compact focus on the refund call chain — before the automatic pass guesses what matters, or summarise just part of the conversation from the /rewind menu.

Know when to reset

The guide’s other named failure patterns are both about stale context. The kitchen sink session mixes unrelated tasks until the context is full of irrelevant material; the fix is /clear between tasks. Correcting over and over fills the context with failed approaches; after two failed corrections, /clear and write a better prompt using what you learned. For a large feature, the guide suggests a fresh session to execute a written spec, so implementation starts with clean context. Use /context at any point to see what is using the window.

Traps the wrong answers are built from

You should now be able to

• Explain why exploration fills context fastest and how degradation shows up.
• Apply just-in-time retrieval: locate with Glob and Grep before reading.
• Delegate broad searches to Explore or custom subagents with scoped prompts.
• Keep durable findings in a notes file and customise compaction in CLAUDE.md.
• Choose between targeted reads, delegation, /compact with focus and /clear.