CertSafari
    Anthropic Claude Certified Architect – Foundations (CCAR-F)· Lessons

    Domain 5 · Lesson 28/30

    Managing context in large codebase exploration

    Manage context effectively in large codebase exploration

    20 min read
    2.5% of exam
    6 sources
    Published 20 Oct 2026
    Docs as of 14 Oct 2026

    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?

    Sources12

    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.

    When a subagent pays for itself and when it does not
    Delegate to a subagent when…Work in the main conversation when…
    The task produces verbose output you don't need in your main contextYou're making a quick, targeted change
    The work is self-contained and can return a summaryThe task needs frequent back-and-forth or iterative refinement
    You want to enforce specific tool restrictions or permissionsLatency 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?

    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?

    Sources342

    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?

    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?

    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?

    Sources5326

    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.

    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?

    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.

    A compact boundary event from an automatic compactionjson
    {
      "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:

    What happens to each kind of context when Claude Code compacts
    MechanismAfter compaction
    Project-root CLAUDE.md and unscoped rulesRe-injected from disk
    Files Claude read or editedRe-reads up to five, most recently modified first
    Background commands and background subagentsKeep running; Claude is reminded which are still running
    Context that hooks added earlierSummarized 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.

    Sources5142

    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:

    1. 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.
    2. 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.
    3. 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?

    Sources46

    Sources

    (6)

    Every claim above is drawn from one of these pages, quoted as it was written on the date shown.

    1. 1.
      “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. 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. 3.
      “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. 4.
      “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. 5.
      “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. 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

    Ready to test yourself?

    Practise the 16 questions on this subdomain.

    Spotted a mistake, or was something unclear? Tell us.