# Deciding and specifying

> 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.

Page: https://schubergphilis.github.io/ai-training/topics/coding-with-agents/specification/
License: CC BY-SA 4.0, https://creativecommons.org/licenses/by-sa/4.0/

*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](https://schubergphilis.github.io/ai-training/glossary/#what-is-worth-building)
- **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](https://schubergphilis.github.io/ai-training/glossary/#success-criteria)
- **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](https://schubergphilis.github.io/ai-training/glossary/#decomposition-into-components)
- **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](https://schubergphilis.github.io/ai-training/glossary/#dependencies)
- **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](https://schubergphilis.github.io/ai-training/glossary/#designing-the-verification)
- **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](https://schubergphilis.github.io/ai-training/glossary/#design-interview)
- **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](https://schubergphilis.github.io/ai-training/glossary/#throwaway-prototype)
- **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](https://schubergphilis.github.io/ai-training/glossary/#shared-vocabulary)

## Links

- **Builds on:** [Running a coding agent](https://schubergphilis.github.io/ai-training/topics/coding-with-agents/first-session/), [Decomposing work](https://schubergphilis.github.io/ai-training/topics/using-agents/decomposition/)
- **Leads to:** [Plan, implement, verify](https://schubergphilis.github.io/ai-training/topics/coding-with-agents/workflow/)
- **Competencies drawing on it:** [Specifies work well enough for an agent to implement and for anyone to verify](https://schubergphilis.github.io/ai-training/competencies/coding-with-agents/specifies-work/)

## Lessons

- [Let the agent interview you](https://schubergphilis.github.io/ai-training/coding-with-agents/agent-interviews-you/) (tutorial)
- [Deciding whether to build it at all](https://schubergphilis.github.io/ai-training/coding-with-agents/deciding-what-to-build/) (explanation)
- [Splitting the work into components the agent can build one at a time](https://schubergphilis.github.io/ai-training/coding-with-agents/decomposing-the-work/) (tutorial)
- [A prototype you throw away](https://schubergphilis.github.io/ai-training/coding-with-agents/prototype-to-throw-away/) (tutorial)

## Sources

- `Brilliant TAS` Taste: what is worth building, Brilliant, Coding with AI skills map (reference)
- `Brilliant SPC` Specification and design, Brilliant, Coding with AI skills map (reference)
- `Academy ai-native-sdlc-playbook` [The AI-native SDLC playbook](https://academy.claude.com/courses/ai-native-sdlc-playbook), Claude Academy (course)
- `Academy ai-fluency-for-builders` [AI Fluency for builders](https://academy.claude.com/courses/ai-fluency-for-builders), Claude Academy (course)
- `Claude Code best practices` [Best practices for Claude Code](https://code.claude.com/docs/en/best-practices), Claude Code documentation (reference)
- `Thomas 2019` The Pragmatic Programmer: Your Journey to Mastery, 20th Anniversary Edition, Addison-Wesley, 2019 (book)
- `Artima tracer bullets` [Tracer Bullets and Prototypes: A Conversation with Andy Hunt and Dave Thomas, Part VIII](https://www.artima.com/articles/tracer-bullets-and-prototypes), Artima Developer, 2003 (reference)
- `Brooks 1995` The Mythical Man-Month: Essays on Software Engineering, Anniversary Edition, Addison-Wesley, 1995 (book)
- `Evans 2003` Domain-Driven Design: Tackling Complexity in the Heart of Software, Addison-Wesley, 2003 (book)
- `Evans DDD Reference` [Domain-Driven Design Reference: Definitions and Pattern Summaries](https://www.domainlanguage.com/ddd/reference/), Domain Language, 2015 (reference)
- `OpenAI Academy scope-ai-solutions-kjplw` [Scope AI Solutions](https://academy.openai.com/public/courses/scope-ai-solutions-kjplw), OpenAI Academy (course)
- `OpenAI Academy scale-codex-across-teams-and-systems-jr83a` [Scale Codex Across Teams and Systems](https://academy.openai.com/public/courses/scale-codex-across-teams-and-systems-jr83a), OpenAI Academy (course)