Spec-driven development

What it isCopy Anchor Link

You describe the behavior, constraints and acceptance checks in a short document. The agent turns it into a plan, then code. When it goes wrong, you fix the spec or the checks, not the generated code by hand. Google's framing is the same: define success with tests and automated checks first, then let the agent work, then verify.

Why it worksCopy Anchor Link

Most agent failures are underspecified tasks. A spec forces the missing decisions to surface while they are cheap. It also gives a stable document to hand to a fresh agent after a context reset. Keep specs small and testable. A spec nobody can verify is a wish.

A worked example: a tiny specCopy Anchor Link

Feature: password reset by email. Behavior: user enters email, receives a link valid for 30 minutes, link works once. Edge cases: unknown email shows the same message as a known one, so attackers cannot discover accounts. Checks: a test for expired links, a test for reuse, a test for unknown email. The agent now knows what done means.

How a spec guides the agentCopy Anchor Link

The agent works from the text it is given. A vague request leaves gaps, and the model fills each gap with the most likely choice, which may not be yours. A spec closes the gaps in advance. The usual flow is a short chain.

1. Write the behavior and the checks.
2. Ask the agent for a plan from the spec and read it.
3. Let it implement in steps, running the checks.
4. When something is wrong, edit the spec, not the code.

Step 4 keeps the spec as the source of truth. If you patch the code by hand, the next agent run will undo your change or contradict it.

A second example: when a spec is too muchCopy Anchor Link

You want a button to change colour. Writing a spec with edge cases would take longer than the change itself. Skip it. A spec pays off when the feature has rules that are easy to get wrong, such as money, permissions or time limits, or when several people or agents will touch it. Equally, a spec cannot capture everything: for a visual design, you may only know it is right when you see it. In that case iterate with the agent and look at the result.

What goes wrongCopy Anchor Link

Vague words are the main failure. "Fast", "secure" and "user-friendly" cannot be tested. Replace them with something measurable, such as "the page responds in under one second on the test data". Another failure is a spec that contradicts itself, which shows up as the agent asking questions or making an arbitrary choice. A third is checks that pass without testing anything, such as a test that always succeeds. To confirm a test has value, break the code on purpose and see whether it fails.

Try it yourselfCopy Anchor Link

Choose a small feature, such as a function that checks whether a password is strong enough.

1. Write five lines of rules, each testable.
2. Ask the agent to write tests from the rules before any code.
3. Break one rule in the code and watch a test fail.

Expect to find at least one rule that was ambiguous when you tried to write its test.

Common mistakeCopy Anchor Link

Specs nobody can check. If you cannot say how you would test a line, rewrite the line.