For thirty years, software development has operated on a simple, unspoken hierarchy. Specifications were inputs. Code was the output. The document you approved in a strategy meeting became a rough guide — a wish list that developers interpreted, adapted, and ultimately rewrote in the language of implementation. By the time software shipped, the original intent had been filtered through dozens of technical decisions that no one above engineering had visibility into or control over. That hierarchy is changing. And the implications for how you lead, govern, and invest in technology are significant.
The Gap That Has Always Existed
Every technology leader knows the scenario. A detailed requirements document is agreed. Development begins. Months later, what ships doesn't quite match the original vision. Features are missing. Edge cases were interpreted differently. The roadmap shifts. The team embarks on another sprint cycle to correct course.
This isn't a failure of process or of people. It is a structural problem baked into how software has always been built.
The specification served the code. It was scaffolding — useful during planning, discarded once development began. Code became the source of truth. The original intent lived in documents that quickly fell out of sync with the system being built.
Spec-Driven Development (SDD) — a methodology formalised by GitHub's emerging spec-kit tooling — inverts this entirely. Code no longer drives specifications. Specifications drive code. The document you and your team agree on becomes the executable source of truth from which code is generated, tested, and maintained.
How SDD Differs From What Came Before
To understand what SDD changes, it helps to place it against the methodologies executives are already familiar with.
Waterfall
Waterfall came closest to placing specifications at the centre. Requirements were documented in detail before a line of code was written. But Waterfall's fatal flaw was that specifications and code were still entirely separate artefacts. Once requirements were handed to engineering, the spec became static. It did not evolve with the product. It did not generate code. It simply described what was intended, and engineers translated that intent manually — a translation process riddled with interpretation, assumption, and drift.
When reality met the specification, it was always the specification that lost.
Agile
Agile was a direct reaction to the failures of Waterfall — and it made a reasonable bet. If specifications were always going to fall behind reality, stop trying to write them upfront. Embrace change. Iterate. Let working software be the measure of progress.
The result was a methodology that elevated developer velocity and shortened feedback cycles. But it came at a cost that is only now becoming fully visible: specifications became secondary artefacts. Product backlogs, user stories, and acceptance criteria served the sprint. They described intent, but code was still the truth. When requirements changed, teams manually propagated those changes through design documents, APIs, tests, and implementations. Each pivot accumulated hidden technical debt.
The Agile Trade-off
Agile solved the delivery problem but preserved the intent-to-implementation gap. It made that gap faster to navigate, not smaller. The backlog remained a proxy for business intent, not a driver of it.
SAFe and Scaled Frameworks
Enterprise frameworks like SAFe attempted to bring strategic alignment back into Agile at scale. Program Increments, Architectural Runways, and Portfolio Kanban boards tried to reconnect business goals to engineering work. But they added process overhead without resolving the core issue: the translation between business intent and working code still happened manually, inside individual teams, with all the interpretation and drift that implies.
What SDD Actually Changes
SDD is made possible by a single recent shift: AI systems can now reliably translate precise natural-language specifications into working code. That capability breaks the assumption that manual translation was inevitable.
In an SDD workflow, specifications are not inputs to development. They are the development. A Product Requirements Document is not a guide for engineers — it is the artefact from which implementation plans are generated, and from which code is produced. When you change a requirement in the PRD, affected technical decisions update. When you modify a user story, corresponding API endpoints regenerate. The document and the system stay in sync because the document produces the system.
Three Stages of the SDD Workflow
1. Specification — A product idea is developed iteratively with AI assistance into a precise, structured PRD. AI asks clarifying questions, identifies edge cases, and flags ambiguities with explicit markers rather than guessing. What would traditionally require days of meetings and documentation can happen in hours.
2. Implementation Planning — From the PRD, AI generates a detailed implementation plan. Every technology choice carries documented rationale. Every architectural decision traces back to a specific requirement. Organisational constraints — security policies, database standards, authentication requirements — are applied automatically.
3. Code Generation and Testing — Code is generated from the implementation plan. Crucially, test scenarios are part of the specification itself, not an afterthought. Tests define expected behaviour before code is written, ensuring that what gets built matches what was specified.
The Business Case for Executives
Faster, More Predictable Pivots
In traditional development, a significant requirement change triggers a cascade of manual updates across documentation, design, and code. Each manual step introduces lag and the risk of inconsistency. SDD transforms this into a systematic process: change the specification, regenerate the affected plan, regenerate the affected code. The gap between decision and implementation compresses from weeks to hours.
For businesses operating in competitive, fast-moving markets, this is a structural advantage.
Intent Preserved as an Asset
One of the least discussed costs of traditional development is the erosion of institutional intent. The original rationale behind architectural decisions disappears into git commit messages and the memory of engineers who may no longer be on the team. Specifications and code diverge. The business no longer has a readable, accurate account of why the system is the way it is.
SDD keeps intent visible and current. The specification is always accurate because it generates the code. When new team members join, auditors arrive, or regulators ask questions, the answer to "why does the system work this way?" lives in a document that is both readable and up to date.
Reduced Technical Debt at the Source
Technical debt is largely a product of manual translation. Engineers make reasonable decisions in the moment that diverge from original intent. Those decisions accumulate. Over time, the cost of change rises. SDD addresses this at the source. Because code is generated from specifications, refactoring means updating the specification — not untangling years of accumulated interpretation.
A New Basis for Governance
For CIOs and CTOs, SDD offers something previous methodologies could not: a single, auditable source of truth that bridges business intent and technical implementation. Compliance requirements, security constraints, and architectural principles can be encoded directly into the specification layer, ensuring that every generated system automatically inherits them.
Constitutional Governance
SDD introduces the concept of a development constitution — a set of immutable architectural principles that govern every specification and every generated implementation. Simplicity constraints, test-first mandates, integration requirements, and modularity rules are enforced at the specification level, not left to individual engineering discretion. For enterprises managing complex technology estates, this is governance infrastructure.
What Changes for Your Organisation
SDD does not eliminate the need for engineering expertise. It redirects it. The shift is from mechanical translation — turning specifications into code by hand — toward specification quality. The most valuable skill in an SDD organisation is the ability to write precise, unambiguous, complete specifications that AI can execute reliably.
This changes the profile of what strong engineering leadership looks like. It elevates the role of product thinking, systems design, and clear expression of intent. It reduces the premium on the ability to hold large, complex codebases in memory.
Key Artefacts in a Spec-Driven Workflow
SDD produces a set of structured Markdown documents that together form the complete, auditable record of a system's intent and design. Each artefact has a distinct role and is either authored by a human or generated by AI from an upstream document.
| Artefact | Filename Convention | Purpose | Authored By |
|---|---|---|---|
| Product Requirements Document | PRD.md | Captures business intent, user stories, scope, and constraints. The root of the specification chain. | Human (AI-assisted) |
| Implementation Plan | PLAN.md | Maps every PRD requirement to specific technical decisions, components, and architecture choices with documented rationale. | AI (from PRD) |
| Development Constitution | CONSTITUTION.md | Defines immutable architectural principles — simplicity rules, security constraints, integration mandates — applied to every downstream artefact. | Human |
| API Specification | API.md | Describes all interfaces, endpoints, request/response shapes, and error contracts derived from the PRD. | AI (from PLAN) |
| Test Scenarios | TESTS.md | Defines expected behaviour and acceptance criteria before code is written. Used to verify generated implementations. | AI (from PRD) |
| Architecture Decision Records | decisions/ADR-NNN.md | Captures individual architectural choices, alternatives considered, and the reasons for decisions. Generated inline during planning. | AI (from PLAN) |
| Changelog | CHANGELOG.md | Tracks specification changes and their downstream effects on plan and code, maintaining traceability over time. | AI (from diffs) |
The critical property of this artefact chain is directionality: changes flow downward from the PRD. Modifying a requirement regenerates the PLAN, which in turn regenerates affected API, test, and implementation artefacts. No manual propagation. No silent drift.
The Honest Caveats
SDD is not a silver bullet, and it is not fully mature. Practising it today requires assembling tools, maintaining discipline, and accepting that the methodology is still evolving. AI code generation is reliable but not infallible. Specifications still require human judgement to write well. The feedback loop between production systems and specification updates is a discipline that teams need to build.
What SDD represents is not a solved problem but a directional shift. The organisations that learn to write excellent specifications now — precise, complete, unambiguous — will be the ones best positioned as AI generation becomes more capable and the tooling matures.
References and Further Reading
- GitHub spec-kit — Spec-Driven Development Guide — The reference implementation of SDD tooling and workflow conventions. github.com/github/spec-kit
- Agile Manifesto — agilemanifesto.org. The original principles behind iterative development — and the implicit trade-offs that SDD now addresses.
- Scaled Agile Framework (SAFe) — scaledagileframework.com. Enterprise Agile framework context for understanding where SDD sits relative to existing delivery structures.
