Codebase Exploration & Context Degradation

Official Exam Guide Objectives

Task 5.4: Manage context effectively in large codebase exploration.

Knowledge of

• Context degradation in extended sessions: models start giving inconsistent answers and referencing "typical patterns" rather than specific classes discovered earlier
• The role of scratchpad files for persisting key findings across context boundaries
• Subagent delegation for isolating verbose exploration output while the main agent coordinates high-level understanding
• Structured state persistence for crash recovery: each agent exports state to a known location, and the coordinator loads a manifest on resume

Skills in

• Spawning subagents to investigate specific questions (e.g., "find all test files," "trace refund flow dependencies") while the main agent preserves high-level coordination
• Having agents maintain scratchpad files recording key findings, referencing them for subsequent questions to counteract context degradation
• Summarizing key findings from one exploration phase before spawning sub-agents for the next phase, injecting summaries into initial context
• Designing crash recovery using structured agent state exports (manifests) that the coordinator loads on resume and injects into agent prompts
• Using /compact to reduce context usage during extended exploration sessions when context fills with verbose discovery output

What You Need to Know

Exploring a large codebase is about as context-hungry as agent work gets. Unfamiliar repositories, dependency chains, legacy systems — extended sessions of this kind produce a characteristic failure called context degradation, and it is not about running out of room. The model loses its hold on what it found earlier as the context fills with the verbose output of finding it.

Context Degradation

It shows itself in a recognisable way: the agent begins describing patterns instead of naming things. Several modules in, you get "this follows the typical repository pattern" where earlier you would have had "the OrderRepository class at src/repos/order.ts implements the base Repository<T> interface with custom caching in the findById method."

This happens because:

1. Every step of exploration emits bulk — whole files, search hits, directory listings.
2. All of it stays in the conversation.
3. The precise things found early sink beneath it as newer, larger output arrives.
4. Attention follows the recent material, and the specific references stop being reachable.

The critical insight: this is not a capacity problem, and a larger window does not address it. Nothing has been evicted for lack of space — the specifics are still present and simply no longer prominent, having been buried under everything that arrived afterwards. A bigger window buries them at greater depth.

Scratchpad Files

The main defence is to write findings down outside the conversation. The agent records what matters to a file and consults it later, which puts that knowledge somewhere accumulation cannot reach.

# Exploration Scratchpad — Order Service

## Key Classes
- `OrderRepository` — src/repos/order.ts; implements `Repository<T>`, caches inside findById
- `OrderService` — src/services/order.ts; sits over OrderRepository and PaymentGateway
- `RefundProcessor` — src/services/refund.ts; calls OrderService.getOrderWithItems()

## Dependency Chain
RefundProcessor → OrderService → OrderRepository → PostgreSQL
RefundProcessor → PaymentGateway → Stripe API

## Critical Findings
- Nothing retries when the Stripe call fails inside RefundProcessor
- OrderRepository keys its cache on orderId and never invalidates on a status change
- Coverage is lopsided: OrderService 87%, RefundProcessor 12%

Reading that file is how the agent recovers a detail rather than searching its own context for it. The timing matters as much as the technique: this is set up at the beginning of an extended exploration, because by the time degradation is visible the findings worth writing down have already blurred.

Subagent Delegation

The second defence is to move the verbose work elsewhere. Rather than the main agent reading every file and running every search itself — filling its own context with the output of both — specific questions go to subagents:

• "Which test files cover the order service, and what coverage do they report?"
• "Follow a refund from the API endpoint through to the database and name every service it passes through"
• "List the external API integrations and describe how each one handles failure"

Each one works in a context of its own, where it can be as verbose as the task requires, and returns a summary. Only that summary reaches the coordinator.

Parallelisation is the obvious read and it is the lesser benefit. What actually matters is isolation: exploration is inherently noisy, and delegating it keeps the noise out of the context doing the reasoning.

Summary Injection Between Phases

Exploration that proceeds in phases — architecture first, then specific components — should carry its conclusions forward. Summarise what phase one established and inject that into the prompts of the phase two subagents.

