Spec-Driven Development: From Programmer to System Architect

AI agents are evolving from coding assistants to independent actors in software development. Spec-Driven Development (SDD for short) is a new approach that systematically controls AI—and fundamentally changes the role of developers: away from coding and toward architecture, specification, and orchestration.

AI has long been more than just an autocomplete assistant. AI agents are increasingly taking on entire work packages, thereby becoming an active part of the entire software development process—the agent plans, designs, implements, and tracks its own progress. But the more AI evolves from a “helper” to an “agent,” the more our approach to building software must change as well.

A promising approach in this shift is specification-driven development (Spec-Driven Development). This article explores what Spec-Driven Development means, how it works, and how it changes things for developers.

The documents used are based on the artifacts of traditional software development processes, which are typically maintained as Markdown documents in SDD.

• Requirements Specification
  The requirements specification describes what the system is supposed to do. It is also referred to as a requirements document and describes:
  • Features
  • Use Cases
  • Behaviors
  • Acceptance Criteria
  • Delimiters
    
• Technical Specification
  The technical specification describes how the system is to be implemented. It is also referred to as the requirements specification and contains:
  • Architecture & System Design
  • Technology Decisions
  • Data Models
  • APIs
  • Detailed implementation of the requirements specified in the requirements specification
    
• Work Packages
  The technical specification is then typically broken down into implementation tasks to be carried out by the AI agent.

At first glance, this may resemble the classic waterfall model. The key difference, however, is that the process is not designed for the entire system but is applied specifically to individual features—essentially as a “waterfall process on a small scale” at the feature level.

In addition to traditional specification documents, spec-driven development tools typically offer additional control options via separate documents containing general rules and guidelines—essentially, a form of documentation outlining system guidelines. While specification documents are created for individual changes or features, these instructions apply to all modifications. Specifications may include:

• Non-functional requirements (performance, security, reliability)
• Fundamental architectural decisions
• Defined technology stack
• Test Procedure
• Coding Conventions
• but also rules regarding the format, scope, and quality of the specifications themselves

Note: AI agents typically have similar mechanisms (for example, the copilot-instructions.md or the emerging AGENTS.md standard). It makes sense to have these files reference each other so that system-wide rules need to be maintained only once and redundancies are avoided.

There is now a growing number of specialized tools available for the practical implementation of spec-driven development. They differ primarily in terms of workflow, customizability, and how they handle long-lived specifications. Among the best-known examples are GitHub Spec Kit and OpenSpec.

GitHub Spec Kit

One possible tool for spec-driven development is GitHub Spec Kit. It is developed by GitHub, but can be used not only with GitHub's own coding agents but also with a wide variety of others.

A Python command-line tool called “specify” initializes Spec Kit in a project by placing certain predefined prompts (known as slash commands), as well as templates and some scripts, in the project directory.

In Spec Kit, the system-wide instructions are called "Constitution," which is intended to signal that they are non-negotiable. When creating a new project, you are initially guided through the process via /speckit.constitution.

The main commands for mapping the SDD workflow are:

• /speckit.specify for creating the technical specification.
  Optionally, /speckit.clarify can be used to resolve ambiguities that arise during interviews.
• /speckit.plan for creating the technical specification
• /speckit.tasks to break down the technical specifications into tasks
• /speckit.implement to start the implementation

Spec Kit integrates very well with GitHub Copilot; for example, it displays possible answers to questions as buttons in the “Ask Questions” tool.

In Spec Kit, while the specifications are versioned along with the source code, they only ever reflect the delta from the previous system state, so no complete specification of the system is created. Spec Kit therefore follows only the “Spec-First” approach.

Most recently, there was also Discussionsabout whether the tool will continue to be developed sufficiently following the departure of one of its lead developers from Microsoft to Anthropic.

OpenSpec

One alternative is the OpenSpec tool. It, too, can be used with various coding agents and, similar to Spec Kit, is initialized via a CLI, which in this case is installed as an NPM package.

System-wide instructions are stored in OpenSpec's config.yaml. This file already provides a predefined format for delineating the basic system context of rules for the individual documentation artifacts.

