Rob West

Specs, Agents and Lost Design Signals

Published 16 Nov 2026


Picture a change that should be simple, adding a field to an order, which turns out to need edits in fourteen files. A developer making that change notices. They groan, they start to wonder why the same knowledge is spread across so many places, and quite often they stop and restructure the code so that the next change of this kind touches one place rather than fourteen. An agent making the same change just edits the fourteen files. It doesn't get tired or irritated, the tests pass, and the pull request arrives looking like progress.

I think that difference matters more than it first appears. Building software produces two kinds of learning: whether the product does the right thing, and whether the design fits the domain. The second kind has always depended on friction like this, and agents absorb it. Spec-driven development, the most visible response to the weaknesses of coding agents over the last year or so, has a place for the first kind of learning but no place for the friction. This builds on my argument that the agentic software factory is the wrong metaphor, and as there, I'm not denying that a large class of work can go straight through an agent. I'll come back to where that work fits, because it turns out to matter to this argument too.

Two Kinds of Learning

The first kind of learning is about the product: does the system do the right thing for the people using it? This is the territory of hypothesis-driven development. Barry O'Reilly's format captures it well: we believe this capability will result in this outcome, and we will know we have succeeded when we see this measurable signal. Product learning can be written down in advance as a belief, and tested.

The second is about the design: do the abstractions in the code match the concepts of the domain? Plato's image in the Phaedrus of "carving nature at its joints" is the best description I know of what good system design is trying to do. I picked that phrase up from my study of philosophy and it always comes to mind when thinking about this topic. Eric Evans described how this happens in practice in Domain-Driven Design, in the part of the book he called "refactoring toward deeper insight": the model improves through working in the code, often in sudden breakthroughs when a better concept becomes visible. John Ousterhout's A Philosophy of Software Design argues for continual, strategic investment in design rather than treating design as a phase, and for designing things twice to compare alternatives. Dave Farley frames the whole discipline as optimising for learning and for managing complexity. None of them treats design fit as something you can specify up front.

Christopher Alexander explained why in Notes on the Synthesis of Form in 1964. He argued that good fit between a form and its context is very hard to describe directly, but misfits are easy to recognise. We arrive at good design by noticing and removing misfits, not by specifying fit. Daniel Jackson draws out the consequence for requirements in his work on software concepts:

The list of fitness criteria is infinite and unknowable.
Daniel Jackson, What is a design problem?

If fit can't be specified, it has to be sensed.

The Friction Was the Feedback

That sensing has always depended on friction. Ousterhout describes three symptoms of complexity: change amplification, where a simple change needs edits in many places; cognitive load, where you need to hold too much in your head to make a change safely; and unknown unknowns, where it isn't clear what needs to change at all. Each of these is something you feel while you are working. The fourteen-file change is change amplification in its purest form, and the developer making it feels it. That discomfort is Alexander's misfit, experienced in the work rather than observed from outside.

The discomfort is also what prompts the response. Kent Beck's advice captures the instinct well:

For each desired change, make the change easy (warning: this may be hard), then make the easy change.
Kent Beck

Developers refactor because the friction tells them where the design no longer fits. Years ago I wrote about being mindful of tensions in how a team works and being prepared to change things to reduce them. The same instinct operates on the code. You sense the tension, then you respond to it, and over time the abstractions move closer to the "joints" of the domain.

That is what disappears when an agent makes the change. Editing fourteen files costs it almost nothing, and it doesn't stop halfway through to ask whether there is a better way. The reviewer sees a larger diff rather than the missing abstraction behind it. The friction is absorbed at the point of change, and with it goes the signal that would have prompted someone to make the change easy first.

This is my interpretation rather than an established finding, but the data I have seen is consistent with it. GitClear's analysis of 623 million code changes, Write-Only Mode, reports that the share of changed lines that were moved, its proxy for refactoring, fell from 21% in 2022 to 3.8% so far in 2026, while copy and pasted lines rose from 9.4% to 15.7%. These are a vendor's own measures, they show correlation rather than cause, and GitClear doesn't explain how it detects moved code, so I wouldn't lean on the precise numbers. But the direction is what the mechanism predicts: less restructuring, more repetition, and design misfit accumulating quietly while delivery looks smooth.