Skip it and phase two starts cold, re-deriving the architecture before it can begin its actual work, at the cost of the exploration phase one already paid for. Worse, a subagent without that background asks the wrong questions, because knowing which components matter is itself a phase one finding.

Phase 1 Summary (injected into Phase 2 subagent prompts):
- Architecture is layered throughout: Controllers → Services → Repositories → Database
- A refund travels RefundController → RefundProcessor → OrderService → PaymentGateway
- Open concern: nothing in RefundProcessor retries a failed external call
- For phase 2: examine how RefundProcessor and PaymentGateway handle errors

The /compact Command

Claude Code offers /compact for exactly this situation: it summarises the conversation so far, reclaiming the space that file contents, search output and directory listings have taken up.

Run it during a long exploration rather than at the point of exhaustion. Waiting until the window is full treats it as a capacity measure, and its real value is protecting the quality of what remains — compacting before the specifics get buried is what keeps them retrievable.

Crash Recovery via Structured State Manifests

Long sessions end unexpectedly — a crash, a dropped connection, context that ran out. With nothing persisted, the exploration is simply gone and repeats from the beginning.

Structured state persistence prevents that. Each agent writes its position to a known file, a manifest recording:

• Ground already covered — which files were opened, which searches ran
• The findings established so far
• Which phase it is in, and what comes next
• Questions still open and anything left unresolved

{
  "sessionId": "explore-order-service-001",
  "phase": 2,
  "exploredPaths": [
    "src/repos/order.ts",
    "src/services/order.ts",
    "src/services/refund.ts"
  ],
  "keyFindings": {
    "architecture": "Layered: Controllers → Services → Repositories → DB",
    "criticalIssue": "RefundProcessor has no retry logic for Stripe API failures",
    "testCoverage": {"OrderService": "87%", "RefundProcessor": "12%"}
  },
  "nextSteps": [
    "Investigate PaymentGateway error handling",
    "Review RefundProcessor test files",
    "Check cache invalidation logic in OrderRepository"
  ]
}

Resuming means loading the manifest into the new agent's prompt. Note what exploredPaths buys beyond the findings themselves: it stops the resumed session re-reading files whose conclusions are already recorded, which is where the cost of a naive restart actually sits.

Deep Dive

Structured note-taking (agentic memory) — the official name for scratchpad files

What this lesson calls "scratchpad files" is Anthropic's second named long-horizon technique: "structured note-taking, or agentic memory, is a technique where the agent regularly writes notes persisted to memory outside of the context window." The demonstrated case is Claude playing Pokémon — "after context resets, the agent reads its own notes and continues multi-hour training sequences or dungeon explorations" — the same mechanism this lesson applies to a codebase: persist the OrderRepository-at-src/repos/order.ts-level detail somewhere the model re-reads, rather than trusting it to survive in a filling context window. Anthropic's guidance on choosing between the three long-horizon techniques is explicit that note-taking "excels for iterative development with clear milestones" — a good fit for phased codebase exploration.

Sourceanthropic.com › effective-context-engineering-for-ai-agentsfetched 2026-07-30

Sub-agent architectures as the third long-horizon technique

Subagent delegation for exploration is the third documented technique: "rather than one agent attempting to maintain state across an entire project, specialized sub-agents can handle focused tasks with clean context windows." The token economics are explicit — "each subagent might explore extensively, using tens of thousands of tokens or more, but returns only a condensed, distilled summary of its work" to the coordinator. This is the mechanism behind this lesson's claim that subagent delegation is "primarily about context isolation" rather than parallelisation: the coordinator's context stays clean regardless of how much verbose exploration happened inside the subagent.

Sourceanthropic.com › effective-context-engineering-for-ai-agentsfetched 2026-07-30

/compact and /clear — exact command behaviour in Claude Code

Claude Code exposes two distinct commands for managing a filling context, and they do different things. /clear "start[s] fresh with an empty context" while Claude Code "saves the previous conversation" so it stays resumable via /resume. /compact [instructions] instead "replace[s] history with a summary, optionally focused on what you specify" — for example /compact Focus on the API changes — giving the developer control over what survives compaction rather than accepting a generic summary. Best-practice guidance says to "use /clear frequently between tasks to reset the context window entirely" and, "for more control, run /compact <instructions>, like /compact Focus on the API changes".

