Spec-Driven Development – Adoption at Enterprise Scale

Evolution of Intent Articulation: Instructions to Dialogue

The past year has brought significant shifts in AI-augmented coding. We have moved from copying code between IDEs and chat interfaces to using purpose-built CLIs and AI-native editors.

Vibe Coding – Instructional Interaction

Yet even as tools evolved, “vibe coding” (iterating with AI until the code works, without deliberate upfront planning) interactions with AI remained largely instructional in nature, one prompt at a time. The implementation itself served as context for further steering.

Figure 1: Vibe coding workflow

Plan Mode – Better Preparation

Plan mode (where AI drafts an execution plan for human review before writing any code) marked a major evolution in AI coding that enabled early identification of intent alignment issues. By requiring humans and AI to deliberate and agree on a list of tasks, related validation mechanisms, etc., before jumping into implementation, it extended independent execution times and delivered more complete results. This was our first “kick-off ceremony” with AI that recognized that better up-front conversation yields more aligned outcomes.

However, the interaction between humans and AI remains tactical and instructional. Since plans don’t typically persist beyond execution, the implementation becomes the primary context for refinement and additional features.

Figure 2: Plan Mode Workflow

Spec-Driven Development – Human and AI Dialogue

Spec-Driven Development emerged as AI models began demonstrating sustained focus on complex tasks for extended periods of time. Operating in a continuous back-and-forth pattern, instructional interactions between humans and AI is not the best use of this capability. At the same time, allowing AI to operate independently for long periods risks significant deviation from intended outcomes. We need effective context engineering to ensure intent alignment in this scenario. SDD addresses this need by establishing a shared understanding with AI, with specs facilitating dialogue between humans and AI, rather than serving as instruction manuals.

Figure 3: Spec-Driven Development high-level workflow

This article explores how enterprises can adopt SDD by examining immediate tooling gaps that need addressing, integration patterns with existing workflows that help teams experience value quickly, and the stakeholder collaboration changes necessary to make SDD sustainable at scale.

Enterprise Adoption: Why It Matters, and Why It’s Not a Technical Rollout

SDD already demonstrates clear value in several technical dimensions. In addition to enabling longer, more focused independent execution, it helps address token usage and context window management, enabling optimal and cost-effective usage of AI agents.

However, the most significant impact of SDD may be cultural rather than technical.

Conversations over Instructions

When senior engineers collaborate, communication is conversational, rather than one-way instructions. We achieve shared understanding through dialogue. That shared understanding defines what we build. SDD facilitates this same pattern between humans and AI agents, where agents help us think through solutions, challenge assumptions, and refine intent before diving into execution.

Figure 4: Spec-Driven Development detailed workflow

Figure 4 illustrates how SDD tools help structure our dialogue with AI. While some tools use distinct discovery, design, and task phases, others may have more granular or fluid approaches. What matters is creating opportunities for iterative intent articulation with AI facilitated through specifications. While newer models bring longer context windows and better reasoning abilities to the table, we cannot extract the most out of them unless we treat AI as a co-creator of our solutions.

Collaborative Context over Smarter Models

At a conceptual level, with Spec-Driven Development, teams can break down features into constituent aspects that guide autonomous execution (Figure 4):

• What (Discover) is the business context defining the use case we’re servicing?
• How (Design) is the technical approach mapping that use case to our architecture? thinking through modules, implementation mechanics, and communication channels.
• Tasks that detail execution plans agents can act on, with clear verifiability and opportunities for parallelization.

But even this conversational approach, when practiced individually, misses the larger opportunity. While AI wears different hats (as illustrated in Figure 4) to help author different specs, it does not make sense for a single developer to go through the entire process alone.

Teams building execution context through cross-functional specs are superior to individuals optimizing prompts or chasing smarter models. SDD can help by leveraging specs as translation layers that capture evolving stakeholder dialogue. For example: Product defining “what”, Architecture shaping “how”, Engineering helping structure “tasks”, etc.

As building becomes faster and cheaper, the bottleneck has shifted. If we keep ourselves preoccupied verifying AI output, the backlog is starved for fresh ideas. In short, a review-based approach alone cannot scale when using AI agents.

