What you will be able to do
- Recognise context degradation in a long exploration session and say what causes it
- Decide when to delegate a discovery task to a subagent and when to run it directly
- Use scratchpad files, including one file per concurrent subagent, to keep findings past context boundaries
- Maintain a scratchpad during exploration and consult it before answering later questions, so degraded recall does not decide the answer
- Inject a phase summary into the next phase's subagent prompts
- Use /compact and /clear without losing exact facts
- Design crash recovery around per-agent state exports and a coordinator manifest
Key concept
Context as a finite attention budget — Every token that enters the context window competes for the model's attention, so recall of specific earlier findings gets worse as the window fills. Large-codebase exploration is about deciding which tokens are allowed into the main context and keeping everything else in subagents or on disk.
1.Why long exploration sessions degrade
A session that has been exploring a large repository for hours starts to get things wrong in a recognisable way. Its answers drift: asked about a class it examined in detail early on, it describes what such a class typically looks like rather than what it actually found, and two answers about the same component stop agreeing with each other. The specific finding is still somewhere in the transcript. The model just no longer retrieves it reliably.
The cause is context rot. As the number of tokens in the window grows, the model's ability to recall any one piece of information from that window drops. This is a performance gradient rather than a hard cliff, and it shows up in every model; some degrade more gently than others. Exploration makes it worse because discovery work is verbose. Each file read, grep result and directory listing piles up, and an unscoped "investigate this" can have Claude read hundreds of files into the main conversation.
That rules out the obvious fixes. A larger model still suffers context rot. A higher output-token limit lets the agent write more but does nothing for what it can recall. Re-reading the whole repository floods the context again and repeats the problem. What works is controlling what enters the main context in the first place and keeping important findings somewhere that does not depend on recall from a long transcript. The rest of this lesson covers the tools for each.
Checkpoint 1 of 9· Check yourself
An agent has spent hours exploring a large repository. When asked about a class it examined in detail early on, it now describes what such a class typically looks like, and its two latest answers about that component disagree. Which response deals with the cause?
This is context rot: recall gets worse as the window fills, and it happens in every model. A larger model or a higher output limit leaves recall unchanged, and re-reading the repository floods the context again. The fix is to control what enters the context and to store findings outside the transcript.
“While some models exhibit more gentle degradation than others, this characteristic emerges across all models.”Source: www.anthropic.com
2.Delegating verbose discovery to subagents
A subagent runs in its own context window. It can read dozens of files and run as many searches as it needs, and only its final message comes back to the parent. The main agent gets the answer without the noise. The detailed search context stays in the subagent, and the coordinator keeps its window for the high-level plan: what has been learned, what to ask next and how the pieces fit together. A subagent may use tens of thousands of tokens while it explores, but it typically returns a distilled summary of about 1,000 to 2,000 tokens.
Delegated tasks should be specific questions with answers that compress well. "Find all test files and return the paths as one list" and "Trace the refund flow's dependencies and report the call chain" are good examples. Claude Code includes an Explore subagent built for this kind of work. Its purpose is file discovery, code search and codebase exploration, and it gets read-only tools, with Write and Edit denied. For the test-file inventory, the alternatives that keep the search in the main agent all fail. Capping output at the first 200 matches gives an incomplete inventory. Searching one directory at a time still lands every path in the main context, just spread over several turns. Compacting afterwards means the flood has already happened.
| Delegate to a subagent when… | Work in the main conversation when… |
|---|---|
| The task produces verbose output you don't need in your main context | You're making a quick, targeted change |
| The work is self-contained and can return a summary | The task needs frequent back-and-forth or iterative refinement |
| You want to enforce specific tool restrictions or permissions | Latency matters: a non-fork subagent starts fresh and may need time to gather context |
The right column matters as much as the left. Finding the one function that computes a discount rate in a small module, before making a single edit, is a quick targeted lookup. A subagent would have to start fresh and gather context first, so a direct Grep or Read in the main conversation is the better choice. Save delegation for discovery whose raw output you would never look at again.
Checkpoint 2 of 9· Check yourself
Mid-way through a long exploration session, four tasks come up. Which one should stay in the main conversation instead of going to a subagent?
The discount-rate lookup is a quick, targeted change. A non-fork subagent starts with a fresh context and would first have to gather context, so a direct Grep or Read in the main conversation is faster. The other three tasks produce verbose output that compresses into a short answer, so they should go to a subagent.
“Latency matters. A subagent that isn’t a fork starts fresh and may need time to gather context”Source: code.claude.com
Checkpoint 3 of 9· Exam question
A main agent is coordinating exploration of a repository with over 50,000 files and needs a complete list of every test file before planning a coverage audit. Running the search directly would flood the main conversation with thousands of matched paths it will not need again. What best keeps the main agent's context focused on high-level coordination while still producing the list?
Correct answer: B — Run the search in a subagent that scans the repository and returns only the matching test file paths as one consolidated list.
- A. Incorrect. Capping the output at the first 200 matches keeps the conversation small, but in a repository with over 50,000 files the capped set is almost certainly incomplete. The coverage audit needs every test file, so a partial list does not meet the requirement.
- B. Correct. A subagent runs the search in its own context window, so the thousands of matched paths never enter the main conversation. The main agent receives only the finished list of test files and can keep its context for coordinating the audit.
- C. Incorrect. Splitting the search by directory still returns every matched path to the main agent, and noting each batch means the full list builds up in the main conversation anyway. The flood of paths the main agent will not need again is spread out, not avoided.
- D. Incorrect. Compaction runs only after the matched paths have already filled the main conversation, so it does not prevent the flood. A summary can also drop individual paths, which puts at risk the complete list the audit depends on.
3.Scratchpad files that outlive the context window
A scratchpad file keeps key findings alive across context boundaries. Every boundary in a long exploration, whether a compaction that replaces the conversation with a summary, a fresh session, or a hand-off to a new subagent, discards the transcript but leaves the disk untouched. The agent writes a note to a file as it learns something and reads it back before it relies on that knowledge. In context-engineering terms this is structured note-taking: notes persisted outside the context window and pulled back in when needed. A to-do list, or a custom agent's NOTES.md, follows the same pattern.
The agent has to maintain the file as it works, not reconstruct it afterwards. When it finds that OrderService extends a custom TransactionalBase class with a distinctive retry mechanism, it records the class name, the base class and the detail that makes it unusual, right then. Each entry should be specific enough to stand in for the original reading: names, paths, values. A line such as "OrderService has some retry logic" is the same vague, typical-pattern answer that degradation produces, only saved to disk.
The file counteracts degradation only when later questions go through it. Asked about OrderService hours later, the agent reads the notes before answering, and the answer comes from the recorded finding instead of from recall over a long transcript. Writing without reading still leaves the answer to recall, and recall is the thing that degraded. The agent's instructions should therefore state the rule outright: before answering any question that depends on an earlier finding, consult the scratchpad, and add new findings to it afterwards. The same habit lets long-running agents keep going after context resets: they read their own notes and pick up multi-hour work where they stopped.
Concurrent subagents need a file convention. When several subagents investigate different modules in parallel, each one should write to its own uniquely named scratchpad, such as one file per module. The coordinator should aggregate those files only after every subagent has finished. Subagents run concurrently and in isolated contexts, and none of them can see what another is doing. A single shared file written as findings arrive, or one fixed filename that each agent overwrites, lets one agent's record replace another's before anyone reads it. Skipping files and relying on each subagent's final reply leaves nothing on disk if a subagent is cut off or the session moves on.
Checkpoint 4 of 9· Check yourself
During a multi-hour exploration, the agent wrote to NOTES.md that OrderService extends TransactionalBase and has a distinctive retry mechanism. Hours later, asked about OrderService, it describes a generic service class and does not mention TransactionalBase. The notes file is still on disk and correct. What change fixes this?
A scratchpad only helps if both halves happen: the agent writes the finding down, then pulls it back into context before relying on it. If it writes but never reads, the answer still depends on recall from a long transcript, which is exactly what degraded. A focused compact or a larger model does not fix that.
“the agent regularly writes notes persisted to memory outside of the context window. These notes get pulled back into the context window at later times.”Source: www.anthropic.com
Checkpoint 5 of 9· Exam question
Several subagents are running concurrently, each investigating a different module of a large codebase and recording findings as they go. The architect must prevent one subagent's findings from being overwritten by another before the coordinator can reliably aggregate the results. Which scratchpad convention best achieves this?
Correct answer: A — Give each subagent its own uniquely named scratchpad file, e.g., one per module, and have the coordinator aggregate all files only after all subagents have finished their investigations.
- A. Anthropic's multi-agent architecture guidelines recommend isolating subagent output to prevent interference. Each subagent should write to its own scratchpad or external memory (e.g., uniquely named files). The coordinator then aggregates these separate outputs once all subagents complete, avoiding race conditions and ensuring data integrity.
- B. A single shared scratchpad file creates race conditions: concurrent writes from multiple subagents can lead to lost or corrupted data before the coordinator can aggregate the results. Isolated files per subagent are necessary to prevent such conflicts.
- C. Relying solely on verbal reporting risks context pollution and makes it harder to preserve intermediate results. The recommended pattern is to persist findings to isolated scratchpads or external storage, which the coordinator can then reliably read and synthesize.
- D. Using a single fixed filename results in the last write from any subagent overwriting all previous findings, directly causing the problem the architect wants to avoid. Unique filenames per subagent are required for safe concurrent recording.
Checkpoint 6 of 9· Exam question
An architect has been running a single Claude Code session for several hours exploring a large monorepo. Early on, the agent correctly identified that OrderService extends a custom TransactionalBase class with a distinctive retry mechanism. Hours later, asked about OrderService again, the agent describes it as 'typically extending a standard base controller with default error handling,' ignoring its earlier finding. What should the architect do going forward to prevent this?
Correct answer: A — Have the agent save class names and base classes it discovers to a notes file, so it can read them before answering questions.
- A. Correct. Writing specific findings such as class names and base classes to a file gives the agent a durable record outside the long transcript. It can consult that record before answering, so later answers stay tied to what was actually found.
- B. Incorrect. The output token limit only caps how long a response can be. The agent ignored its earlier finding because it was buried in a long session, not because its answers were cut short, so a higher limit leaves the problem in place.
- C. Incorrect. A larger model does not fix the loss of early details in a long session. Those findings are still diluted across hours of transcript, so the fix is to manage context, not to change model size.
- D. Incorrect. Re-reading a large monorepo from scratch repeats hours of exploration and adds a great deal more material to the context, which dilutes earlier findings further. It also leaves no compact record of what was found for the agent to consult.
4.Carrying findings into the next exploration phase
Large explorations happen in phases. First you map the modules, then you trace specific flows, then you check how those flows are tested. Subagents start with no parent context: a non-fork subagent begins with only the prompt it is given. A phase-2 subagent therefore knows nothing that phase 1 found unless that knowledge is written into its task message.
So before spawning the next phase, the coordinator condenses what the last phase established into a short summary and puts it at the top of each new subagent's prompt. A phase-2 prompt might begin: "Refunds enter through RefundController; OrderService extends TransactionalBase, which retries on lock timeouts; payment calls go through the gateway adapter. Trace where refund state is persisted." Without that, every phase-2 subagent rediscovers the module map, which costs time and tokens and can come out slightly different each time. With it, each subagent starts from the same facts and spends its context on the new question.
The phase-2 subagents would then start with a crowded context, which is the problem delegation exists to avoid. A summary passes on the established facts (names, relationships, open questions) and leaves room for the new investigation.
Checkpoint 7 of 9· Check yourself
Phase-2 subagents, each tracing a different refund-related flow, keep spending most of their tokens re-mapping the modules that phase 1 already mapped. Their module maps also differ slightly from one another. What should the coordinator change before spawning them?
A non-fork subagent starts with a fresh context that holds only the prompt it is given. Phase-1 knowledge therefore has to be written into its task message. A short summary gives every subagent the same facts without filling their context the way full reports would. Compacting the coordinator changes only the coordinator's own context, not what the subagents receive.
“Fresh context with the prompt you pass”Source: code.claude.com
Sources4
5.Using /compact and /clear during long exploration
When a session's context has filled with discovery output, /compact replaces the conversation with a structured summary and frees space so the session can continue. Automatic compaction also fires on its own as the window fills. When it does, Claude Code records a compact boundary showing the trigger and how many tokens were in context beforehand.
{
"type": "system",
"subtype": "compact_boundary",
"compactMetadata": {
"trigger": "auto",
"preTokens": 167189
}
}Running it yourself with a focus gives better results than waiting for the automatic pass. /compact focus on the refund flow trace keeps what you choose instead of what the automatic pass guesses is important. You can also add a standing instruction to CLAUDE.md, such as "When compacting, always preserve the full list of modified files and any test commands." Even so, a summary is lossy. Compaction that is too aggressive can drop subtle context whose importance only becomes clear later, such as an exact configuration value found during a debugging detour.
That is why /compact and a scratchpad file work as a pair. /compact reclaims the space, and the scratchpad keeps the exact facts, such as pool_size=12 or the name of a base class, word for word on disk where no summary can blur them. It also helps to know what reloads after compaction:
| Mechanism | After compaction |
|---|---|
| Project-root CLAUDE.md and unscoped rules | Re-injected from disk |
| Files Claude read or edited | Re-reads up to five, most recently modified first |
| Background commands and background subagents | Keep running; Claude is reminded which are still running |
| Context that hooks added earlier | Summarized with the rest of the conversation |
A scratchpad you created is not automatically one of the five files re-read, so the agent's instructions should say to read it again before answering. Subagent transcripts are stored in separate files and are not affected when the main conversation compacts. /clear is a different tool: it resets the context entirely and is meant for switching to unrelated work, where the old conversation would only crowd out the files you need next. Use /compact to continue the same exploration with less weight, and /clear to start a different one.
Checkpoint 8 of 9· Match them up
An extended exploration session needs four different context tools. Match each tool to the job it does.
Tap a term, then the definition that fits it.
/compact (focused or not) continues the same work by summarising, and every summary is lossy, so exact values belong in a scratchpad on disk. /clear starts fresh and is only for moving to a different task.
“Clear between tasks: run /clear when switching to unrelated work. Old conversation crowds out the files you need next and costs tokens on every message.”Source: code.claude.com
6.Crash recovery with state exports and a manifest
A coordinator that crashes partway through a multi-agent exploration loses its conversation, but it should not lose the work. The idea from Resume vs start fresh with an injected summary applies across the whole system. Each agent exports its state to a known location. When the system restarts, the coordinator loads a manifest of that state and injects it into the agents' prompts instead of relying on any agent's memory.
The design has three parts, and each one closes a specific gap:
- As each subagent finishes, it writes its findings to a known file path, a per-agent export following the same one-file-per-agent rule as scratchpads.
- The coordinator records that agent's status and result path in a manifest file, so a single file describes the state of the whole run.
- On restart, the coordinator reads the manifest first. It does not re-run the agents marked complete. It loads their exported findings and injects them into the prompts of the subagents it spawns for the unfinished work.
Long-running agent harnesses show the same pattern in practice. An initializer creates a claude-progress.txt log of what agents have done and a JSON feature list where each entry carries a passes flag. Every later session starts by reading the git log and progress files to get oriented. The progress file is not decoration: compaction alone does not always pass clear instructions to the next session, and without the file the next agent has to guess what happened. The format matters too. Models are less likely to wrongly change or overwrite JSON than Markdown, which is a good reason to keep a manifest in structured JSON.
Claude Code applies similar persistence to subagents themselves. When a background subagent fails, the message Claude receives names the error and includes the subagent's last output, so partial work is not lost. Subagent transcripts also persist within their session, so a subagent can be resumed after a restart. A manifest takes this a step further: it records which work is complete in a form the coordinator can read on startup.
Checkpoint 9 of 9· Check yourself
You are designing the file a coordinator reads first on restart. It must show which exploration subagents have finished and where each one's findings are, and agents will update their own entries as they complete. Which design fits this lesson best?
Models are less likely to wrongly change or overwrite JSON than Markdown, so a structured JSON manifest that points to per-agent export files is the most reliable record. A shared append file breaks the one-file-per-agent rule. Compaction does not always pass clear instructions to the next session, and a crashed coordinator's conversation is gone anyway.
“we landed on using JSON for this, as the model is less likely to inappropriately change or overwrite JSON files compared to Markdown files.”Source: www.anthropic.com
Sources
(6)
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 1.https://code.claude.com/docs/en/best-practicesOfficial docs
“Long sessions with irrelevant context can reduce performance.”
↩︎ Why long exploration sessions degrade“Claude reads hundreds of files, filling the context.”
↩︎ Why long exploration sessions degrade“When compacting, always preserve the full list of modified files and any test commands”
↩︎ Using /compact and /clear during long exploration - 2.
“as the number of tokens in the context window increases, the model’s ability to accurately recall information from that context decreases.”
↩︎ Why long exploration sessions degrade“returns only a condensed, distilled summary of its work (often 1,000-2,000 tokens).”
↩︎ Delegating verbose discovery to subagents“These notes get pulled back into the context window at later times.”
↩︎ Scratchpad files that outlive the context window“After context resets, the agent reads its own notes and continues multi-hour training sequences or dungeon explorations.”
↩︎ Scratchpad files that outlive the context window“this simple pattern allows the agent to track progress across complex tasks”
↩︎ Scratchpad files that outlive the context window“overly aggressive compaction can result in the loss of subtle but critical context whose importance only becomes apparent later.”
↩︎ Using /compact and /clear during long exploration“Context, therefore, must be treated as a finite resource with diminishing marginal returns.”
↩︎ Key concept“this characteristic emerges across all models”
↩︎ Exam trap 1“These notes get pulled back into the context window at later times.”
↩︎ Exam trap 4“overly aggressive compaction can result in the loss of subtle but critical context whose importance only becomes apparent later.”
↩︎ Exam trap 5“While some models exhibit more gentle degradation than others, this characteristic emerges across all models.”
↩︎ Checkpoint“the agent regularly writes notes persisted to memory outside of the context window. These notes get pulled back into the context window at later times.”
↩︎ Checkpoint - 3.https://code.claude.com/docs/en/agent-sdk/subagentsOfficial docs
“intermediate tool calls and results stay inside the subagent; only its final message returns to the parent.”
↩︎ Delegating verbose discovery to subagents“multiple subagents can run concurrently, so independent subtasks finish in the time of the slowest one rather than the sum of all of them.”
↩︎ Scratchpad files that outlive the context window“multiple subagents can run concurrently, so independent subtasks finish in the time of the slowest one rather than the sum of all of them.”
↩︎ Exam trap 3 - 4.https://code.claude.com/docs/en/sub-agentsOfficial docs
“Purpose: file discovery, code search, codebase exploration”
↩︎ Delegating verbose discovery to subagents“You’re making a quick, targeted change”
↩︎ Delegating verbose discovery to subagents“Fresh context with the prompt you pass”
↩︎ Carrying findings into the next exploration phase“Task message: the delegation prompt Claude writes when it hands off the work.”
↩︎ Carrying findings into the next exploration phase“when the main conversation compacts, subagent transcripts are unaffected. They’re stored in separate files.”
↩︎ Using /compact and /clear during long exploration“includes the subagent’s last output, so partial work isn’t lost.”
↩︎ Crash recovery with state exports and a manifest“Session persistence: subagent transcripts persist within their session.”
↩︎ Crash recovery with state exports and a manifest“Latency matters. A subagent that isn’t a fork starts fresh and may need time to gather context”
↩︎ Checkpoint - 5.https://code.claude.com/docs/en/context-windowOfficial docs
“you run /compact, which replaces the conversation with a structured summary”
↩︎ Scratchpad files that outlive the context window“The summary keeps what you choose instead of what the automatic pass guesses is important.”
↩︎ Using /compact and /clear during long exploration“run /clear when switching to unrelated work.”
↩︎ Using /compact and /clear during long exploration“send research to a subagent so the file contents stay in its context window, not yours.”
↩︎ Exam trap 2“Clear between tasks: run /clear when switching to unrelated work. Old conversation crowds out the files you need next and costs tokens on every message.”
↩︎ Checkpoint - 6.
“agents need a way to bridge the gap between coding sessions.”
↩︎ Scratchpad files that outlive the context window“a claude-progress.txt file that keeps a log of what agents have done”
↩︎ Crash recovery with state exports and a manifest“This happens even with compaction, which doesn’t always pass perfectly clear instructions to the next agent.”
↩︎ Crash recovery with state exports and a manifest“the model is less likely to inappropriately change or overwrite JSON files compared to Markdown files.”
↩︎ Crash recovery with state exports and a manifest“Read the git logs and progress files to get up to speed on what was recently worked on.”
↩︎ Exam trap 6“each new session begins with no memory of what came before.”
↩︎ Prediction“we landed on using JSON for this, as the model is less likely to inappropriately change or overwrite JSON files compared to Markdown files.”
↩︎ Checkpoint