Sources: https://code.claude.com/docs/en/sessions (command definitions) · https://code.claude.com/docs/en/best-practices (when to clear vs compact, and the example) (fetched 2026-07-30)

Checkpoints and /rewind — a different recovery mechanism from state manifests

Claude Code separately checkpoints code state automatically: "every user prompt creates a new checkpoint," and /rewind (or pressing Esc twice on an empty prompt) opens a menu to restore code and conversation, conversation only, or code only, to that point. This is explicitly "local undo," not version control — "Checkpointing does not track files modified by bash commands... Only direct file edits made through Claude's file editing tools are tracked" — and checkpoints are saved with the conversation, so /rewind still works after a session resume. This is a different tool from the structured state manifest this lesson describes for crash recovery: checkpoints undo code changes within a session; manifests persist exploration findings across a coordinator's resume.

Sourcecode.claude.com › checkpointingfetched 2026-07-30

Subagent context isolation — the exact mechanics

At the SDK level, "each subagent runs in its own fresh conversation. Intermediate tool calls and results stay inside the subagent; only its final message returns to the parent." Even more specifically, "a subagent's context window starts fresh, with no parent conversation, but isn't empty. The only content you pass from parent to subagent is the Agent tool's prompt string" — it still gets its own system prompt, project CLAUDE.md, and tool definitions, but it does not inherit the parent's conversation history or tool results, and so does not automatically inherit the coordinator's accumulated findings. This is precisely why this lesson's summary-injection step between exploration phases is necessary: without explicitly building the Phase 1 summary into the Phase 2 subagent's prompt, that subagent starts from nothing.

Sourcecode.claude.com › subagentsfetched 2026-07-30

Quick Reference

Exam Traps

Practice Scenario

Build Exercise

Build a Context-Resilient Codebase Explorer

Difficulty: Advanced (3/4)

60 minutes

1. Create a coordinator agent that delegates specific codebase exploration tasks to subagents (e.g., find test files, trace dependency chains, identify external integrations)

Why: Subagent delegation is primarily about context isolation, not parallelisation. The main agent context stays clean for high-level coordination while subagents handle verbose exploration. This directly prevents context degradation by keeping verbose file contents and search results out of the coordinator context.

You should see: A coordinator function that spawns subagents with specific, focused investigation prompts. Each subagent returns a structured summary (key findings, file paths, class names) rather than raw verbose output. The coordinator context should remain clean.

2. Implement scratchpad file management: agents write key findings (class names, file paths, dependency chains) to a known file and read it before subsequent exploration steps

Why: Scratchpad files are the primary mitigation for context degradation. They persist knowledge outside the conversation context, making it immune to the attention shift that causes the model to reference typical patterns instead of specific class names and file paths it discovered earlier.

You should see: An agent that writes structured findings to a scratchpad file after each exploration step and reads the scratchpad at the start of each subsequent step. The scratchpad should contain specific class names, file paths, and dependency chains, not summaries.

3. Build summary injection logic: after Phase 1 exploration, summarise findings and inject the summary into Phase 2 subagent prompts

Why: Summary injection prevents the cold start problem where Phase 2 subagents duplicate Phase 1 exploration because they were not given previous findings. It ensures Phase 2 agents have the architectural understanding needed to ask the right questions without rediscovering the system structure.

You should see: A Phase 1 summary document that captures the high-level architecture, key concerns, and specific investigation targets for Phase 2. This summary is injected into the initial prompt of every Phase 2 subagent.

4. Implement crash recovery: each agent exports structured state (explored paths, key findings, next steps) to a manifest file that the coordinator loads on resume

Why: Extended exploration sessions can fail from crashes, network interruptions, or context exhaustion. Without recovery mechanisms, all progress is lost. Structured state manifests enable the coordinator to resume from the last checkpoint rather than restarting from scratch.

You should see: A manifest file in JSON format containing the session ID, current phase, explored paths, key findings, and next steps. On resume, the coordinator loads this manifest and injects it into agent prompts so exploration continues from where it left off.

