5.4 - Codebase Exploration & Context Degradation

Build exercise: Build a Context-Resilient Codebase Explorer

Advanced · 60 minutes

You'll practice:

• Recognise context degradation as an attention quality problem, not a token limit problem
• Implement scratchpad files to persist key findings outside the conversation context
• Use subagent delegation for context isolation, not just parallelisation
• Design crash recovery via structured state manifests for session resilience
• Apply summary injection between exploration phases to prevent cold start duplication

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

   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.

   Hints

   1. Define 3-4 specific investigation tasks, each narrow enough for a single subagent to handle without filling its own context.

   2. Each subagent should return structured data (class names, file paths, findings), not the raw file contents it read during exploration.

   3. 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 };
      }

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

   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.

   Hints

   1. The scratchpad should be a Markdown file with clear sections for key classes, dependency chains, and critical findings. Write to it after each major discovery.

   2. This is a deliberate strategy, not a fallback. Agents should be instructed to maintain scratchpad files from the start of any extended exploration session.

   3. 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);

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

   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.

   Hints

   1. The summary should include the architectural overview, dependency chains discovered, and the specific Phase 2 objective for each subagent.

   2. Keep the summary concise and structured. Phase 2 subagents need context, not the full verbose output from Phase 1.

   3. 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"
      };

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

   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.

   Hints

   1. The manifest should be updated after every significant exploration step, not just at the end of a phase. Frequent checkpointing minimises lost work on crash.

   2. Include a nextSteps array so the resumed session knows exactly what to investigate next without re-analysing the findings.

   3. 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;
      }

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

   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.

   Hints

   1. Look for the specific degradation symptom: the agent saying this follows the typical repository pattern instead of the OrderRepository class at src/repos/order.ts implements Repository<T>.

   2. After exploring 5+ modules, ask the agent to list all classes it discovered with their file paths. Without scratchpad files, it will miss or generalise. With scratchpad files, it will reference the file for accurate details.

   3. // 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) };
      }