It is in this situation where teams need to operate collectively, ideating and solving together to direct agent swarms building in parallel. Organizations that master this approach can free humans to spend more time on strategic problem-solving while agents simultaneously handle implementation across multiple workstreams. This team-level orchestration, not individual efficiency gains, is where SDD becomes non-negotiable for enterprises.

The Risk of “SpecFall” / “Markdown-Monster”

Given this significant cultural dimension, treating SDD as a technical rollout leaves substantial value on the table. SDD adoption is an organizational capability to develop, not just a technical practice to install. Those who have lived through enterprise agile adoption will recognize the pattern. Tools and ceremonies are easy to install, but without the cultural shifts we risk “SpecFall” (the equivalent of “Scrumerfall”).

Adopting spec-driven workflows without changing how product, architecture, engineering, and QA stakeholders actually work together risks creating a “markdown monster” that generates layers of outdated documentation on arrival. The key is treating specs as both the conversation medium between stakeholders and the context engine for AI agents.

Challenges in Adopting SDD at Scale

The multi-layered, multi-stakeholder reality of enterprises exposes several gaps in current SDD tooling. Most popular tools exhibit one or more of these.

Developer-Centric Tooling

Most popular SDD tools have socialized their use within Git repositories, code editors, and CLIs. This positioning makes sense for individual developers but creates friction for cross-functional collaboration. When specs live in code repositories, product managers and business analysts (the very people who should be defining the “What”) face barriers to participation.

Mono-Repo Focus

Current tools typically keep specs co-located with code in a single repository. This may work for simple applications, but enterprise systems are rarely mono-repos. Modern architectures span microservices, shared libraries, infrastructure repositories, and platform components. When your feature requires changes across six different repositories, where does the spec live? How do you maintain coherence across these boundaries? The tooling doesn’t provide clear answers.

Lack of Separation of Concerns

As an extension of the developer-centric approach, current tools don’t clearly separate artifacts by their evolution pace and audience.

Architecture decisions like schema design and business context such as acceptance criteria are more strategic, involving a different audience and approval workflow. The task list is highly tactical in nature and most likely reviewed only by the engineer who oversees the execution itself.

Yet most tools organize everything under feature-specific folders, making it difficult to extract domain-level views or track technical evolution across features. While agents could theoretically extract holistic views, the question remains: Should these artifacts with fundamentally different lifecycles live together in the first place?

Unclear Starting Points

Should teams begin with a product requirements document covering the entire application? A specific feature pulled from an existing backlog? Most enterprises have qualified backlogs in tools like Jira or Azure DevOps, representing weeks or months of prior refinement. But current SDD tools don’t integrate with these systems.

Can teams pull features from existing backlogs into SDD workflows? How do they keep backlogs synchronized with evolving specs? The lack of clear integration patterns is a hurdle for teams that want to adopt SDD without completely sacrificing their existing work backlogs and planning investments.

Undefined Collaboration Patterns

Not all stakeholders participate in all phases. Product teams focus on feature definition with only high-level technical awareness. Architects concentrate on system design and crosscutting concerns. Platform engineering ensures consistency with organizational standards, but current tooling doesn’t map these distinct involvement patterns. When does each stakeholder’s contribution begin and end? How do they know when to review? Who approves what? Lack of clarity in these collaboration mechanics can hinder sustainable adoption.

Wide Range of Spec Styles and Granularity

Each SDD tool takes a different approach to specifications. Most use markdown files, but formats vary from structured user stories and acceptance criteria (GitHub SpecKit) to patterns like EARS (Amazon Kiro). Some generate machine-parseable formats for schemas and message payloads (SpecKit generates OpenAPI for HTTP APIs), while others embed tests directly in specs to validate alignment (Tessl).

Spec file organization strategies also differ. Tools may organize specs at the feature level (e.g., SpecKit and Kiro), maintain a single evolving spec, or use hybrid approaches with both top-level and archived feature specs (OpenSpec). Some maintain one-to-one mappings between specs and code artifacts. Spec verbosity also varies across tools.

Given this range in approach and granularity, choosing a tool and specification style can feel daunting. Each tool brings opinions that shape your process, which can be helpful when teams are new to SDD, but limiting if the tool’s assumptions don’t align with how your teams actually work.

Specification to Implementation Alignment

While the ultimate goal of SDD is intent-to-implementation alignment, the process involves two distinct transitions:

