Exploring a large codebase without losing the thread

An Agent SDK agent helps make sense of a legacy codebase with hundreds of files. For the first hour it answers with exact class names and paths. Two hours later it talks about “the typical repository pattern” and contradicts what it said before. That is context degradation: the window filled up with search output and what mattered got diluted or compacted away.

The context window lesson already introduced the scratchpad file and /compact. This one covers how to set up a long exploration so it never gets there.

Warning signs

• Answers about “typical patterns” instead of the specific classes it already found.
• Claims about the code that come from memory and are out of date.
• Inconsistent answers to the same question.

Two habits help from the start: scoped searches (paths, line numbers and short snippets, with a cap, instead of 2,000 lines of matches) and requiring every claim about the code to cite a path and line from a fresh read.

Split the work across subagents

The main agent does not have to read the forty files. It spawns subagents with focused questions (“find all test files”, “trace the refund flow dependencies”); each explores in its own context and returns only a structured summary. The verbose output stays isolated (context isolation) and the main agent keeps the coordination and the big picture. In a 40-package monorepo: one subagent per package and one pass that integrates the summaries.

Between phases, a summary

A new subagent starts from scratch: all it receives is its prompt. If phase 1 found the existing test helpers and phase 2 writes tests, the phase 2 subagents will explore again and ignore those helpers unless you pass them along. So before launching the next phase, the coordinator summarises the findings that matter and puts them in the initial context of each new subagent.

Notes outside the conversation

The scratchpad file keeps confirmed findings with path and line range, plus open questions. The agent consults it before answering each new question, not just at the end, and rereads it when resuming the next day. Because it lives outside the context, it does not depend on what an automatic compaction keeps.

In an interactive session that is filling up with grep and test output mid-task, /compact summarises the conversation to free space and accepts focus instructions: “keep the findings about bookings, the class names and the open questions”.

Surviving a crash

A multi-agent research run is cut off halfway (the container restarts). If the state lived only in memory, it starts from zero or with an incomplete set. Crash recovery is designed like this:

1. each agent exports its result and status to a known location in storage that outlives the process;
2. on resume, the coordinator loads a manifest of finished tasks;
3. it injects those results into the prompts and launches only what is pending.

The typical traps

• A bigger window, or “remember what you found”, as the fix.
• Having the main agent read everything itself.
• Assuming phase 2 subagents inherit what was learned in phase 1.
• Restarting the exploration from scratch after a crash.

On the exam

If the symptom is generic or self-contradicting answers, the answer involves notes outside the context or subagents that isolate the exploration. If new subagents repeat work, inject a summary of the previous phase. If the system crashes, exported state and a manifest.