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
Links
- Builds on: Running a coding agent, Decomposing work
- Leads to: Plan, implement, verify
- Competencies drawing on it: Specifies work well enough for an agent to implement and for anyone to verify
Lessons
- Deciding whether to build it at all (explanation)
- Splitting the work into components the agent can build one at a time (tutorial)
Your reference
Each lesson above adds its takeaways and its example here once you finish it. Your reference lists every lesson you have finished.
Deciding whether to build it at all
Unlocks when you finish Deciding whether to build it at all.
Takeaways
- A request names a solution. Find the problem behind it and the person who has it before you propose a change. Then write the alternatives down, including doing nothing.
- Price a change by what the team owns after it ships, and the hour the agent spends writing it is the smaller part. A dependency for one format is patched for years.
- Building as asked is one outcome. A request can also be shrunk to the part that solves the stated problem, or answered without code.
- Success criteria are observable outcomes a person other than the author could check, and they include what must keep working.
- End the criteria with an out-of-scope line, because the agent fills the gap between done and everything it could improve with its own choices.
Example
This lesson has no runnable example or prompt block.
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.
Takeaways
- A component has one responsibility, an interface that fits in a sentence, and a size that fits one agent session and one reviewable change. Cut where the data changes form.
- Dependencies set the build order. The component whose output the others take is built and checked first, so a mistake in it never reaches the next one unseen.
- A component checked alone is a fixed point for the next brief. Feed the next component's test what the first one produces, or the second inherits and hides the first one's mistakes.
- Write the acceptance test before the component exists, put it in the suite and name the test run in the brief as what done means.
- A check that passes on a stub doesn't check the work. Run it against a version with the right name and no work, and the line must still say it failed.
Example
Show the list · open in the lesson
Run this, and compare what you see with the output below.
python3 todo.py listPrints the lines below (verified in CI from site/examples/coding-with-agents/decomposing-the-work/list.py)
1. [ ] Buy milk 2. [x] Call the plumber 3. [x] Renew the passport 4. [ ] Water the plants 2 open, 2 done
Sources
Brilliant TASTaste: what is worth building, Brilliant, Coding with AI skills map (reference)Brilliant SPCSpecification and design, Brilliant, Coding with AI skills map (reference)Academy ai-native-sdlc-playbookThe AI-native SDLC playbook, Claude Academy (course)Academy ai-fluency-for-buildersAI Fluency for builders, Claude Academy (course)