• Intent-to-specification
• Specification-to-implementation

Intent-to-specification alignment happens through dialogue and review. The elephant in the room is specification-to-implementation alignment. This alignment validation becomes a key factor when choosing an SDD tool or approach, since each specification style has inherent verifiability characteristics.

Unclear Brownfield Adoption Path

Be it enterprise or even smaller teams, we already have existing code that needs to be maintained or features to be added. In those circumstances, should our first step be to create specs by having LLMs read through the entire project, or should we build up specs incrementally, focusing on each area that needs attention? There are two aspects that can get in the way.

When existing applications are large, it may be impractical to have an LLM create specs without exceeding context limits. Even if we managed to create the spec, it can be quite large, which then creates review difficulties. While backtesting the spec against the code may be one way of gaining some level of confidence, the point of specs, as we have been discussing, is to capture intent. Intent requires human review. Really large specs for existing systems can be impractical to review.

While some tools (such as OpenSpec, which follows an incremental approach to capturing existing information in specs) claim to be geared towards brownfield contexts, doing it at scale, where the context lives across repos and projects, the lack of clarity around this can be a hurdle for adoption.

Enabling SDD Adoption Without Boiling the Ocean

The gaps highlighted above are tactical hindrances, not fundamental barriers. Organizations can experience SDD value by first adapting practices to existing workflows, then evolving toward more AI-native patterns once benefits become evident.

Building a Spec-Driven Development tool from scratch might seem appealing, but the cost of socializing it can be expensive. Picking an extensible tool closest to your philosophical approach and customizing it provides a more practical path to learn from experience.

Here are practical measures that address several entry barriers to existing tools.

Integrating with Existing Product Backlogs

Most SDD tools emerged from developer-centric contexts, so starting with engineering teams makes sense. But this shouldn’t require product managers to learn Git workflows. MCP servers provide a practical integration layer.

Developers pull stories from Jira, Linear, or Azure DevOps directly into their SDD workflows while progress updates flow back to backlog tools.

Product Backlog Integration Example

OpenSpec has a three-step SDD workflow where a change typically goes through “proposal”, “application”, and “archival” phases.

Figure 5-a: OpenSpec Spec-Driven Development workflow

In the modified workflow, shown in Figure 5-b, we integrate with a product backlog over MCP to keep issues updated with appropriate status. Instead of the default setup, where changes are proposed via CLI input:

• Picking up an issue from backlog for “proposal” moves it to “Todo” state
• As we move to implementing the same in “application” phase, the issue moves to “In Progress”
• Subsequently upon “archival”, the issue is moved to “Done” state

Figure 5-b: OpenSpec modified SDD workflow integrated with product backlog through MCP

This simple integration respects the reality that product teams already invest significant effort curating backlogs. Rather than duplicating work in new systems, we bridge to where it already lives.

Multi-Repository Orchestration

The separation achieved between business context and technical implementation details is crucial for multi-repository SDD orchestration.

Consider a feature touching both the front end and back end or spanning multiple microservices. Repository responsibilities and integration patterns need to be established so we can factor work into appropriate pieces and coordinate across boundaries.

Figure 6: Product owner, architect, and dev collaboration facilitated through SDD workflow

Figure 6 illustrates how product owner, architect, and developer collaborate through the SDD workflow across three distinct phases.

Discover Phase

The product owner works with AI to articulate business intent (the “what” and “why”) behind the feature. This conversation happens in the backlog context, where business stakeholders already operate.

Design Phase

The architect collaborates with AI to determine the technical approach. For features spanning multiple repositories, this phase breaks down the parent story into repository-specific sub-issues. Each sub-issue represents work scoped to a single repository with clear technical boundaries and dependencies. Crucially, these sub-issues remain in the backlog, maintaining visibility for product and engineering teams to track progress.

Task Phase

The developer works with each sub-issue in its respective repository and works with AI to detail implementation tasks. This approach is where technical execution details such as schema definitions, module breakdowns, etc., live. These artifacts belong in the repository because they’re tightly coupled with the codebase they’ll modify.

With this separation, business context stays visible on product boards while technical implementation details remain in the repositories themselves.

Importantly, architects don’t necessarily have to manually decompose every story. Instead, they can establish the harness for coding agents by documenting repository boundaries, integration patterns, and architectural constraints. An agent guided by this context can automatically superimpose these guidelines onto incoming stories, generating appropriate sub-issues for each affected repository.