5. Test context degradation by running an extended exploration session across multiple modules and verify that scratchpad files preserve specific class names and file paths that would otherwise degrade to generic descriptions

Why: This validates that the scratchpad mitigation actually works against context degradation. The observable symptom is the model referencing typical patterns instead of specific classes and paths. You need to confirm that scratchpad files prevent this degradation.

You should see: Two comparison runs: one without scratchpad files where the agent degrades to generic references after exploring 4-5 modules, and one with scratchpad files where the agent maintains specific class names and file paths throughout the entire session.

Sources

• Claude Certified Architect Foundations Exam Guide — Domain 5, Task Statement 5.4 — Anthropic
• Claude Code Documentation — Context Management — Anthropic
• Claude Code Documentation — Commands — Anthropic
• Effective Context Engineering for AI Agents — Anthropic
• Claude Code — Sessions — Anthropic
• Claude Code — Checkpointing — Anthropic
• Agent SDK — Subagents — Anthropic

Appendix A — Build Exercise Step Hints

Progressive hints revealed by the "Stuck? Get a nudge" control on each step.

Step 1. Create a coordinator agent that delegates specific codebase exploration tasks to subagents (e.g., find test files, trace dependency chains, identify external integrations)

Why: Subagent delegation is primarily about context isolation, not parallelisation. The main agent context stays clean for high-level coordination while subagents handle verbose exploration. This directly prevents context degradation by keeping verbose file contents and search results out of the coordinator context.

You should see: A coordinator function that spawns subagents with specific, focused investigation prompts. Each subagent returns a structured summary (key findings, file paths, class names) rather than raw verbose output. The coordinator context should remain clean.

const investigationTasks = [
  { task: "Find all test files for the order service and report coverage status", subagent: "test-coverage" },
  { task: "Trace the refund flow from API endpoint to database, listing all intermediate services", subagent: "refund-flow" },
  { task: "Identify all external API integrations and their error handling patterns", subagent: "external-apis" }
];

async function delegateToSubagent(task) {
  const result = await spawnSubagent({
    prompt: task.task,
    returnFormat: "structured_summary"
  });
  // Coordinator receives only the summary, not verbose exploration output
  return { task: task.subagent, findings: result.structuredFindings };
}

investigation_tasks = [
    {"task": "Find all test files for the order service and report coverage status", "subagent": "test-coverage"},
    {"task": "Trace the refund flow from API endpoint to database, listing all intermediate services", "subagent": "refund-flow"},
    {"task": "Identify all external API integrations and their error handling patterns", "subagent": "external-apis"},
]


async def delegate_to_subagent(task: dict) -> dict:
    result = await spawn_subagent(prompt=task["task"], return_format="structured_summary")
    # Coordinator receives only the summary, not verbose exploration output
    return {"task": task["subagent"], "findings": result["structured_findings"]}

Step 2. Implement scratchpad file management: agents write key findings (class names, file paths, dependency chains) to a known file and read it before subsequent exploration steps

Why: Scratchpad files are the primary mitigation for context degradation. They persist knowledge outside the conversation context, making it immune to the attention shift that causes the model to reference typical patterns instead of specific class names and file paths it discovered earlier.

You should see: An agent that writes structured findings to a scratchpad file after each exploration step and reads the scratchpad at the start of each subsequent step. The scratchpad should contain specific class names, file paths, and dependency chains, not summaries.

const SCRATCHPAD_PATH = "/tmp/exploration-scratchpad.md";

async function updateScratchpad(newFindings) {
  const existing = await readFile(SCRATCHPAD_PATH).catch(() => "");
  const updated = existing + "\n\n" + formatFindings(newFindings);
  await writeFile(SCRATCHPAD_PATH, updated);
}

function formatFindings(findings) {
  return `## ${findings.module}\n` +
    `- Class: \`${findings.className}\` (${findings.filePath})\n` +
    `- Implements: ${findings.interfaces.join(", ")}\n` +
    `- Dependencies: ${findings.dependencies.join(" -> ")}\n` +
    `- Critical: ${findings.criticalNote || "None"}`;
}

