Task statement 5.4 · Context management and reliability
Manage context effectively in large codebase exploration
The engineer is tracing refund flow dependencies before the billing system's refunds move to a new payments provider. Two hours in, the answers describe refund services in general instead of the classes this codebase actually has.
share
The tempting fix is to keep everything in one conversation and push on. A larger context window only postpones the moment compaction starts summarising, and the findings made early are the ones it compresses. Starting over with /clear throws the findings away along with the noise. Reading every file in the main session feels thorough, but the listings crowd out the specific classes that later questions depend on.
KnowledgeWhat degrades, and what keeps findings exact
In an extended session, every directory listing, search result and file read is appended to the context window and re-sent with each later request. As the window fills, the model recalls earlier material less accurately, and Claude Code eventually compacts the session into a summary. The guide calls the result context degradation: the model gives inconsistent answers and references "typical patterns" rather than the specific classes it discovered earlier. Asked at hour two what calls RefundLedgerAdapter.post(), a class it found an hour before, the session answers "a typical refund service calls its ledger adapter from the commit step". Rephrasing the question cannot fix this, because the finding now exists only inside a summary.
A scratchpad file is a file on disk where the agent records key findings and reads them back for later questions, so they survive context boundaries: a compaction, the end of a subagent, or a new session. Subagent delegation hands a verbose question such as "find all test files" to a subagent, which reads in its own context window and returns only a summary, so the main agent keeps the high-level picture. Claude Code's built-in Explore subagent exists for this: it is read-only, and Claude sends it codebase searches so the results stay out of the main conversation. Between phases, the main agent summarises what one phase found and injects that summary into the initial context of the next phase's subagents.
- Phase 1 finds all test files. An Explore subagent searches and returns a short summary.
- The main agent writes the key paths from that summary to the scratchpad file.
- Phase 2 traces refund flow dependencies, starting from phase 1's injected summary.
- Every agent exports its state to a known directory as it goes, next to a manifest, a file listing each agent, its status and where its state is.
- Phase 3 asks a specific question, and the main agent reads the scratchpad before answering.
Interactive · the same three phases, run three ways
Choose how the exploration is run. Shown: subagents and a scratchpad, the setup in the steps above.
Everything runs in one context window. Compaction summarises phase 2's findings, and the answer falls back on typical patterns.
Verbose reads stay in subagents' own context windows. Findings are written to the scratchpad and read back exactly when phase 3 needs them.
The crash loses the context window, not the work. The manifest says where each agent's state is, and the coordinator picks up from there.
SkillThe same question, answered from a file
With the setup above, phase 1's Explore subagent searches the repository and returns a 1,500-token summary of 212 test files, and the main agent writes the refund-relevant paths to .explore/refund-flow-notes.md. The phase 2 subagent starts from an injected summary of phase 1, so it goes straight to RefundController.create() instead of re-mapping the test tree. When phase 3 asks what calls RefundLedgerAdapter.post(), the main agent reads line 14 and names the exact caller.
// phase 2 subagent's first prompt (refund-tracer) Trace refund flow dependencies, starting at RefundController.create(). Phase 1 summary: 212 test files; refund tests in tests/refunds/ (14); modules refunds/, ledger/, gateway/; ledger/ has no tests. Append each finding to .explore/refund-flow-notes.md as you go.
# .explore/refund-flow-notes.md, lines 13–15 13 RefundService.commit() → RefundLedgerAdapter.post(refundId, cents) 14 Caller of post(): RefundService.commit() at refunds/service.ts:88 15 Card reversals go through PaymentsGateway.charge()
SkillWhen /compact is the right move
/compact replaces the conversation history with a summary, and optional focus instructions tell the summary what to keep. It fits when verbose discovery output is already in the context and you want to keep working in the same session. Suppose the engineer listed every file under ledger/ and grepped the whole repository for post( in the main session. Forty minutes later, 300 lines of listings fill 80% of the window, and the two findings that matter are already in the scratchpad. Delegating now would not help, because the output is already in the history, and /clear would drop the half-finished question about ledger retries. /compact focus on ledger retries and RefundLedgerAdapter frees the space and keeps that thread, while the scratchpad keeps the exact findings a summary would round off.
SkillCrash recovery from a manifest
A crash loses the context window of every running agent at once, so the work has to be persisted as structured state. Each agent exports its state to a known location as it works, and the manifest from step 4 describes the whole run. On resume, the coordinator loads the manifest and injects each agent's state into that agent's prompt. Here the refund-tracer was interrupted after tracing PaymentsGateway.charge(), so it restarts from that checkpoint, and the finished test-finder does not run again. The paths resolve against this tree.
billing-legacy/
└── .explore/
├── manifest.json
├── refund-flow-notes.md # the scratchpad
├── test-finder.json
└── refund-tracer.json
// .explore/manifest.json, loaded by the coordinator on resume
{
"phase": 2,
"scratchpad": ".explore/refund-flow-notes.md",
"agents": [
{ "name": "test-finder", "status": "done",
"state": ".explore/test-finder.json" },
{ "name": "refund-tracer", "status": "interrupted",
"state": ".explore/refund-tracer.json",
"last_checkpoint": "PaymentsGateway.charge() traced" }
]
}
| Verbose output from a search not yet run | Delegate it to a subagent such as Explore, and keep only its summary. |
| Verbose output already in the history | Write the key findings to the scratchpad, then /compact with a focus. |
| A new phase, or a resume after a crash | Start it from the scratchpad and a phase summary, or from the manifest. |
- Inconsistent answers that cite "typical patterns" instead of classes found earlier are context degradation, and asking again does not bring the finding back.
- Explore is Claude Code's read-only subagent for codebase search, so its file listings never enter the main conversation.
- A crash-safe exploration exports each agent's state to a known location and resumes from a manifest.