When architectural refactoring is needed, the original business story remains stable while new architectural breakdowns generate different sub-issues across repositories. The business intent doesn’t change, but the technical implementation strategy evolves.

Here is an example of a Claude Code instance updating Linear backlog based on code repo responsibilities, which are based on architecture breakdown context set up at the project level.

Figure 7: Front end and back end sub issues being generated based on architecture context

Role-Specific Contributions

Similar to how architects contribute architectural guidelines, other roles such as infrastructure specialists, performance experts, and security professionals establish their own context harnesses. Each harness captures domain-specific constraints and patterns.

The key again is configuring agents to superimpose these role-specific guidelines onto incoming stories as they become work items and tasks. Rather than manual review gates, specialized agents apply their domain expertise automatically, such as:

• Infrastructure agents adding deployment constraints.
• Performance agents flagging optimization needs.
• Security agents identifying compliance requirements.

This sets the foundation for orchestrating multiple specialized agents, each layering their guidance to transform business intent into complete, implementable plans.

Specification Style and Validations

This can be a subjective topic. Here are aspects to consider for practicality and enterprise suitability:

Top-Level Steering Ability

Concerns such as architecture, code organization, and technical best practices span across features and influence spec detailing rather than belonging in individual specs. Default support for such mechanisms (e.g., Constitution in SpecKit and Steering Docs in Kiro) or extensibility to achieve this goal is important.

Top-Level Spec View

Having the ability to extract or readily view spec artifacts that closely reflect current application state helps with validation.

Reasonable Granularity

While achieving alignment is important, tools that generate artifacts almost identical to actual code can be double-edged. From a review burden perspective, keeping specs “human reviewable” in terms of size matters. Sheer volume can make detailed review daunting.

It is more practical to prioritize specification styles that facilitate meaningful conversations to promote better dialogue and thinking through solutions in concert with AI. Validation, while important, should not impede this primary objective by influencing specification style in ways that create pushback.

Adopting SDD in Brownfield Contexts

Rather than attempting to retroactively spec out entire systems, incremental exploration is more practical. One of the primary reasons to use SDD is to reduce context burden on coding agents by feeding them exactly what they need to know for a given area of work. The spec needs to be most granular near the area of change. This granularity also reduces the review burden highlighted in the previous sections.

This approach is not dissimilar to techniques we use while refactoring legacy code in a test-driven approach. We try to cover as much of the existing logic around the area of change as possible, and once the confidence is reasonable, we then isolate that area effectively, thereby helping the coding agent focus on that area rather than polluting the context window with larger details.

With time, specification coverage grows organically with each modification. Bug fixes, feature additions, refactoring efforts all become opportunities to add specifications for the code being touched. This organic approach naturally creates reasonably sized, human-reviewable contexts focused on areas of active development, avoiding both the impractical task of comprehensively “spec’ing” entire legacy systems and the review burden that would create.

At this point, we’ve explored adapting SDD to existing organizational patterns without disrupting proven workflows. Once teams see the value, the question shifts: How should organizations evolve toward more AI-native delivery patterns? The answer lies in treating specifications not as static artifacts but as living guidelines that improve through feedback loops.

Long-Term Direction

A question that often comes up in early SDD adoption stages is whether we should bother going through the specification route for minor changes or bug fixes. Can we not directly update the code instead? This question becomes more relevant as organizations move toward spec-native development.

The answer determines whether specifications remain secondary documentation or become a first-class engineering surface. In mature SDD adoption, every change (be it major features or minor bug fixes) must flow through specifications. This is not so much about following a process. Instead, it is about recognizing that specs are the primary interface for directing agent execution. This is indeed a big shift in process as we adopt AI-native SDLC.

Historically, we removed direct access to modify code on servers because these direct changes would be overwritten when the next release deployed. By removing direct server access, teams had to make fixes in the source of truth, the code in version control, and take those changes through a proper release pipeline to redeploy. This server access removal ensured fixes persisted in future releases.

Similarly with AI-generated code, a code issue is an outcome of a gap in the specification. Direct modifications in code may further widen this spec gap. Because of non-determinism in AI generation, that gap keeps resurfacing in different forms whenever the code is regenerated based on that spec. Continuing to manually patch the code will not scale, especially with the volume of code that AI can generate in short durations. Feeding back into the spec to close the gap is more sustainable in comparison.

