AI can write code. Who decides what correct means?¶
Why specification-driven development needs a verification harness when software agents work on production code.
An agent can add a checkout endpoint before lunch. It can write the handler, tests, and documentation. The demo looks convincing. Then a payment times out, the client retries, and the customer is charged twice.
The problem was not that the agent could not write code. Nobody had defined the behavior that mattered when a request failed halfway through.
That is the question behind spec-bridge: If generating code gets cheaper, how do we make the work around that code explicit enough to check? My answer is to combine specification-driven development (SDD) with a harness that gives agents bounded tasks and checks the artifacts they produce. The specification says what must hold; the harness checks whether the workflow has produced enough evidence to proceed.
This is an introduction to the idea, not a claim that any tool can certify production safety. If you already know why you need it, jump to the workflow, a concrete example, or the architecture.
By Rodrigo A. Diaz Leven | LinkedIn · GitHub
The old coordination problem has a new participant¶
Large software teams had this problem before coding agents. When several people change the same system, each person needs to know what the others assume: which component owns a decision, what an interface promises, and what counts as a successful change. Without shared requirements and stable boundaries, the code may work locally while the whole system fails.
There was no single moment when “SDD” was invented to make large teams deterministic. The history is less tidy and more useful. Royce's 1970 paper discussed requirements, design, implementation, testing, and feedback in large systems. Parnas argued for modular boundaries and carefully defined interfaces so developers could work with fewer assumptions about one another's modules. Later work on contracts and tests made some of those assumptions checkable. An early paper explicitly called Agile Specification-Driven Development described tests and contracts as complementary specifications.
None of these ideas made people predictable. They made agreements visible and some mistakes detectable. That distinction matters more now. Agents can produce several implementations quickly, but speed does not tell us which assumptions they made. A prompt that says “build checkout” does not specify what a retry must do, who owns payment state, or when the kitchen may receive an order.
The old team-coordination problem now includes machines that can act on incomplete instructions at scale. SWE-bench measures agent changes against repository tests; SWE-agent shows that the interface for navigating a repository and receiving feedback affects agent performance. These are reasons to design the work environment, not reasons to trust every passing test.
From a vague feature to a testable failure¶
Suppose a team asks for a food-delivery checkout. “Handle payment failures gracefully” sounds like a requirement. It leaves the hard part open.
A better starting point is a specific misfit: the payment fails, but the order is still sent to the restaurant's kitchen. Another is: a timeout triggers a retry and charges the customer twice. A third: two customers order the last item and both orders are accepted. These are illustrative scenarios, not reports of production incidents.
Now the team can make decisions before an agent edits code:
| Question | Decision to make explicit | Evidence to request |
|---|---|---|
| What if the gateway times out? | A retry uses the same payment identity. | A test that retries without a second charge. |
| When is an order sent to the kitchen? | Only after payment is confirmed. | A test that rejects dispatch on failed payment. |
| Who owns the last unit of stock? | The order flow reserves it once. | A concurrent reservation test. |
The point is not to write more prose. It is to find the decisions that would otherwise be buried in generated code. If payment and order dispatch affect each other, the boundary between them needs an explicit contract. If inventory failures interact with concurrent reservations, they belong in the same design conversation. Synthesis-Driven Development (SyDD) uses these interactions between misfits to reason about subsystem boundaries; the methodology goes into the design steps.
What is a misfit, and why start there?¶
The term comes from Christopher Alexander's Notes on the Synthesis of Form. Alexander studied how a designed form, such as a building, fits its context: the people, materials, climate, and other conditions it must serve. A misfit is a specific way that form fails to meet a demand from its context. SyDD borrows this way of looking at design and applies it to software; misfits are not a required part of every approach called SDD.
For checkout, the context includes customers, a payment gateway, and the restaurant. “Payment fails, but the kitchen receives the order” names a misfit between the software and that context. It tells us more than “handle errors”: the team must decide when dispatch is allowed and what happens when payment fails. That decision can become a contract and an acceptance test.
Misfits also help with where to draw boundaries. If preventing duplicate charges and handling payment timeouts both depend on the same payment identity, the team should design them together. If delivery-radius checks do not affect that decision, they may belong elsewhere. This is the SyDD step: examine which failures interact, then use those interactions to shape components and work packages instead of guessing boundaries from familiar class names.
In spec-bridge, the decompose skill makes that reasoning an explicit, optional step. After specify records misfits in spec.md, decompose inventories them, records which pairs interact, and proposes subsystems with reasons for each boundary in decomposition.md. The tool checks that the artifact and required sections are present; it cannot judge whether the proposed boundaries are good. The value of the decompose skill is the reasoning it asks the agent or team to record: which failures affect each other, where one subsystem's behavior depends on another, and which failure scenarios the implementation should test. For a small feature, the team can skip this separate step and do the reasoning in plan. For a complex feature, plan uses the decomposition to define components and contracts; tasks assigns misfits to work packages; implement writes code and tests; review and accept check the results before merge. The workflow overview shows the handoffs.
A misfit is a design question, not proof that a failure will occur or that a test covers every case. The team still has to check that it identified the important failures and that its tests reflect real behavior. But naming a failure gives people and agents a shared, checkable target before either starts implementing a solution.
What spec-bridge does¶
A specification alone can still become a document nobody checks. A test suite alone can pass while missing the failure that matters. A harness connects the steps, the artifacts, and the checks.
In spec-bridge, an agent follows a skill for each stage: specify → optionally decompose → plan → tasks → implement → review → accept → merge. A complex feature can be split into work packages with explicit scope. Implementation can run in isolated Git worktrees. The agent calls spec-bridge-skill-tool after a skill to validate the artifacts it used or produced and to check the skill's declared outcome. The tool returns a structured pass or failure; the agent owns the workflow, not the tool.
For example, a checkout specification can name the payment-retry misfit; a plan can assign payment identity to a component; a work package can ask for a retry test. At each stage, the next person or agent has a smaller question to answer than “is checkout done?” The harness can reject missing or malformed artifacts and incomplete required fields. It does not prove that the design is right, that the tests cover every failure, or that the code is safe to deploy.
The decompose skill gives agents and humans a way to examine how subsystems interact and identify failure scenarios to test. Humans still review the important decisions and the evidence from tests and other checks.
This separation is deliberate:
- The specification states the expected behavior. Skill instructions guide the agent through the work.
- The validator checks artifact structure and configured outcomes, then reports what is missing.
- Tests and human reviewers assess the behavior.
For the responsibilities of the harness vs the validator tool, see the architecture overview and two-responsibility decision. For how each stage fits together, see the workflow overview.
The production bar is higher than “the agent finished”¶
I would not apply a full specification process to a typo. Nor would I treat a green validator as a release approval. More structure pays for itself when the work has coupled failure modes, several contributors, or consequences that are hard to reverse.
For production work, the useful question is not “Did the agent complete its task?” It is:
- Did we define the behavior and the failures that matter?
- Can we trace those decisions to interfaces, tasks, and tests?
- Did the checks run in a reproducible environment?
- Did a reviewer examine what those checks cannot prove?
Passing tests are evidence, not a guarantee. Weak tests can reward a plausible but wrong solution. The harness should make missing evidence visible, while the team remains responsible for judging its quality.
The aim is not deterministic creativity. It is a more dependable way to coordinate work, expose assumptions, and catch errors before generated code reaches production. Large teams needed shared contracts because many developers were building one system. Agents need them for the same reason: the next contributor might produce an entire implementation in minutes.
Where to go next¶
- Try the worked example: Building software with SyDD walks through the food-delivery scenario step by step.
- Understand the design idea: Synthesis-Driven Development explains misfits and subsystem boundaries in detail.
- Follow the stages: SyDD methodology and implementation connects specification, decomposition, design, and verification.
- See the mechanism: Architecture and workflow explain the skill modules, validator, and system boundaries.
- Understand the tradeoffs: Architecture decisions record why the validator is separate from the agent's instructions.
- Explore the source: (unreleased) spec-bridge repository has the tool, skills, and installation instructions.
About the author¶
Rodrigo A. Diaz Leven works on platform engineering and AI-assisted software delivery. This article builds on What Engineers Are Expected to Do After Generative AI: defining the work, giving agents useful context, and checking the result matter at least as much as writing code.