Spec-driven development: the rebranded BDUF
We've come full circle to Big Design Up Front… but that's not a bad thing.
👋 Hi, I’m Thomas. Welcome to a new edition of Beyond Runtime, where I dive into the messy, fascinating world of distributed systems, debugging, AI, and system design. All through the lens of a CTO with 20+ years in the backend trenches.
QUOTE OF THE WEEK:
“Those who cannot remember the past are condemned to repeat it,” - George Santayana
When I first read GitHub’s article about spec-driven development, my reaction was immediate: “I’ve heard this before.”
Here’s their pitch: start with comprehensive specifications, create detailed technical plans, break everything down into precise tasks, only then you send everything to your AI tools and agent to write your code.
If this sounds familiar, it should.
There’s a significant resemblance to Big Design Up Front (BDUF), the heavyweight specification process that Agile was partly a reaction against. And it’s tempting to raise an eyebrow and think it’s the same approach but “rebranded for the AI era”.
However, spec-driven development with AI is genuinely different and genuinely better. Not because the idea of designing before building is new (it isn’t), but because AI changes the economics of doing it well.
Beyond the marketing rebranding
Yes, there's something a little amusing about the tech industry rediscovering upfront design and packaging it as a paradigm shift for the AI era. The GitHub article reads:
“[…] we’re rethinking specifications — not as static documents, but as living, executable artifacts that evolve with the project. Specs become the shared source of truth. When something doesn’t make sense, you go back to the spec; when a project grows complex, you refine it; when tasks feel too large, you break them down.”
Documentation people have been talking about “living specifications,” “executable artifacts,” “shared source of truth” for years, albeit to sparsely populated rooms.
A more honest description, in my opinion would have been:
AI coding agents work best with clear specifications and structured context, which happens to align with existing design and documentation best practices that teams have struggled to follow consistently. Here’s a toolkit that makes it easier to create the kind of documentation that benefits both humans and AI.
But even if it’s just a rebrand, sometimes we need to rediscover old wisdom under new circumstances.
What didn’t change and what did
What didn’t change: the underlying logic.
Thinking carefully before building has always been better than building carelessly and cleaning up later.
BDUF wasn’t wrong because upfront design is bad. It fell out of favour because the cost of doing it well was genuinely prohibitive. Writing thorough specifications took weeks. Keeping them up to date was a full-time job. And the moment business requirements shifted (which they always did) your carefully crafted documents became archaeology.
Agile promised us freedom: respond to change, ship fast, iterate. But teams overcorrected. “Responding to change over following a plan” became “don’t plan at all.” We went from BDUF paralysis, to “figure it out as we go” chaos.
At some point in the past few years we tried to find balance with some upfront design: enough to establish shared vision, identify risks, make conscious trade-offs. However, even the best engineering teams struggled with the implementation: the work is manual, documentation is outdated as soon as you push your next commit, and the focus is always on shipping the next feature.
What changed: the cost.
With AI, a thorough working specification isn’t a days-long documentation marathon. It’s a conversation. You can interrogate your own assumptions, stress-test your architecture decisions, and surface edge cases in an afternoon.
The spec stays current because updating it is no longer a painful enough task to skip (or relegate to the backlog).
The economics flipped.
And when the economics of a practice flip, the practice itself becomes viable in ways it simply wasn’t before.
The biggest benefits
Lower cost for documentation and upfront design would already be worth something on its own. But the benefits of spec-driven development run deeper than that.
(1) AI tools produce better output when they have better input.
A precise, well-reasoned specification gives any AI agent the context it needs to make the right decisions. A clear spec narrows the solution space before a single line is written, which means less correction, less iteration, and fewer of those “it technically does what I asked but not what I meant” moments.
(2) It’s now practical for teams to do the upfront thinking they always knew they should be doing but rarely had time for.
There was always value in doing upfront thinking but the cost of capturing it properly was too high. Now it isn’t.
(3) AI agents can work effectively in parallel
When you introduce multiple AI agents working in parallel, the specification isn’t just documentation anymore but it’s also the coordination layer.
Here’s the mechanics: once you have a well-formed specification broken into discrete, well-scoped tasks, you can hand those tasks to multiple AI agents simultaneously. Instead of one developer (or one agent) working sequentially through a feature, you have several working in parallel on independent sub-tasks, each operating from the same shared spec, each producing output that fits into the same coherent architecture.
This allows parallel work to remain coherent without constant human intervention to align it.
Should you adopt it?
The honest answer is: specs help (a lot), but they’re not everything.
Better specifications give AI tools better input: clearer tasks, tighter scope, output that fits the architecture you actually intended. That’s real and worth pursuing.
But a spec describes what you’re building. It says nothing about how your system is behaving right now, in production, under real conditions. AI tools need both.
A well-written spec helps an agent write better code. But it can’t help an agent debug a production issue it can’t see, or where the frontend error is not connected to the backend failure. The AI tool can’t suggest a meaningful fix without full context of what actually happened.
The same trend pushing teams toward better upfront design should push them toward better observability practices. Unsampled, session-correlated, full-stack visibility isn’t just useful for humans debugging at 2am. It’s also useful to tell your AI tools what’s actually true about your system.
💜 This newsletter is sponsored by Multiplayer.app.
Full stack session recording. End-to-end visibility in a single click.
📚 Interesting Articles & Resources
Reinventing the Wheel Again, and a Case for Spec-Driven Development in the Age of AI - Paul Gledhill
This article is a good walk-through of the practical benefits of adopting spec-driven development. “vibe coding” with AI lacks predictability and maintainability, but with upfront spec-driven practices you ensure repeatable, controlled development and improve long-term quality with AI
Fast PRs but shallow understanding - Stephane Moreau
I wholeheartedly agree with this article on how AI tools boost velocity but erode deep system knowledge. As Stephane points out, we will need even stronger engineering leadership to guard against shallow comprehension and balance throughput with resilience and expertise.
AI Makes the Easy Part Easier and the Hard Part Harder - Matthew Hansen
“AI assistance can cost more time than it saves”. I agree completely. This article highlights that AI handles routine coding but leaves context, investigation, and validation (the hardest skills!) to humans. Leaders should emphasise ownership, context understanding, and avoid overreliance on AI.