Therefore, we need to make it easy to “do the right thing” and work at the spec level, rather than the code level. For example, while code still remains an artifact we version control and review, authoring it may be limited to AI coding agents.

Harness Governance

In their InfoQ article “Spec Driven Development: When Architecture Becomes Executable”, Leigh and Ray introduce the concept of SpecOps where they establish specification authoring as a first-class engineering surface.

When specifications become the primary way work enters the system, they deserve the same quality practices, version control, review processes, and continuous improvement that we apply to production code.

This shift has profound implications. If agents execute from specs, then spec quality directly determines implementation quality. A bug isn’t just a code defect, it’s an opportunity to improve the specifications and harnesses that generated that code. This is where the feedback loop becomes critical.

When bugs surface, understanding their origin is essential:

Spec to Implementation Gap

The specification was clear, but the implementation diverged. This problem requires strengthening task completion validation mechanisms so similar gaps don’t recur. The harness needs better validation agents or more explicit implementation constraints.

Intent to Spec Gap

A use case detail was missed during deliberation, so the specification itself was incomplete. This issue requires improving the spec elicitation process by adding question patterns, research steps, or analysis frameworks to the harness so future stories capture these details up front.

These problems aren’t just bug classifications. They are quality metrics for our context harness. Each gap reveals where the harness needs refinement. Quality engineering’s role evolves from validating implementations to validating and improving the harnesses that guide agent execution.

Figure 8: Harness feedback loop

Figure 8 illustrates this continuous improvement cycle. When validation agents identify gaps between specifications and implementations, those insights feed back into harness refinement. Over time, the harnesses encode more domain knowledge, anticipate more edge cases, and generate more complete specifications. The system learns from its mistakes not by patching implementations, but by improving the context that shapes future implementations.

By treating specification authoring as an operational discipline with feedback loops, quality metrics, and continuous improvement, individual features require less manual refinement. The harnesses carry accumulated wisdom forward.

Pragmatic Path to Implementation Alignment

It is fair to question the value of SDD without perfect alignment between intent, spec, and implementation. While it is possible to engineer validations that leverage specs to independently test implementations, the degree of achievable alignment varies based on spec type. Optimizing for perfect alignment from the get go may involve specs becoming overly granular, leading to review fatigue that undermines adoption.

Looking at it pragmatically, we face alignment issues even between human team members. At a human level, we fix these issues through mechanisms that reduce future miscommunication. Similarly, the retrospective-style feedback loop helps improve alignment over time. Each gap identified strengthens the harness, making future specifications more complete and implementations more aligned.

This shift represents the fundamental transformation in how quality works in agent-orchestrated development. Rather than reviewing finished implementations, quality specialists validate the context harnesses, the constraints they encode and that these validation mechanisms catch divergence early. The role becomes one of harness quality rather than implementation quality.

Closing Note

With AI agents capable of sustained autonomous execution, the bottleneck in software delivery has moved. It’s no longer about how fast we can write code, rather it’s about how effectively we can articulate intent. As Adrian Cockcroft framed it at QCon SF, we’re learning to direct swarms of agents. This approach to building is a fundamentally different organizational capability than managing individual contributors.

SDD enables this shift, but only if we recognize what’s actually changing. Product teams need to articulate business context with enough clarity for agents to understand user value and acceptance criteria. Architects must encode technical constraints and integration patterns into reusable harnesses. Engineers transition from writing implementations to validating that agent-generated code aligns with specifications. Quality specialists shift from testing finished implementations to ensuring the context harnesses themselves are robust.

With SDD, the conversation is not just between humans anymore. Specifications become the shared interface where product, architecture, engineering, and quality collaborate to build execution context that gets translated into action by AI agents. The feedback loop in specification authoring is where that collaboration happens.

Those who approach SDD as a technical rollout will get technical benefits such as better token usage, longer agent runs, fewer hallucinations. Those who approach it as an organizational transformation will unlock the ability to direct agent swarms effectively, freeing human creativity for strategic problem-solving while agents handle implementation across multiple workstreams.

This transformation is not a future state. It is available now, for organizations ready to make the shift.