4 Agent: Stop telling AI what to read. Let it decide.
This chapter covers
- How an AI agent's decide-act-observe loop works
- Scoping a prompt so an agent goes deep, not broad
- Having an agent trace a flow across 15 files with zero guidance
- Writing an understanding test to verify your mental model
- Giving an agent persistent memory with a skill file
Ask an AI agent like Cursor or Claude Code to map an entire codebase, and you'll get a worse answer than a two-dollar script can give you. Point one at VS Code and ask for the architecture, and it might read 25 files, skim 80 lines each, and return a list of type signatures, less useful than the summary we built in chapter 3. This is a mismatch between the tool and the job, rather than a defect in the agent.
The difference between a workflow and an agent is the context window. A workflow runs a fixed pipeline where each step is a fresh slate. An agent decides its next move in a loop (read context, decide action, execute, see result, repeat), and every step draws from the same, shared window. When Claude Code greps a class name, reads the file, follows an import, hits a dead end, and backtracks, each of those actions eats context. This flexibility is its power, but the more files it opens, the less capacity it has to think deeply about any one of them.