Chapter 4: Agent: Stop telling AI what to read. Let it decide.
This introduction explains why agents should investigate narrow, concrete questions after a workflow maps the codebase, then preview tracing, testing, running, and documenting their findings.
After this chapter you will be able to
- Agent context-loop tradeoff. Explain how an agent’s decide-act-observe loop uses one shared context window across its actions, and why following files, grepping, backtracking, and observing results consumes the capacity available for deep reasoning.
- Narrow deep agent questions. Distinguish broad codebase-mapping questions from narrow, deep investigation questions, and describe why agents are best used to zoom into one area after a workflow has already built a map.
- Broad agent mapping limits. Explain why asking an agent for the core abstractions and overall architecture can produce a convincing-looking catalog without a meaningful explanation of what those abstractions do.
- Single-window context competition. Describe how an agent's single context window must serve navigation, comprehension, and overhead, and explain why this competition pushes a broad investigation toward breadth instead of depth.
- Workflow and agent task split. Distinguish the jobs suited to workflows from those suited to agents: use a systematic workflow for broad, predictable architectural questions, and use an agent for the long tail of focused, specific questions.
- Focused agent flow tracing. Explain why a single concrete flow question is a better use of an agent's context budget than asking it to broadly scan files. Describe how the agent can start with only the question, search for an entry point, follow calls and imports, recover from dead ends, and assemble a cross-file trace.
- VS Code file-opening pipeline. Trace the path from clicking a file in the VS Code Explorer to text appearing in the editor. Describe the major layers: the Explorer click handler, editor-service resolution and delegation, editor-group and pane handling, file loading and decoding, and Monaco model attachment and rendering.
- Understanding test purpose. Explain that an understanding test encodes one specific claim from a mental model of system behavior, rather than serving as a coverage-oriented unit test. State that a passing test supports the model, while a failing test reveals something the system actually does that code reading alone missed.
- Cleanup before validation. Trace why a URI with a missing leading slash does not always throw: for http and file schemes, the URI constructor cleans up the path by prepending a slash before validation runs. Distinguish custom schemes, which skip that automatic cleanup and can therefore trigger the validator's error.
- Agent-driven setup recovery. Explain how an agent handles a failed build by reading the error, checking repository configuration again, and retrying with the corrected environment. Use the VS Code example to describe how the agent connected a tree-sitter compilation failure to the Node version specified in .nvmrc.
- Cold-clone build sequence. Describe the sequence that takes a fresh VS Code clone to a running development build: install dependencies with the correct Node version, compile, and run the launch script. State that successful compilation and an opened application establish more evidence than a single isolated test.
- Runtime ground truth. Explain what observing a running system reveals that static code reading, traces, and isolated tests cannot: actual processes, communication, activation order, and runtime security boundaries. Describe the VS Code examples of main, renderer, and extension-host processes communicating over IPC, extension activation order, or Content Security Policy warnings.
- Two-tier skill-file memory. Explain why the agent maintains two skill files: a repository-level file for facts learned about the current codebase and a global file for reusable lessons that apply across projects.
- End-of-session update ritual. Describe the end-of-session practice of asking the agent to add short, high-signal findings to the appropriate skill files, merging evidence from traces, tests, builds, and prior architectural work.
What it builds on
- What's an agent? (chapter 2) · the distinction between an agent and other AI-assisted approaches
- Analyze: The overview-then-zoom-in pattern (chapter 3) · using staged analysis to understand a codebase
- Turn any codebase into a tutorial for $2 (chapter 3) · the workflow that turns a codebase into a tutorial
- Swap the instructions, change the output (chapter 3) · choosing questions and lenses for different layers
- What the LLM sees determines everything (chapter 3) · The principle that what the LLM sees determines the quality of its output.
- What's a workflow? (chapter 2) · The idea of a workflow as a structured process.
- Chained together, each tool covers the next one's weakness (chapter 2) · The idea that chained tools can cover one another's weaknesses.
- The pattern that scales (chapter 3) · The scalable overview-then-zoom-in workflow pattern.
Section by section
Introduction
This introduction explains why agents should investigate narrow, concrete questions after a workflow maps the codebase, then preview tracing, testing, running, and documenting their findings.
- Agent context-loop tradeoff: Explain how an agent’s decide-act-observe loop uses one shared context window across its actions, and why following files, grepping, backtracking, and observing results consumes the capacity available for deep reasoning.
Why it matters: This explains why an agent’s flexibility can become a weakness when it explores too much code. - Narrow deep agent questions: Distinguish broad codebase-mapping questions from narrow, deep investigation questions, and describe why agents are best used to zoom into one area after a workflow has already built a map.
Why it matters: Using an agent for the right scope avoids shallow summaries and turns its exploratory behavior into useful investigation. - Evidence and persistent learning: Describe the chapter’s planned method for deepening and preserving understanding: trace a concrete flow, use tests and a build or run to check what reading missed, and save findings in a skill file for future agent sessions.
Why it matters: These steps replace unverified guesses with evidence and prevent each new agent session from starting from zero.
Key terms: decide-act-observe loop, context window, shared window, workflow, agent, broad, shallow questions, narrow, deep questions, key abstractions, flow trace, understanding test
4.1 Broad questions: Your agent skimmed 25 files and missed everything
This section explains why broad architecture-mapping prompts make agents skim shallowly, and why workflows should handle predictable deep questions while agents handle focused, specific ones.
- Broad agent mapping limits: Explain why asking an agent for the core abstractions and overall architecture can produce a convincing-looking catalog without a meaningful explanation of what those abstractions do.
Why it matters: A broad answer can sound accurate while leaving you unable to connect code abstractions to visible product behavior. - Single-window context competition: Describe how an agent's single context window must serve navigation, comprehension, and overhead, and explain why this competition pushes a broad investigation toward breadth instead of depth.
Why it matters: Knowing where the context budget goes helps you recognize when an agent is skimming rather than genuinely tracing an implementation. - Workflow and agent task split: Distinguish the jobs suited to workflows from those suited to agents: use a systematic workflow for broad, predictable architectural questions, and use an agent for the long tail of focused, specific questions.
Why it matters: Choosing the right tool shape prevents you from wasting an agent on a task a staged workflow can complete more deeply.
Key terms: broad mapping prompt, core abstractions, overall architecture, catalog of declarations, Language Intelligence, single context window, navigation, comprehension, overhead, context budget
4.2 Flow trace: One question, 15 files, zero guidance
This section shows how a single focused end-to-end question lets an agent autonomously trace a behavior across many files and reveal the codebase layers and shared gateways involved.
- Focused agent flow tracing: Explain why a single concrete flow question is a better use of an agent's context budget than asking it to broadly scan files. Describe how the agent can start with only the question, search for an entry point, follow calls and imports, recover from dead ends, and assemble a cross-file trace.
Why it matters: A focused trace gives you an actionable model of one behavior instead of a shallow inventory of names. - VS Code file-opening pipeline: Trace the path from clicking a file in the VS Code Explorer to text appearing in the editor. Describe the major layers: the Explorer click handler, editor-service resolution and delegation, editor-group and pane handling, file loading and decoding, and Monaco model attachment and rendering.
Why it matters: Knowing the layers tells you where to investigate when opening, loading, tab, or rendering behavior breaks. - Shared opening gateway and boundaries: Explain the architectural boundaries revealed by the trace: multiple opening entry points converge on editorService.openEditor(), common interfaces are separated from browser implementations, and raw file bytes are handled separately from text decoding and rendering. State how these boundaries support alternate editors, file-system providers, remotes, and changes in one layer without changing unrelated layers.
Why it matters: Shared gateways and separated responsibilities show you where a change belongs and which parts should remain unaffected.
Key terms: agent, context budget, flow trace, linear walkthrough, grep, ExplorerView, tree.onDidOpen, editorService.openEditor, IEditorService, EditorGroupView
4.3 Understanding tests: One failure taught more than 25 successes
This section shows how an agent can write and run understanding tests to verify a code-reading hypothesis and expose behavior hidden in execution order.
- Understanding test purpose: Explain that an understanding test encodes one specific claim from a mental model of system behavior, rather than serving as a coverage-oriented unit test. State that a passing test supports the model, while a failing test reveals something the system actually does that code reading alone missed.
Why it matters: Understanding tests turn your interpretation of unfamiliar code into a checkable claim about real behavior. - Cleanup before validation: Trace why a URI with a missing leading slash does not always throw: for http and file schemes, the URI constructor cleans up the path by prepending a slash before validation runs. Distinguish custom schemes, which skip that automatic cleanup and can therefore trigger the validator's error.
Why it matters: The key surprise is often not inside either function, but in the order in which functions transform data. - Execution as behavioral evidence: Describe why accurately reading individual functions can still produce a wrong outcome prediction when the important behavior lies at their seam. State the confidence progression in this section: chat says what code says, traces show how code connects, and understanding tests check whether the machine's execution matches the mental model.
Why it matters: Running a focused test closes the gap between plausible source interpretation and the sequence the machine truly executes.
Key terms: understanding test, mental model, hypothesis, URI.from(), URI constructor, validator, cleanup, validation, http scheme, execution trace
4.4 Build and run: Ground truth over guesses
This section shows how an agent can build and launch an unfamiliar codebase, recover from setup failures, and use the running system as ground truth for understanding it.
- Agent-driven setup recovery: Explain how an agent handles a failed build by reading the error, checking repository configuration again, and retrying with the corrected environment. Use the VS Code example to describe how the agent connected a tree-sitter compilation failure to the Node version specified in .nvmrc.
Why it matters: This lets you delegate frustrating environment setup work while still reaching a trustworthy running system. - Cold-clone build sequence: Describe the sequence that takes a fresh VS Code clone to a running development build: install dependencies with the correct Node version, compile, and run the launch script. State that successful compilation and an opened application establish more evidence than a single isolated test.
Why it matters: A repeatable path from clone to running application gives you a concrete baseline before investigating deeper behavior. - Runtime ground truth: Explain what observing a running system reveals that static code reading, traces, and isolated tests cannot: actual processes, communication, activation order, and runtime security boundaries. Describe the VS Code examples of main, renderer, and extension-host processes communicating over IPC, extension activation order, or Content Security Policy warnings.
Why it matters: Runtime observation turns architectural claims into visible behavior and exposes facts that code alone can leave uncertain. - Agent patience advantage: State why agents are especially useful for cold-start setup: they can persist through repetitive environment errors and yak-shaving without frustration, leaving the developer free to observe and investigate the running application.
Why it matters: The value is not magical expertise but sustained execution of tedious steps that often stop human investigation early.
Key terms: failed build, error, .nvmrc, Node version, tree-sitter, nvm install, fresh clone, npm install, npm run compile, ./scripts/code.sh
4.5 Skill file: Make the agent document what it learned
This section establishes persistent agent memory through separate local and global skill files that capture discoveries and reusable codebase-reading methods after every session.
- Two-tier skill-file memory: Explain why the agent maintains two skill files: a repository-level file for facts learned about the current codebase and a global file for reusable lessons that apply across projects.
Why it matters: Separating local facts from portable methods prevents repeated rediscovery while keeping advice useful in every future repository. - Persistent context mechanics: Describe how a skill file gives an agent memory between sessions by being loaded at startup, including the Claude Code locations and names given in this section.
Why it matters: A useful record only prevents rediscovery if the agent receives it automatically when the next session begins. - End-of-session update ritual: Describe the end-of-session practice of asking the agent to add short, high-signal findings to the appropriate skill files, merging evidence from traces, tests, builds, and prior architectural work.
Why it matters: Updating the files after each run turns isolated investigation results into compounding understanding and preserves the context budget for the next real question.
Key terms: skill file, codebase-specific file, global agent config, portable file, CLAUDE.md, .cursorrules, repository root, ~/.claude/CLAUDE.md, end-of-session prompt, high-signal
4.6 Summary
This summary presents a focused, evidence-driven agent workflow that compounds codebase understanding through tests, running systems, and a persistent skill file.
Where this is used later
- Trace one user action across services (chapter 8) · Tracing a user action across services uses the same end-to-end tracing approach.
- Trace one endpoint from request to response (chapter 8) · Endpoint tracing similarly follows an interaction through successive implementation layers.
- Read what the code admits that the marketing won't (chapter 5) · Reading what code admits requires recognizing architectural choices and the product capabilities they enable.
- A schema's shape changes with the kind of codebase (chapter 7) · Understanding how a codebase's shape reflects its purpose depends on noticing responsibility boundaries.
- An architecture is a graph of programs and the wires between them (chapter 9) · Architecture as programs and wires builds on identifying components and the connections between them.
- Open each box to its real tech stack (chapter 9) · Opening architectural boxes to their real stacks requires distinguishing their concrete implementations and roles.
- Ask for the product in one "It's X, but Y" sentence (chapter 5) · The product-intent question becomes a reusable rule that belongs in the global skill file.
- Ask the LLM to draw the schema and tour it (chapter 7) · Schema-reading guidance can be accumulated as a reusable method in the global skill file.
Concepts explained in this chapter
- AI agentAn AI agent is a software system that uses artificial intelligence to pursue tasks through autonomous or semi-autonomous actions.
- pipelineA workflow is a repeatable sequence of predefined steps that systematically transforms inputs into consistent outputs.
- context windowA context window is the finite token capacity available to a language model for processing input, tool results, and generated reasoning or output.
- skill fileA skill file is a configuration or instruction file that records reusable capabilities and guidance for an AI-assisted workflow.
- editor service gatewayAn editor service gateway is a central editor operation that selects an editor, target group, and opening action for a resource.
- understanding testAn understanding test is a test designed to verify whether a person's mental model of a software system matches its actual behavior.
- language intelligenceLanguage intelligence is a set of programming-language services that provide features such as completion, definition navigation, and diagnostics.
- provider interfaceA provider interface is an interface that allows an editor or language service to supply a specific language-related capability.
- mental modelA mental model is an internal conceptual representation of a system, its structure, and its behavior.
These guides are generated from the text of Manning books by Manning's knowledge graph and link to the sections they draw on. The full books are available on liveBook and at manning.com.