My suspicion is that the bill arrives later, and in a form that is harder to trace. Agents have their own version of cognitive load. A design with poor boundaries needs more context to change safely, produces more surprising regressions, and has more unknown unknowns for the agent to stumble into. So the friction does come back, but as agents that struggle and changes that break things in distant places, long after the moment when a small refactoring would have been cheap. By then it is easy to blame the tool rather than the design.

What Specs Capture, and What They Miss

Spec-driven development grew out of a real problem: agents given vague instructions fill the gaps with plausible guesses. GitHub's Spec Kit, AWS's Kiro and OpenSpec share the same basic idea of writing a structured specification of what should be built, reviewing it, and having the agent build to it. Birgitta Böckeler's analysis of the tools places them on a range: spec-first, where the spec guides a single task; spec-anchored, where it is kept to guide later changes; and spec-as-source, where the spec becomes the main artefact and "the human never touches the code."

The sharpest criticism so far has been about timing. Kent Beck made it in a post that Martin Fowler quoted and endorsed:

The descriptions of Spec-Driven development that I have seen emphasize writing the whole specification before implementation. This encodes the (to me bizarre) assumption that you aren't going to learn anything during implementation that would change the specification.
Kent Beck, quoted by Martin Fowler

Fowler's response was that the key to using AI well is to use it to accelerate the feedback loops. I agree, and the two kinds of learning help to say which loops. Product learning is captured, after a fashion, as requirements, but a requirement that is a guess about what customers want is written in exactly the same way as one we have evidence for. Design learning is captured as a plan written before the code, which is precisely where Alexander and Jackson tell us fit can't be found. And the friction that tells us where the design no longer fits has no place at all. The spec describes what the agent should build, and nothing asks what building it revealed.

Prose adds a further problem. Each requirement implies design decisions it doesn't state, and the agent settles them silently, possibly differently each time it runs. So the code, rather than the spec, ends up defining what the system actually does, which sets up the drift I come to below.

OpenSpec as a Test Case

OpenSpec is a useful test of whether this can be fixed within the spec-driven model, because it is designed around iteration. Each change gets its own folder containing a proposal (why the change is being made), a design document (the technical approach and architecture decisions), a task list, and delta specs describing only what the change adds, modifies or removes in the system's behaviour. When the change is finished it is archived: the delta specs are merged into a set of main specs, which the documentation describes as the source of truth for "how your system currently behaves", and the rest of the change folder moves into a dated archive. The documentation is explicit that the artefacts should change as you go, "learn as you build, refine as you go". That is a genuine attempt to keep learning open, but when I look at where the learning ends up, both kinds lose something.

For product learning, being built is treated as being true. When a change is archived its deltas join the source of truth, and nothing in the format separates behaviour we have validated from behaviour we merely implemented. The distinction between what we know and what we believe, which is the whole point of a hypothesis-driven approach, disappears at the moment of merging.

For design learning, the why goes into the archive. The proposal and the design document, the two places where rationale and design learning live, are kept as history rather than merged into anything, so the knowledge most useful to the next person, or the next agent, who needs to change the system is the least durable part of the record. And the learning loop works inside a single change, while some of the most important design learning crosses changes: the realisation, after the third awkward feature in a row, that our model of some part of the domain is wrong. There is no natural home for that.

Across both, specs and code drift. The main specs describe behaviour in prose, and the code and tests describe the same behaviour. Andy Hunt and Dave Thomas's original statement of DRY was about knowledge, not code: "every piece of knowledge must have a single, unambiguous, authoritative representation within a system." Two authorities for the same behaviour will diverge, and with agents the divergence is worse than ordinary stale documentation, because an agent will follow a stale spec confidently rather than ignoring it the way a sceptical developer might.

None of this is unique to OpenSpec, and teams can do more than the documented workflow asks. But the gaps are there even in a tool designed around iteration.

Rebuilding the Sensor

If friction used to be the sensor, and agents have removed it, then we need to rebuild the sensor deliberately. I think specs could genuinely help here, if we change what we think a spec is for.

The starting point is that every change tests two hypotheses, one about the product and one about the design. We already have a format for the first. For the second, we can state before the change what we expect it to touch: which concepts and modules should change, and which shouldn't. After the change we can compare what actually happened. A large gap between expected and actual is a misfit signal, the same information a developer's irritation used to carry, and it should become refactoring work rather than a footnote. We can also ask the agent directly. "What made this change harder than it should have been?" is a cheap question to put to an agent, and the answer is design information that would otherwise be lost.

