# Specifies work well enough for an agent to implement and for anyone to verify

> Competency coding-with-agents/specifies-work

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

*Coding with agents* · competency `coding-with-agents/specifies-work`

**Taught in:** the [Coding with agents](https://schubergphilis.github.io/ai-training/coding-with-agents/) course

**Draws on:** [Deciding and specifying](https://schubergphilis.github.io/ai-training/topics/coding-with-agents/specification/), [Decomposing work](https://schubergphilis.github.io/ai-training/topics/using-agents/decomposition/)

## Learning objectives

### Judges whether something should be built before building it (base)

| Claim | Why | Example |
| ----- | --- | ------- |
| The learner states the problem and who has it before proposing a change. | An agent makes building cheap, which makes building the wrong thing cheap too. | "Support answers the same question ten times a week" comes before "build a settings page", and the answer may be a documentation fix. |
| The learner names at least one alternative to building, including doing nothing, and says why building wins. | The comparison is what turns a wish into a decision. | "We could add the feature, change the default, or document the workaround; the workaround costs each user five minutes a week, so we change the default." |
| The learner weighs the cost of owning the change against its value, and the cost of writing it is the smaller part. | The agent writes it in an hour, and the team maintains it for years. | A new dependency for one date format is rejected because it adds a package to keep patched, and a ten-line function is written instead. |

Served by: [Deciding whether to build it at all](https://schubergphilis.github.io/ai-training/coding-with-agents/deciding-what-to-build/)

### Defines what a successful outcome requires (base)

| Claim | Why | Example |
| ----- | --- | ------- |
| Success is written as observable outcomes that a person other than the author could check. | A criterion the author has to interpret is a criterion the agent and the reviewer interpret differently. | "Search results return within 300 ms at the 95th percentile on the test data set" instead of "search is fast". |
| The criteria include what must keep working as well as what is new. | An agent optimizing for the new criterion trades away anything that is not listed. | "All existing exports still open in the finance team's spreadsheet program" is added because the new CSV format could break them. |
| The learner writes down what is out of scope. | The agent fills the gap between "done" and "everything it could improve" with its own choices. | "Not in scope: mobile layout, translations" stops the agent from restyling the whole page. |

Served by: [Deciding whether to build it at all](https://schubergphilis.github.io/ai-training/coding-with-agents/deciding-what-to-build/)

### Decomposes a problem into components with clear dependencies (base)

| Claim | Why | Example |
| ----- | --- | ------- |
| Each component has one clear responsibility and an interface that fits in a sentence. | Components a person can describe are components an agent can implement in isolation and a reviewer can check in isolation. | "A parser that turns the file into records; a validator that flags bad records; a writer that saves the good ones" rather than one "import" task. |
| The learner draws the dependencies and orders the work so each step can be checked before the next starts. | A component built on an unverified one inherits its mistakes and hides them. | The parser is built and tested on real files before the validator, because the validator's tests need real parsed records. |
| Each component is small enough to be one agent session and one reviewable change. | A task that is too large for a session loses context halfway through, and its diff is too large to read. | The learner splits "add authentication" into token issuing, token checking and the login page, and briefs each separately. |

Served by: [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/)

### Designs how the work will be verified before it is built (base)

| Claim | Why | Example |
| ----- | --- | ------- |
| Before building, the learner writes down how each success criterion will be verified: which test, which measurement, which manual step. | A check designed afterwards is designed around what was built, and passes by construction. | For "no duplicate invoices", the check is a test that imports the same file twice and asserts one set of rows, written before the import code. |
| The check is something the agent can run, so it can verify its own work before handing back. | A check only a person can run is run once at the end, and a check the agent can run is run on every attempt. | The acceptance test goes into the test suite and the brief says "done when `mise run test` passes". |
| The learner designs at least one check that would fail if the agent took a shortcut. | Agents optimize for the check they see, and a check that passes on a stub passes on a stub. | The test for the email sender uses a fake mailbox and asserts the message arrived, where a check on the send function's return value would pass on a stub. |

Served by: [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/)

### Reaches a shared design by having the agent interview them before planning (base)

| Claim | Why | Example |
| ----- | --- | ------- |
| For a larger feature, the learner asks the agent to interview them about the design before any plan is written. | The questions bring out decisions the learner had not made yet, while changing them is still free (Best practices for Claude Code, Claude Code documentation). | The learner writes "I want a CSV export. Interview me about it before you plan anything", and gets questions about encodings and very large files they had not considered. |
| The learner answers with decisions, and says "not decided yet" when there is none. | An answer made up to move on becomes a requirement the agent builds. | Asked which time zone the export uses, the learner says it is undecided, and the spec lists it as an open question. |
| The interview ends in a written spec, and the work starts from that file in a fresh session. | The file holds the outcome of the interview, and a fresh session has room for the work (Best practices for Claude Code, Claude Code documentation). | The agent writes `SPEC.md`, the learner reads and corrects it, and opens a new session with "implement `SPEC.md`". |

Served by: [Let the agent interview you](https://schubergphilis.github.io/ai-training/coding-with-agents/agent-interviews-you/)

### Settles a design question with a throwaway prototype (expert)

| Claim | Why | Example |
| ----- | --- | ------- |
| The learner states the one question a prototype must answer before asking for it. | A prototype without a question grows into a first version of the system (The Pragmatic Programmer: Your Journey to Mastery, 20th Anniversary Edition, Addison-Wesley, 2019). | "Can the library read the 2 GB export in under a minute?" and the agent writes a short script that times exactly that. |
| The prototype leaves out everything the question does not need. | Its value is the answer, so tests, error handling and structure are effort spent on code that is deleted. | The timing script has a hard-coded path and no tests, and the learner does not ask for either. |
| The learner writes the answer into the specification and deletes the prototype. | Code built without structure brings its shortcuts into the system when it is kept. | The spec gains "the parser must stream, because the library loads the whole file into memory", and the prototype branch is deleted. |

Served by: [A prototype you throw away](https://schubergphilis.github.io/ai-training/coding-with-agents/prototype-to-throw-away/)

## Alignment

| Framework | Code | Asks | Objectives here |
| --------- | ---- | ---- | --------------- |
| Ng, AI engineering skills map | Shaping the build | Deciding what goes in the spec | judges-worth-building, defines-success, decomposes-into-components, designs-the-check |
| AI Fluency 4D (Dakan and Feller) | Delegation | Decide what to hand to AI, which tool fits, and how much autonomy to give | judges-worth-building |
| Brilliant Coding with AI | TAS-1..4 | Judge what should be built and define success, weighing value against cost | judges-worth-building, defines-success |
| Brilliant Coding with AI | SPC-3, SPC-4, SPC-6 | Decompose, analyze dependencies, design verification | decomposes-into-components, designs-the-check |

## References

- Best practices for Claude Code, Claude Code documentation, https://code.claude.com/docs/en/best-practices
- The Pragmatic Programmer: Your Journey to Mastery, 20th Anniversary Edition, Addison-Wesley, 2019