Spec-Driven Development: Where OpenSpec Chafes in Daily Use

Short answer: spec-driven development (SDD) means writing down what a change has to do, as requirements and acceptance scenarios in Markdown, before the agent touches any code, and having the agent build against that document. OpenSpec, Spec Kit and Kiro are the best-known tools. In 2026, for the people whose workflows I’ve read, it’s no longer the center of the workflow: the effort goes into giving the agent a check that comes back pass or fail, and the spec, when there is one, is short (Anthropic suggests having Claude interview you to produce it).

Step away from AI for two or three weeks and it feels like years went by. Everyone’s talking about SDD, harness engineering, grilling and software factories, and you can’t tell whether you missed a revolution or a few new names for the same thing.

The first one, SDD, got me. I went to look up what spec-driven development actually was and found out I’d been doing it for months. I use OpenSpec every day, on this site and on Rydger. I just didn’t know it had a name.

One caveat up front: OpenSpec is the only SDD tool I run daily. I’ve read about Spec Kit, Kiro and BMAD but haven’t lived with them, and the people I quote below are the ones whose workflows I think are worth reading, not a survey.

So the rest of the vocabulary doesn’t throw you, here are three terms you’ll hear this week:

• Harness engineering: everything that guides and checks the agent; the spec is one of its guides. I covered it in this post.
• Grilling: having the agent interview you relentlessly before anything gets written.
• Software factory: spec in, software out, no human review. The opposite end of the spectrum from what I’m arguing for here.

I’d been doing SDD for months without the label

GitHub popularized the idea when it launched Spec Kit in September 2025, pitching the spec as “a contract for how your code should behave.” Birgitta Böckeler, writing on martinfowler.com, sorted it into three levels that make the rest of the noise easier to place:

• Spec-first: write the spec, let the agent build, and the spec isn’t necessarily kept once the task is done.
• Spec-anchored: the spec stays in the repo and evolves with the code.
• Spec-as-source: the spec is the source file and the code is generated from it.

OpenSpec is spec-anchored. Each change lives in openspec/changes/<name>/ as four pieces: proposal.md (why and what changes), delta specs with requirements and WHEN … THEN … scenarios, design.md (how) and tasks.md (the checklist). When you’re done you archive the change, and its deltas merge into the project’s living specs.

The rest of the map, one line each:

That table is my reading of their docs, not a recommendation from any of them.

Where OpenSpec chafes when you use it every day

The friction doesn’t show up in a demo. It shows up after months with the tool, and it clusters in four places.

explore stays shallow. It’s supposed to be the thinking and research step before you propose. In practice it reads what’s in front of it and comes back fast. It doesn’t do the research I’d do by hand: reading the docs and checking how other people solved the same problem.

propose doesn’t ask enough questions. When there’s a gap, it fills it with a reasonable assumption and moves on. Those assumptions get written down with the same confidence as the things you actually decided, and then you have to hunt them down. That’s a pattern I see often, not something I’ve counted.

The Markdown is long, and long reviews degrade. Four files per change is a lot of text to read carefully before a single line of code exists. The problem is the volume, not the reader. Böckeler said it in October 2025 after trying Kiro and Spec Kit: “I’d rather review code than all these markdown files.” Thoughtworks’ Radar warned in November 2025 that some of these tools generate spec files that are long and hard to review.

Closing a change is pure ceremony. When you archive, it first asks you to sync the delta specs into the living ones, then archives: one more review gate that neither writes code nor checks it. That’s the price of a living spec, and you pay it on every change, small ones included. On a small fix, Böckeler compared the workflow to using a sledgehammer to crack a nut.

The honest part: a living spec does earn its keep

This site has an OpenSpec change called improve-seo-ai-visibility, proposed on October 6. Every task is done except one: re-measure 28 days after the deploy. That task is still sitting in tasks.md, and no chat session would have remembered it for me. To be fair, a GitHub issue would have held the reminder too. What the issue doesn’t hold is the requirement next to it, with its scenarios, in the same repo as the code it describes. That’s the promise of spec-anchored: a year from now, someone can read why the code is the way it is. On a three-week-old change, that’s still more promise than payoff.

I also like that every task ends in a concrete “verify …”, so the agent knows what to check before it ticks the box.

And SDD isn’t dead. Spec Kit shipped four releases between October 16 and October 27, 2026, and the April 2026 Radar put OpenSpec in Assess, which in Thoughtworks terms means worth exploring.

What they do now: a short spec and a check the agent can run

I read how four people whose work I follow describe their own workflow, plus Anthropic’s guide. They agree more than you’d expect.

