Exploring large codebases stresses every part of context management. The model can hold only so much before quality degrades. This lesson covers the symptoms of context degradation, the patterns for working in large codebases, and how to recover from crashes.
Symptoms of Context Degradation
- Inconsistent answers — the model says one thing now, the opposite later.
- References to "typical patterns" instead of specific classes the model found earlier in the session.
- Forgetting that a specific function was already analyzed.
- Suggesting code that doesn't follow the project's actual conventions even though they were established earlier.
These are signs the relevant context is no longer accessible to the model — it's been pushed out, summarized, or lost in the middle.
Pattern 1: Subagents for Specific Investigations
Spawn subagents for focused investigations: "explore the authentication flow," "map the database schema," "find all error-handling patterns." Each subagent returns a summary to the main agent. The main agent maintains a high-level view; subagents do the deep dives.
This keeps the main context lean. Without subagents, every exploratory tool call lands in the main context, eating capacity.
Pattern 2: Scratchpad Files
Maintain a scratchpad file (e.g., SCRATCHPAD.md) recording key findings: "authentication uses JWT, refresh handled in /auth/refresh," "database queries go through Repository pattern, base class is in src/data/." The model reads the scratchpad at the start of each phase. Findings persist even after the original tool calls fall out of context.
Pattern 3: Summarize Before Spawning
Before spawning sub-agents for the next phase, summarize the findings from the current phase. The summary becomes the input to the next phase. The model doesn't carry forward the verbose tool outputs from the previous phase — only the summary.
Pattern 4: Crash Recovery via State Manifests
For long-running explorations that may crash or hit context limits, periodically export structured agent state — files explored, findings recorded, hypotheses formed, open questions. On resume, the coordinator loads the manifest and continues. The structured manifest is more reliable than trying to reconstruct state from tool history.
The Resume vs Fresh-Start Decision
| Use --resume when | Use fresh + summary when |
|---|---|
| Prior context is mostly valid | Tool results reference files that have changed |
| Conversation is short enough not to be in context pressure | The session is approaching context limits |
| The user wants to continue a specific train of thought | You've identified a clean restart point |
Inform the Agent About Changed Files
If files have been modified since the last session, the agent's tool history references stale state. Resuming and acting on those stale tool results produces wrong answers. Either start fresh with a structured summary, or explicitly tell the agent which files have changed and that prior tool results for those files should be re-validated.
Skills to Develop
- Recognize symptoms of context degradation (inconsistency, generic "typical" references).
- Spawn subagents for verbose investigations to keep main context lean.
- Maintain scratchpad files for findings that need to persist across phases.
- Summarize phase outputs before spawning sub-agents for the next phase.
- Export structured state manifests for crash recovery.