The Planning/Architecture Agent

Chapter 5 specialized code review toward security. This chapter covers a different kind of specialization entirely: an agent whose job is to think through how something should be built — before any implementation begins — and produce a reviewable plan rather than working code.

What a Planning/Architecture Agent Actually Produces

A planning agent's output is a structured plan: the proposed approach, which files or areas of the codebase will be touched, the key architectural tradeoffs actually considered and the reasoning behind the recommended choice, and any genuinely open questions or risks. It does not produce the implementation itself — that's Fundamentals' Chapter 5's own coding agent's job, once a plan exists to actually implement.

Why Separate Planning From Implementation

Committing straight to an implementation approach without thinking it through first risks real wasted work if that approach turns out to be wrong partway through building it. Keeping planning as its own separate, reviewable step — proposing an approach, getting it reviewed and approved, then implementing — catches a flawed approach while it's still just a written plan, cheap to revise, rather than after a real implementation has already been built around it. This is the same underlying logic as reviewing code before merging it, applied one step earlier in the process.

Designing a Planning Agent's Definition

"Use this agent to design an implementation approach for a non-trivial feature or change before any code is written — identifying the files involved, the architectural approach, and the key tradeoffs. Not for writing the actual implementation." Tool access should stay read-only — Read, Grep, Glob, no Edit or Write — for the same reason a review agent stays read-only: keeping the plan itself as a discrete, reviewable proposal, rather than an agent that quietly starts implementing while it's supposed to be planning.

Writing the System Prompt for a Planning Agent

A planning agent's system prompt should instruct it to actually understand the existing codebase's own relevant conventions before proposing anything — a plan disconnected from how the codebase already works isn't genuinely useful — to name real tradeoffs explicitly rather than presenting one option as though it were the only possibility, and to flag genuine open questions or risks honestly rather than glossing over uncertainty to make the plan look more complete than it really is.

Briefing a Planning Agent Well

A good brief states the actual goal, any known constraints (must integrate with an existing system, can't change a specific public interface), and how much freedom the agent actually has — a genuinely open architectural question versus "given we've already decided on approach X, plan the specifics of implementing it."

A Worked Example

"We need to add real-time notifications to the app. Plan the approach — consider WebSockets, Server-Sent Events, and polling, and identify the tradeoffs between them for our specific situation: mostly one-way server-to-client updates, a moderate number of concurrent users. Don't implement anything yet — just produce the plan for review." This states the actual goal, names the specific options worth weighing, gives the real constraints that should inform the choice, and explicitly confirms this is a planning task, not an implementation one.

Hands-On Exercises