Skip to content
AI Training

Deciding and specifying

Coding with agents · topic coding-with-agents/specification

When an agent does the implementing, the engineer's skill concentrates before the code: judging whether something is worth building, defining what success requires, breaking the problem into components with clear dependencies, and designing how the result will be verified before any of it exists.

Concepts

What is worth building
Judging an idea before building it: who needs it, what it costs to build and to keep, what it displaces, and what happens if it is not built. Cheap implementation makes this judgment more important, not less, because the cost of building the wrong thing is now mostly the cost of maintaining it. Say no, or say smaller, before the agent starts. glossary
Success criteria
Concrete, checkable statements of what a finished result must do and must not do, written before the work starts. Good criteria describe observable behavior, name the edge cases that matter and set limits such as performance or compatibility. They become the agent's target and the reviewer's checklist, and they stop a plausible result from being accepted as a correct one. glossary
Decomposition into components
Splitting a problem into parts with clear responsibilities and interfaces, each small enough to build and verify on its own. Good components can be implemented in any order that respects their dependencies, tested in isolation and replaced without touching the rest. The split is a design decision the engineer owns; agents follow it well and invent it poorly. glossary
Dependencies
The relationships that force an order: which component needs another to exist first, which decision has to be made before a piece can be specified, which external system must be available. Naming dependencies early sets the sequence of work, shows what can proceed in parallel and exposes the risky assumption that everything else rests on. glossary
Designing the verification
Deciding how each piece of work will be checked before it is built: which tests must pass, what to observe in the running system, which review questions to ask. Designing the check first makes the criteria precise, gives the agent a target it can run itself, and keeps verification from being replaced by a glance at a diff that looks right. glossary
Design interview
Having the agent question the engineer about a feature before any plan is written. The agent asks about the implementation, edge cases, concerns and trade-offs, skips the obvious, and keeps going until the open points are settled, then writes the result down as a specification. The questions bring out decisions the engineer had not made yet, while changing them costs nothing. The written spec lets a fresh session build the design without the interview in its context. glossary
Throwaway prototype
A small program built only to answer one design question, such as whether a library can handle the data or which of two interfaces reads better, and deleted once the question is answered. It skips error handling, tests and structure, because none of its code is kept. With an agent a prototype is cheap, so trying an idea can replace a long discussion of it. The answer goes into the specification, and the prototype's code stays out of the real system. glossary
Shared vocabulary
One agreed meaning for each term of the problem domain, used the same way by domain experts, engineers, specifications, code and agent instructions. When the spec says "account" and the code says "customer" for the same thing, an agent has to guess whether the two differ, and some of its guesses are wrong. A short glossary the agent reads keeps the terms aligned, and renaming a term is a change to the design. glossary

Lessons

Your reference

Each lesson above adds its takeaways and its example here once you finish it. Your reference lists every lesson you have finished.

Let the agent interview you

Unlocks when you finish Let the agent interview you.

Deciding whether to build it at all

Unlocks when you finish Deciding whether to build it at all.

Splitting the work into components the agent can build one at a time

Unlocks when you finish Splitting the work into components the agent can build one at a time.

A prototype you throw away

Unlocks when you finish A prototype you throw away.

Sources