Software specifications have always been disposable scaffolding. A temporary artifact for human-to-human communication before the “real work” began. That era is over.
We’re entering a paradoxical phase where the most critical, valuable output of your engineering team isn’t code, it’s the specification that generates the code. GitHub’s Spec Kit is not a niche tool, it’s the canary in this coal mine. It orchestrates “spec-kit phases via sub-agent delegation to reduce context pollution” and validates “project documentation with automated checks, AI-driven workflows, and spec-kit hooks.” This isn’t about being organized, it’s about creating executable artifacts that define your system’s what before its how.
Yet developers are having a collective déjà vu moment. As one astute observer in a recent software architecture discussion noted, we’re basically reinventing the Software Design Description (SDD) document from 30 years ago, just with agents doing the implementation. The question isn’t whether spec-first is happening, it’s what kind of spec-first you’re practicing, and who owns the consequences.
The Spec-Driven Spectrum: From Lint to Law
The conversation around “spec-driven development” masks a critical continuum of commitment. Borrowing from thought leadership on martinfowler.com, we can identify three distinct rungs on this ladder:
Level 1: Spec-First (The Polite Suggestion)
Here, you write a specification, use it to guide development (by humans or AI), and then largely abandon it. The spec has a lifespan roughly equal to the feature branch. GitHub Spec Kit’s default workflow, branch per spec, focused implementation, often embodies this. It’s useful for alignment, but it’s architectural lip service. Once the code exists, the spec becomes a historical artifact that drifts from reality faster than your average README.
Level 2: Spec-Anchored (The Enforced Contract)
This is where the rubber meets the road. The spec isn’t just written, it’s mechanically enforced. On every pull request, CI/CD runs contract tests (think OpenAPI schema validation, behavioral contract tests), and the build fails if implementation drifts from specification. The spec and the code coexist as peer artifacts, validated against each other continuously. This is the sweet spot for many production systems where interfaces matter, and misunderstanding is expensive. It’s NetFlix treating its federated GraphQL schema as a binding contract.
Level 3: Spec-as-Truth (The Single Source)
You only edit the spec. The code is a generated, disposable output. If you edit the generated code, the next regeneration wipes your changes, that’s the point. Google’s Protocol Buffers and gRPC stubs operate at this level perfectly. For application code, frameworks like Tessl push this pattern with LLM-driven regeneration. The litmus test is brutal: delete your src/ directory, hand the spec to an agent, and regenerate. If you get a functionally identical system back, you’re practicing spec-as-truth. If not, you have undocumented institutional knowledge scattered across your codebase that still belongs to humans.
The Ghost in the Spec Machine: Who Feels the Friction?
The brutal insight from developers wrestling with this shift is about experiential feedback loops. An LLM doesn’t experience resistance. It doesn’t get that sinking feeling when a beautiful, spec-compliant API turns out to be a nightmare to consume. It doesn’t sense that “this is too complex to use” or that an abstraction is leaking.
One engineer recounted an experiment where a detailed spec was fed to an LLM for implementation. The agent executed flawlessly. Later, the engineer gutted the core logic to rewrite it by hand, discovering that the original design in the spec was fundamentally unsound. The implementation process revealed cleaner abstractions, more consistent APIs, and better performance. The AI had blindly built the flawed spec.
As a conversation with an LLM distilled it: “The key isn’t that AI can’t refactor, it’s that AI doesn’t experience resistance. The awkward I, the sense that ‘this is too complex to use’, these don’t register as signals to redesign. The deeper point: your spec wasn’t wrong, it was untested. AI excels at executing tested designs. The testing happens through the friction of implementation, and that friction is experiential, not analytical.”
This is the core trade-off of spec-driven AI development. You decouple design from implementation at the risk of decoupling design from reality.
The GitHub Spec Kit Blueprint: A Case Study in Tooling
The GitHub Spec Kit provides a concrete view into the mechanics of this new workflow. It’s not just a library, it’s an opinionated framework for turning natural language into running systems.
The typical workflow is a phased funnel:
1. /speckit.constitution: Establish project-wide principles (“We value testability over brevity”).
2. /speckit.specify: Define what to build, focusing on user stories and outcomes.
3. /speckit.plan: Define how to build it, choosing the tech stack and architecture.
4. /speckit.tasks: Break the plan into an actionable, ordered task list.
5. /speckit.implement: Execute all tasks, generating code.
The toolkit supports over 30 AI coding agents, from GitHub Copilot to Devin, and boasts a sprawling ecosystem of community extensions for everything from security governance (spec-kit-security-review) to multi-agent orchestration (spec-kit-fleet). This isn’t a toy, it’s an industrial-grade attempt to standardize a new development protocol.
The Architectural Accountability Vacuum
This brings us to the central, uncomfortable question of this paradigm shift: Who owns a system where the design and the implementation are separate artifacts produced by different entities?
In traditional development, the human architect and the human coder are often the same person, or at least part of the same team. The pain points of a bad design are felt by the person implementing it, creating a natural feedback mechanism for refactoring.
In spec-first AI development, this loop is broken. The spec author (a human) defines success criteria. The AI agent (the machine) attempts to fulfill them. If the spec is flawed but executable, the AI will produce flawed but executable code.
The ownership model fractures:
* Who owns the quality of the generated code? Is it the spec author for writing an ambiguous requirement? The agent operator for choosing a suboptimal model? The platform (Spec Kit) for providing the scaffolding?
* Who owns the architecture? Is it the person who wrote “use microservices” in the plan, or the agent that chose NestJS over FastAPI, established the module boundaries, and defined the inter-service communication patterns?
* Who owns the technical debt? When an AI generates a verbose, inefficient, or tightly coupled solution that technically meets the spec, who is responsible for the resulting maintenance burden?
The rise of agents capable of complex multi-agent orchestration in production only amplifies this problem. You’re not just handing off to one AI, you’re spinning up a team of them. The industry is racing to build tools for deploying agentic workflows efficiently, but we’re building the operational harness before we’ve solved the fundamental accountability question.
The Human’s New Role: Spec Therapist and System Psychiatrist
If AI agents become our primary code-generating workforce, the human role doesn’t vanish, it transmutes. We are no longer primarily builders, we become design validators and system psychologists.
Our job shifts upstream:
1. Specification Therapy: We must learn to write specs that are not just clear to other humans, but robust against machine misinterpretation. This requires a new ruthlessness about ambiguity. The spec isn’t a conversation starter, it’s a blueprint that cannot tolerate “you know what I mean.”
2. Constraint Engineering: We must define the negative space, what the system must not do. This is where governance, security policies, and architectural guardrails become first-class citizens of the spec, not afterthoughts. Tools like Spec Kit’s extensions for “OWASP LLM Threat Model” and “Security Review” are early attempts to codify this.
3. Testing the Friction: We must build mechanized ways to simulate the “experiential friction” AI lacks. This could mean rigorous, automated usability testing of generated APIs, performance benchmarking as a spec requirement, or architectural analysis tools that run on the spec itself before a single line of code is generated.
4. System Cohesion Custodian: As features are generated from disparate specs by potentially different agents, someone must own the holistic view. Does the login flow generated from spec-004-auth.md coherently integrate with the user profile generated from spec-007-user-profile.md? The AI agents, focused on their discrete tasks, likely won’t ensure this. The human becomes the integrator.
The Inevitable Drift: Spec-Anchored as the New Normal
Given the accountability vacuum of pure spec-as-truth and the weakness of throwaway spec-first, spec-anchored development emerges as the most plausible near-term future for serious software production.
In this model, the spec is the source of truth for a feature’s intent, but the code is the source of truth for its implementation. The relationship is symbiotic and enforced. Every change to one triggers a validation check against the other. This creates a living, breathing document that actually reflects the system.
This requires tooling that doesn’t just generate from specs, but bi-directionally syncs specs and code. Imagine a linter that flags: “Your implementation of this endpoint now returns a 404 on condition X, but your spec still says it returns a 200. Update the spec or revert the code change.” This is the logical next step for platforms like Spec Kit. The community extension spec-kit-sync hints at this direction, offering “AI-assisted resolution with human approval” for drift.
The business impact of AI adoption failures often stems from this kind of incoherence between promise (the spec/plan) and reality (the generated system). Spec-anchored tooling is the antidote.
A New Class of Bugs: Spec-Impl Misalignment
Traditional software bugs live in the code: null pointer exceptions, off-by-one errors, memory leaks. In the spec-first AI era, we introduce a new, more insidious bug class: Spec-Impl Misalignment.
This is where the code perfectly satisfies the literal specification but fails to solve the actual human problem. The spec said “sort the list alphabetically.” The AI sorts the list alphabetically. The human user wanted it sorted by last name, but the data field was called fullName. The AI, lacking common sense or the data context required for agent accuracy, did exactly what it was told.
Debugging these failures is a meta-problem. You don’t debug the code, you debug the specification and the context given to the AI. Your toolchain shifts from debuggers and profilers to spec analyzers, ambiguity detectors, and “common sense” validation suites.
Where Do We Go From Here?
The move to spec-first driven by AI agents isn’t just a productivity hack. It’s a fundamental re-architecting of the software development value chain. The highest-leverage activity is no longer writing the implementation, it’s writing the specification that correctly guides the implementation.
This demands a maturation of our tools and our thinking:
* Specification Languages: Markdown and natural language are starting points, but they’re notoriously ambiguous. We’ll likely see the emergence of more structured, constrained specification formats that balance human readability with machine precision.
* AI for Spec Validation: Just as we use AI to write code, we’ll need AI to critique specifications, identifying contradictions, uncovering ambiguous language, and suggesting edge cases before they become bugs.
* Ownership Frameworks: Organizations will need to establish clear RACI matrices for spec-driven projects. Who approves the spec? Who validates the generated output? Who is accountable for the final system’s behavior? This is a core component of any mature AI Operating Model.
* Shift in Hiring: We’ll value systems thinkers who can define robust problems over virtuoso coders who can solve ill-defined ones. The capability of specialized coding models is rapidly commoditizing, the ability to direct them effectively is not.
The era of human-as-code-monkey is ending. The era of human-as-specification-therapist, system-psychologist, and intent-engineer is beginning. The question isn’t whether your team will adopt spec-first practices, it’s whether you’ll control the spec, or let it control you. Your system’s soul depends on the answer.