// Before each exploration step, read the scratchpad
const context = await readFile(SCRATCHPAD_PATH);

from pathlib import Path

SCRATCHPAD_PATH = Path("/tmp/exploration-scratchpad.md")


def update_scratchpad(new_findings: dict) -> None:
    existing = SCRATCHPAD_PATH.read_text() if SCRATCHPAD_PATH.exists() else ""
    SCRATCHPAD_PATH.write_text(existing + "\n\n" + format_findings(new_findings))


def format_findings(findings: dict) -> str:
    return (
        f"## {findings['module']}\n"
        f"- Class: `{findings['class_name']}` ({findings['file_path']})\n"
        f"- Implements: {', '.join(findings['interfaces'])}\n"
        f"- Dependencies: {' -> '.join(findings['dependencies'])}\n"
        f"- Critical: {findings.get('critical_note') or 'None'}"
    )


# Before each exploration step, read the scratchpad
context = SCRATCHPAD_PATH.read_text()

Step 3. Build summary injection logic: after Phase 1 exploration, summarise findings and inject the summary into Phase 2 subagent prompts

Why: Summary injection prevents the cold start problem where Phase 2 subagents duplicate Phase 1 exploration because they were not given previous findings. It ensures Phase 2 agents have the architectural understanding needed to ask the right questions without rediscovering the system structure.

You should see: A Phase 1 summary document that captures the high-level architecture, key concerns, and specific investigation targets for Phase 2. This summary is injected into the initial prompt of every Phase 2 subagent.

function buildPhase2Prompt(phase1Summary, phase2Task) {
  return `## Context from Phase 1 Exploration\n` +
    `Architecture: ${phase1Summary.architecture}\n` +
    `Key dependency chain: ${phase1Summary.dependencyChain}\n` +
    `Critical concern: ${phase1Summary.criticalIssue}\n\n` +
    `## Your Phase 2 Task\n${phase2Task}\n\n` +
    `Use the Phase 1 context to guide your investigation. Do not re-explore already-discovered architecture.`;
}

const phase1Summary = {
  architecture: "Layered: Controllers -> Services -> Repositories -> DB",
  dependencyChain: "RefundController -> RefundProcessor -> OrderService -> PaymentGateway",
  criticalIssue: "RefundProcessor has no retry logic for Stripe API failures"
};

def build_phase2_prompt(phase1_summary: dict, phase2_task: str) -> str:
    # Phase 2 subagents start with a fresh context window, so anything Phase 1
    # learned has to be written into this prompt or it is re-discovered.
    return (
        "## Context from Phase 1 Exploration\n"
        f"Architecture: {phase1_summary['architecture']}\n"
        f"Key dependency chain: {phase1_summary['dependency_chain']}\n"
        f"Critical concern: {phase1_summary['critical_issue']}\n\n"
        f"## Your Phase 2 Task\n{phase2_task}\n\n"
        "Use the Phase 1 context to guide your investigation. "
        "Do not re-explore already-discovered architecture."
    )


phase1_summary = {
    "architecture": "Layered: Controllers -> Services -> Repositories -> DB",
    "dependency_chain": "RefundController -> RefundProcessor -> OrderService -> PaymentGateway",
    "critical_issue": "RefundProcessor has no retry logic for Stripe API failures",
}

Step 4. Implement crash recovery: each agent exports structured state (explored paths, key findings, next steps) to a manifest file that the coordinator loads on resume

Why: Extended exploration sessions can fail from crashes, network interruptions, or context exhaustion. Without recovery mechanisms, all progress is lost. Structured state manifests enable the coordinator to resume from the last checkpoint rather than restarting from scratch.

You should see: A manifest file in JSON format containing the session ID, current phase, explored paths, key findings, and next steps. On resume, the coordinator loads this manifest and injects it into agent prompts so exploration continues from where it left off.

const MANIFEST_PATH = "/tmp/exploration-manifest.json";

