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

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