• Anthropic’s Claude Code best practices suggest that when you don’t know exactly what you want, you have Claude interview you until it can write the spec to a SPEC.md, then build from a fresh session. And the line that sums it all up: “Give Claude something it can run that comes back pass or fail.”
• Boris Cherny, who leads Claude Code, in a January thread: five Claudes in parallel, most sessions starting in plan mode, and what he calls the most important thing for good results, giving Claude a way to verify its work. I covered his point about writing loops instead of prompts in another post.
• Simon Willison, in his agentic engineering guide: red/green TDD (write the test, confirm it fails, then write the code) and run the existing tests before you start.
• Mitchell Hashimoto, in February: “If you give an agent a way to verify its work,” it fixes its own mistakes more often than not. And a repeated agent mistake gets a line in AGENTS.md or a script so it stops recurring.
• Böckeler again, in April, on harness engineering: guides before the agent acts (rules, specs) and sensors after (tests, linters, type checks). The spec becomes one guide among several.

This is partly SDD under another name: the interview plus SPEC.md is textbook spec-first. The difference is where the effort goes. Classic SDD puts it into writing and reviewing Markdown, so the guarantee rests on a person reading it carefully. This puts it into a scenario that becomes a failing test, which then goes red without anyone watching. It isn’t free either. A test written by the same agent that wrote the code can pass while checking the wrong thing, so the review doesn’t disappear: it moves to the test. And a green command says nothing about a design decision no command can check.

Three of the frictions have a fix; the fourth doesn’t

Here’s what I’d try for each, based on the above:

The last row has no clean fix. If you want the spec to survive, somebody has to sit through the ceremony. What you get to choose is which changes are worth it.

What to learn next, cheapest first

1. One pass/fail command per project. Tests, types, linter, whatever you have, behind a single command the agent can run. It’s the point all five sources share.
2. Scenarios become tests. The WHEN … THEN … in your spec is already a test written in English. Ask the agent to write it first and confirm it fails.
3. A short AGENTS.md that grows one mistake at a time. Every time the agent repeats an error, one line or one script. And prune: the April Radar flags agent instruction bloat under Caution because those files get long and start contradicting themselves.
4. Interview before the spec. This goes straight at the propose problem. I wrote up how I do it with grill-with-docs.
5. A reviewer with a clean context. A session or subagent that checks the diff against the spec without having seen your conversation. Anthropic’s guide is blunt about it: handing the same task to a subagent doesn’t make the answer better, but a fresh reviewer does help.
6. Parallel work in worktrees, and loops. Last. A worktree is cheap to try and so is a small loop; the Radar’s caution is about swarms of agents running at once, and that’s where most of the noise comes from.

On this site I already run 1, 3 and 4: a pre-push hook that runs astro check, lint and the tests before every push, a short AGENTS.md, and grill-with-docs. I built number 5 as a verifier.

Step two is the one Willison and Pocock push hardest. Here it is with a made-up booking example:

// spec: WHEN room R1 is booked 10:00-11:00
//       and someone books R1 for 10:30-11:30
//       THEN the API returns 409 and stores nothing
it("rejects an overlapping booking", async () => {
  await book({ room: "R1", from: "10:00", to: "11:00" });
  const res = await book({ room: "R1", from: "10:30", to: "11:30" });
  expect(res.status).toBe(409);
  expect(await countBookings("R1")).toBe(1);
});

Before your next propose

You don’t need to drop OpenSpec. A “verify …” written in prose is something the agent interprets; a command with an exit code isn’t. So do one thing: go through your next change’s tasks.md and make sure every task ends in a command the agent can run that comes back pass or fail. For a task with no command, like a design decision or a doc, write down what you’d observe when it’s done (a file that exists, a URL that answers) or mark it as human-checked on purpose. The ones a command can’t confirm for you are where your attention should go.

Related reading: the step I added before OpenSpec, to decide what deserves a spec at all, is in the Rydger subagents post.

Sources

• GitHub, Spec Kit launch post (September 2, 2025).
• Birgitta Böckeler, Understanding Spec-Driven-Development: Kiro, spec-kit, and Tessl (October 15, 2025) and Harness engineering (April 2, 2026).
• Thoughtworks Technology Radar: spec-driven development (November 2025), OpenSpec and agent instruction bloat (vol. 34, April 2026).
• Anthropic, Claude Code best practices (read October 28, 2026).
• Boris Cherny, thread on his Claude Code workflow (January 2, 2026).
• Simon Willison, Agentic Engineering Patterns.
• Mitchell Hashimoto, My AI Adoption Journey (February 5, 2026).
• Matt Pocock, skills, including grill-me.
• My OpenSpec experience comes from daily use; the improve-seo-ai-visibility change is in this site’s repo.

P.S. Do you use SDD every day too? I’d love to know which part you stopped doing and never missed. Tell me on LinkedIn.