OpenSpec offers different workflows (Quick Path and Expanded), which differ mainly in whether the specification documents are all created together in a single step or in separate steps. The latter has the advantage that, for example, the technical specification can be reviewed before the work packages are generated from it.

OpenSpec also supports the definition of custom schemas, which allow for complete customization of the workflow and the specification artifacts used.

The most important OpenSpec commands are:

• /ospx:explore as an optional step to refine the specifications through an interview.
• /ospx:propose as part of the “Quick Path,” which generates all specification documents in a single step. Alternatively, use /ospx:new to create the change and then /ospx:continue for each artifact.
• /ospx:apply starts the conversion
• OpenSpec separates changes (= proposed modifications) from specs (= how the system currently works). /ospx:archive integrates the change specification into the system specification and closes the change.

Comparing changes and specifications results in long-lasting system documentation. OpenSpec is therefore “spec-anchored.”

More SDD tools

In addition to the solutions mentioned, there are various other providers, such as Kiro, Tessl, and BMAD. However, a comprehensive evaluation of each emerging tool is challenging, as it requires comparable, non-trivial use cases and experience spanning multiple iteration cycles.

Instead, it is advisable to classify the available frameworks based on the defined categories and compare their workflows and customizability. A focused approach—that is, selecting and mastering a few suitable tools in depth—is more effective than continuously evaluating all new market entrants.

It is crucial to select a flexible framework that aligns well with your specific requirements, as well as to optimize and adapt it specifically to company- and project-specific processes. This includes, for example, integration with existing systems such as ticketing systems, version control, and knowledge databases; adapting specification artifacts to your own standards; and defining appropriate instructions and guidelines that enable agents to independently validate changes and verify them through automated tests.

A key question is how much specification is actually necessary—since the various SDD tools differ, in some cases significantly, in this regard.

The following chart compares the “Lines of Spec” (i.e., the number of lines in the Markdown specifications) with the “Lines of Code” required to implement a feature. If the specification for a complex feature is too brief, the likelihood that the results will not meet expectations increases. If, on the other hand, it is too detailed, reviews become inefficient simply due to the sheer volume of content that needs to be read and validated.

Regardless of specific methods and tools, it is clear that AI-powered software development and spec-driven development do not replace developers, but rather shift their focus and significantly expand their scope of work, thereby fundamentally redefining the role of the developer:

• The focus is increasingly shifting away from simply writing code and toward structuring problems.
• Planning and systematic specifications are becoming a key focus in order to effectively manage and parallelize the work of coding agents.
• Architectural decisions and precise orchestration of AI are becoming increasingly important, as models often tend to favor “traditional” approaches—simply because these dominate the majority of the training data, even though more modern alternatives are now available.
• At the same time, the focus is increasingly shifting toward review and quality assurance, as growing support from automated or AI-assisted implementation means that the careful review of specifications and generated code, the early detection of inconsistencies, and ensuring that business and technical requirements are met are becoming increasingly central to development work.
  

Until now, many of these tasks have fallen primarily to experienced developers. In the future, junior developers will also need to develop these skills much earlier, while experienced developers will increasingly take on the roles of mentors and quality assurance specialists for the entire system architecture.

At the same time, experimentation becomes much easier. Whereas in the past, lengthy discussions were held to find the optimal solution before proceeding with time-consuming implementation, today different approaches can be tested quickly and easily, shifting the debate from theory to practice.

As much potential as this new way of working offers, it inevitably comes with a number of new challenges that involve both technical and organizational aspects, for which there are so far only partially tested solutions.

• How can the ever-growing volume of specifications and generated code be validated efficiently and reliably?
• If developers themselves write little or no code, how can they maintain their programming skills at a level that allows them to effectively control and evaluate the work of AI agents?
• How and by whom will programming languages and frameworks continue to be developed in the future if their primary users are increasingly AI systems?
• How should the training of the next generation of software developers be structured, and which skills should be the focus in the future?

These are all issues we are actively addressing—and our industry shares a collective responsibility for finding answers to them.