The Coding Agent

Where Chapter 4's teaching agent explains without acting, a coding agent is the opposite: a general-purpose delegate for actual implementation work — writing new code, modifying existing code, and verifying that what it produced actually works. This chapter covers designing one, briefing it with a genuinely usable spec, and reviewing what it hands back before trusting it's done.

Designing a Coding Agent's Definition

A coding agent's description should point at implementation work with a reasonably clear scope: "Use this agent for a well-defined implementation task — adding a feature, fixing a specific bug, or making a scoped code change. Not for open-ended research or vague 'improve this' requests without a clear target." Tool access is necessarily much broader than the teaching agent's — Read, Edit, Write, Grep, and typically Bash (so it can run the code or tests it writes and confirm the result works, rather than just assuming it does). Model choice should favor the most capable model available — correctness in real implementation work matters more than speed here.

Writing the System Prompt for a Coding Agent

A coding agent's system prompt should instruct it to:

• Follow the existing codebase's own conventions and style rather than introducing a different pattern
• Avoid adding abstractions, features, or refactoring beyond what the task actually asked for
• Verify its own change actually works — run the relevant tests or build, don't just assume the edit is correct
• Flag genuine ambiguity rather than silently guessing and proceeding on an assumption

Briefing a Coding Agent Well

Chapter 3's brief-writing principles apply here directly, with implementation work adding one more requirement: acceptance criteria — a concrete way to know the task was actually done correctly, not just attempted. A brief that says "add validation to the signup form" is vaguer than one that says exactly what should be validated and how a failure should be shown to the user.

A Worked Example

A well-scoped brief: "Add input validation to the signup form in src/forms/signup.ts. Email must match a standard email pattern; password must be at least 8 characters. Show a clear, field-specific error message when either check fails. Don't change the form's overall structure, layout, or styling — only the validation logic and the error messages." This gives the agent a specific target file, exact validation rules, a defined success condition (clear per-field errors), and an explicit boundary (don't touch structure or styling) — everything it needs to implement the task correctly without guessing at scope.

Reviewing What a Coding Agent Hands Back

Chapter 3's warning about trusting a final report over the actual result applies with particular force here: implementation work is exactly the kind of consequential task that deserves real verification, not just acceptance of a confident-sounding summary. Review the actual diff, confirm it matches what was asked for, and check that anything outside the requested scope wasn't quietly touched along the way.

Hands-On Exercises