CHAPTER 13 · MASTERY

Driving Coding Agents

The previous twelve chapters gave you mental models and vocabulary. This one assembles them into a repeatable workflow: how to turn fuzzy intent into a spec an agent can execute precisely, where to step in, and how to review output efficiently. The goal is for you to always hold the direction and the pace, instead of being pushed along by whatever the agent produces.

Opening: two developers, one feature

Where the answer lies: A is making the agent guess the requirements by trial and error, exposing one hidden requirement per round; B said the hidden requirements out loud before starting: filter state in the URL (shareable, survives refresh), don't touch pagination, and what "done" means. Agents execute extremely well, but they can't read requirements you never stated. B's 15 minutes weren't "writing docs" — they were design, which is your core job in the agent era.

The workflow at a glance

① Explore: have the agent investigate before it touches anything

For unfamiliar code or complex changes, the first instruction should be "investigate and report", not "implement". For example: "How does the list page load its data? Where do filter and pagination state live? Read only, change nothing, give me a short report." It's cheap, and it exposes your own wrong assumptions.

② Spec: your core output

See the six-element template in the next section.

③ Plan: reject the wrong direction when it's cheapest

Have the agent produce a plan before writing code (many tools have a dedicated "plan mode"). Reviewing a plan is ten times cheaper than reviewing code. Ask of the plan:

• Do the files it intends to touch match what I expected? Anything out of scope?
• Any data-model changes, new dependencies, DB migrations? Those need my explicit OK.
• Are security aspects (auth, validation) covered?
• What's the test plan? How will it prove it's done?

④ Implement: small, verifiable, committable steps

Cut work into vertical slices: each slice is the smallest end-to-end runnable piece ("first make the URL param filter the list; no UI yet"), rather than "all DB code, then all endpoints, then all UI". Run checks and commit after each slice. If something breaks, you roll back one small step.

⑤ Verify: let the machines check first

Chapter 10's Definition of Done kicks in here: the agent may only say "done" when type checks, lint and tests all pass. For UI, open the preview link and click through yourself — nothing automated replaces that.

⑥ Review → ⑦ Merge → ⑧ Capture

Review method below. After merging, spend one minute asking: what did I have to tell the agent more than once? Write it into AGENTS.md or turn it into a test or lint rule. Every correction should happen only once.

The six elements of a task description

A description like this takes 10–15 minutes. It forces you to decide first: where state lives, which layer filters, what the edge cases are. Leave those decisions for the agent to make implicitly and you get A's two hours.

Precise language: from symptom to term

What you observe is usually a "symptom"; what the agent needs is a "direction for diagnosis". This table maps common vague descriptions to precise expressions from earlier chapters. Fluency with these words is the most direct lever you have over an agent:

Note the word "likely". These expressions are hypotheses, not conclusions. The good move is to give the agent both the symptom and your hypothesis, and require it to verify first: "I suspect a request race; add logging first to confirm the order requests are sent and returned, then fix it."

Reviewing agent output

Reviewing a design

When an agent hands you a design doc or technical proposal, the point isn't polished prose but:

• Requirement coverage: does every acceptance criterion map to an implementation approach?
• Data model: are new tables / fields sensible? Will changing them later be painful?
• Failure modes: what happens on network failure, LLM timeout, double submission, concurrent edits?
• Alternatives: which other approaches did it consider, and why not them? — if none, ask: "Give me two alternatives and the trade-offs."
• Over-engineering: abstraction layers, plugin systems or generic frameworks built for imagined future needs?

Reviewing code: a 10-minute checklist

Don't start reading line by line from the first file. Go from highest information density down:

1. Scope of change: does the list of modified files match expectations? Anything from the "don't" list touched?
2. Data structures: schemas, type definitions, Zod schemas, DB migrations. They decide the shape of everything else.
3. Tests: do they cover the acceptance criteria? Were existing tests modified (Chapter 10)?
4. Boundaries: is external input validated? Is the authorization condition there? Did secrets leak into client code?
5. Search for red flags: any, as, !, @ts-ignore, eslint-disable, empty catch, new dependencies, useEffect.
6. Core logic last: by now you know what it should look like, so it reads much faster.

Controlling the pace

When to step in

• Three failed attempts at the same problem: stop. Don't say "try again". Ask the agent for hypotheses and evidence, or look at the error yourself. Letting it keep guessing only makes the context messier.
• It starts changing things outside the described scope: point it out immediately and ask for a revert.
• It proposes turning off checks, skipping tests, adding dependencies: all need your explicit approval.
• The diff is too big to want to read: the task was cut too large. Roll back, slice smaller, retry.

Collaborating on debugging

The key: give evidence, ask for hypotheses, verify before changing. That turns the agent from "guess a fix" into "run a small scientific experiment".

When to do it yourself

A one-line config change, a small bug you already know how to fix, UI tweaks that need taste — doing it yourself is often faster than describing it to an agent. You don't have to use an agent for everything.

Running in parallel

Once fluent, you can run several agents on independent tasks at once (one building a feature, one adding tests, one investigating a performance issue), each on its own git worktree or branch. The precondition: the tasks really are independent and you have the bandwidth to review everything — your review capacity is always the bottleneck of parallelism.

Writing AGENTS.md well

• Short and specific: it occupies context in every session. Write "use pnpm", not an essay on package managers.
• Write what the agent can't guess: project-specific conventions, known pitfalls, prohibitions. Generic framework knowledge doesn't belong.
• Point, don't copy: "DB conventions: see docs/db.md" lets the agent read it when needed.
• Layer it: global conventions at the root; local ones in subdirectories (e.g. apps/api/AGENTS.md).
• Keep it alive: update it whenever you notice a repeated correction; delete lines that go stale.

How the tools differ Aware

Claude Code, Codex CLI, pi, Cursor and IDE agents share the same underlying principles (Chapter 12), and this chapter's methods apply to all of them. The differences are mostly in harness philosophy: some ship rich built-ins (plan mode, subagents, hooks, plugin marketplaces, cloud runs), others are deliberately minimal and let you assemble what you need via extensions. When choosing, look at: model support, the project-instructions file convention, permission granularity, whether it can run unattended (CI, batch jobs), and whether you like how it feels. No need to chase every new tool — the workflow and your ability to express yourself are the assets that transfer.

Anti-patterns

Self-check