Specifies work well enough for an agent to implement and for anyone to verify
Coding with agents · competency coding-with-agents/specifies-work
Taught in: the Coding with agents course
Draws on: Deciding and specifying, Decomposing work
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
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
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
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
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 [1]. | 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 [1]. | 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
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 [2]. | "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
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
- Anthropic. Best practices for Claude Code. Claude Code documentation. Reference.
Claude Code best practices - David Thomas, Andrew Hunt. The Pragmatic Programmer: Your Journey to Mastery, 20th Anniversary Edition. Addison-Wesley, 2019. Book.
Thomas 2019