async function saveManifest(state) {
  await writeFile(MANIFEST_PATH, JSON.stringify({
    sessionId: state.sessionId,
    phase: state.phase,
    exploredPaths: state.exploredPaths,
    keyFindings: state.keyFindings,
    nextSteps: state.nextSteps,
    lastUpdated: new Date().toISOString()
  }, null, 2));
}

async function resumeFromManifest() {
  const manifest = JSON.parse(await readFile(MANIFEST_PATH));
  console.log(`Resuming session ${manifest.sessionId} from phase ${manifest.phase}`);
  console.log(`Already explored: ${manifest.exploredPaths.length} paths`);
  console.log(`Next steps: ${manifest.nextSteps.join(", ")}`);
  return manifest;
}

import json
from datetime import datetime, timezone
from pathlib import Path

MANIFEST_PATH = Path("/tmp/exploration-manifest.json")


def save_manifest(state: dict) -> None:
    MANIFEST_PATH.write_text(
        json.dumps(
            {
                "session_id": state["session_id"],
                "phase": state["phase"],
                "explored_paths": state["explored_paths"],
                "key_findings": state["key_findings"],
                "next_steps": state["next_steps"],
                "last_updated": datetime.now(timezone.utc).isoformat(),
            },
            indent=2,
        )
    )


def resume_from_manifest() -> dict:
    manifest = json.loads(MANIFEST_PATH.read_text())
    print(f"Resuming session {manifest['session_id']} from phase {manifest['phase']}")
    print(f"Already explored: {len(manifest['explored_paths'])} paths")
    print(f"Next steps: {', '.join(manifest['next_steps'])}")
    return manifest

Step 5. Test context degradation by running an extended exploration session across multiple modules and verify that scratchpad files preserve specific class names and file paths that would otherwise degrade to generic descriptions

Why: This validates that the scratchpad mitigation actually works against context degradation. The observable symptom is the model referencing typical patterns instead of specific classes and paths. You need to confirm that scratchpad files prevent this degradation.

You should see: Two comparison runs: one without scratchpad files where the agent degrades to generic references after exploring 4-5 modules, and one with scratchpad files where the agent maintains specific class names and file paths throughout the entire session.

// Test without scratchpad
const withoutScratchpad = await exploreModules(5, { useScratchpad: false });
// Ask: "List all classes you discovered with their file paths"
// Expected: generic references like "a repository class" and "the service layer"

// Test with scratchpad
const withScratchpad = await exploreModules(5, { useScratchpad: true });
// Ask: "List all classes you discovered with their file paths"
// Expected: specific references like "OrderRepository at src/repos/order.ts"

// Measure specificity
function measureSpecificity(response) {
  const specificRefs = (response.match(/\b\w+\.ts\b/g) || []).length;
  const genericRefs = (response.match(/typical|standard|common pattern/gi) || []).length;
  return { specificRefs, genericRefs, ratio: specificRefs / (genericRefs + 1) };
}

import re

# Test without scratchpad
without_scratchpad = explore_modules(5, use_scratchpad=False)
# Ask: "List all classes you discovered with their file paths"
# Expected: generic references like "a repository class" and "the service layer"

# Test with scratchpad
with_scratchpad = explore_modules(5, use_scratchpad=True)
# Ask: "List all classes you discovered with their file paths"
# Expected: specific references like "OrderRepository at src/repos/order.ts"


# Measure specificity
def measure_specificity(response: str) -> dict:
    specific_refs = len(re.findall(r"\b\w+\.ts\b", response))
    generic_refs = len(re.findall(r"typical|standard|common pattern", response, re.I))
    return {
        "specific_refs": specific_refs,
        "generic_refs": generic_refs,
        "ratio": specific_refs / (generic_refs + 1),
    }

Appendix B — Interactive Study Prompts

Two prompts to paste into Claude. B1 drills the judgement the exam actually measures; B3 reviews the work you produced for the Build Exercise above. The exam simulator between them is the interactive quiz on this page.

B1. Concept Check — Discrimination Drill

B2. Exam Simulator

B3. Build Coach — Code Review

The Build Exercise and its hint ladder are already on this page. This prompt is for the one thing the page cannot do: review the code and the artefacts you actually produced.