Here is an illustrative sketch of what that might look like alongside a change. It isn't part of any tool; it is just a way to make the idea concrete.

# Illustrative only: hypotheses and observations recorded alongside a change
change: add-partial-refunds
product:
  belief: Customers who can refund part of an order will contact support less
  evidence: Refund-related support tickets fall by 20% within a month of release
  status: unvalidated
design:
  expected_to_touch: [Payments, Refunds]
  should_not_touch: [Orders, Invoicing]
  new_concepts: none expected
observed:
  touched: [Payments, Refunds, Orders, Invoicing, Reporting]
  new_concepts: [RefundAllocation]
  agent_friction: Order totals are recalculated in three places and each needed the same change
response: Consolidate order total calculation before the next payments change

A few principles sit behind that sketch.

  • Separate what we know from what we believe. A belief only becomes knowledge when the evidence arrives, not when the code is merged. The product belief above stays marked as unvalidated until the support data says otherwise.
  • Make knowledge executable. Behaviour we are confident about belongs in tests and executable examples, the approach behaviour-driven development and Gojko Adzic's Specification by Example established long ago. Architectural constraints belong in fitness functions, the automated checks Neal Ford, Rebecca Parsons and Patrick Kua describe in Building Evolutionary Architectures. Executable knowledge can't drift silently, because it fails.
  • Keep prose for what only prose can say. Intent, outcomes, beliefs and rationale don't fit in code, and they should stay live rather than being archived. My rule of thumb would be: don't write in prose what can be stated in code, and don't leave in code what only prose can say.
  • Treat vocabulary as a fit test. If the domain terms in the spec and the names in the code start to diverge, that is both drift and a sign that the abstractions no longer match the domain.

Henry Garner at JUXT has proposed something compatible in On co-specs and tri-checks: the spec, the tests and the code are checked against each other, with "none of the three" having primacy, so that a disagreement between any two is information. That gets the relationship right, I think. The spec isn't the master the code serves. It is one of several views of a design we are still discovering, and the places where the views disagree are where the learning is.

Could OpenSpec be extended to work this way? Some of the gaps would close: a section for beliefs with archiving gated on evidence rather than completion, a record of design expectations and observed friction for each change, and executable scenarios to stop behaviour drifting. But executable scenarios fix drift by turning the behaviour spec into the test suite, which leaves the prose version redundant. Live rationale still sits beside the code and has to be maintained, and learning that crosses changes still has no home in a model organised around individual changes. So I don't think it answers these concerns. My suspicion is that the sensing needs to sit closer to the code and the running system than a folder of specs can.

Routine Work as a Sensor

The two kinds of learning also give a way to place the work that can go straight through an agent. Product uncertainty and design uncertainty can each be high or low:

  • Low product and low design uncertainty: the straight-through work. A precise spec is a perfectly good work order, and this is a large share of what most teams do.
  • High product, low design uncertainty: experiments. A thin spec, a stated belief about the outcome, and a fast route to evidence.
  • Low product, high design uncertainty: we know what the behaviour should be but not how the system should accommodate it. This is where designing it twice, spikes and refactoring first pay off.
  • High product and high design uncertainty: discovery. Agents can be enormously useful here prototyping alternatives, and the spec is mostly questions.

That explains why one spec-driven workflow feels like overkill for a small fix and inadequate for a genuinely new problem. The more useful consequence is that the straight-through route can be a sensor itself. If we record design expectations even for routine changes, then a change we thought was routine that turns out to touch far more than expected has told us something. It was in the wrong quadrant, and the design has a misfit we hadn't seen. That is the moment to take it out of the pipeline and look at the design, rather than letting the agent quietly absorb the cost.

Sensing at Machine Speed

I think specs are worth writing, and spec-driven development is a reasonable response to agents filling gaps with guesses. But a spec treated as a work order, which becomes the truth once the code is merged, captures product learning badly and design learning not at all. For as long as people have been writing software, a change like the fourteen-file one has told someone that the design no longer fits the domain, and good teams have learned to listen. Agents remove the effort and, unless we are careful, the information along with it. If coding agents give us design engineering at machine speed, we need sensing at machine speed too, and that means deliberately building back the feedback that friction used to provide.

© 2026 Rob West. All Rights Reserved. Built using Kontent and Gatsby.