Spec-Driven Development: How to delegate implementation to AI without losing control
- Krzysztof Niemiec
- Jul 1
- 6 min read
AI is entering the codebase without clear rules
AI has become part of the daily work of technology teams faster than many organizations have been able to establish a sensible process for using it.
A model can generate classes, tests, or parts of a feature within minutes. However, speed alone does not guarantee that the result will support the business objective, respect the existing architecture, or remain within the boundaries of the system.
The problem: Vibe Coding
In practice, AI-assisted development often follows a simple pattern:
A loosely defined prompt
Generated code
Manual adjustments to match the requirements and architecture
This approach is commonly described as “vibe coding.” It may work for small experiments, but it becomes risky when applied to larger features or production systems.
The SDD approach
Spec-Driven Development, or SDD, reverses this order.
First, we:
document the requirements,
agree on the implementation plan,
define technical boundaries,
break the work down into clear tasks.
Only then do we move on to implementation.
In Spec-Driven Development, AI is the executor, not the decision-maker.
Between chaos and full SDD: the role of AI rules
Not every change immediately requires a complete process. There is often an intermediate stage that could informally be called “vibe coding 2.0”: AI still works from prompts, but within explicitly defined rules, patterns, and constraints.
Rules and Skills
This is where rules become the foundation. Rules are the standing guardrails that tell the model how to work in this particular codebase, regardless of the specific task: prefer the smallest possible diff, do not introduce new dependencies without justification, respect existing services and architectural boundaries, keep controllers thin, and align with the project’s existing tests and coding style.
In practice, these rules live next to the code - for example, as project rule files for the AI tooling and a short “constitution” describing non-negotiable engineering principles. They are what turns a general-purpose model into a contributor that behaves like the rest of the team.
A closely related mechanism is skills: documented, repeatable instructions for completing a specific type of task, such as creating tests or migrations in accordance with the project’s conventions.
The distinction matters. Rules constrain how the model works at all times; skills describe how to perform a recurring task; the specification defines what to build and why. Rules and skills reduce the model’s discretion and keep its output consistent, but they do not replace the specification, which remains the shared point of reference for the business, product team, technical team, and AI.
Guardrails and Direction
Rules keep AI inside the guardrails, while the specification points it at the right destination.
For larger or riskier changes, neither is sufficient on its own. A model with a strong specification but no rules may still drift from the codebase’s conventions, while a model with strict rules but no specification may faithfully build the wrong thing.
What is Spec-Driven Development?
In SDD, a change does not begin with code. It begins with three artifacts: a specification, a technical plan, and a task list. Implementation starts only after these have been prepared.
Specification → Technical Plan → Task List → Implementation
The four stages
The specification describes what needs to change and why.
The technical plan translates the requirement into an implementation approach for a specific system.
The task list breaks the work down into small, reviewable steps.
The implementation carries out the previously agreed tasks.
A specification is not merely an elaborate prompt for an AI model. It is a communication contract between the business, product team, technical team, and AI, ensuring that everyone works from the same description of the change.
Example: adding a Deputy Director role to an existing Symfony-based e-Learning application
A useful example of this model is a change to an existing Symfony-based e-learning application: adding a Deputy Director role with a narrower set of permissions than the Director role.
Specification
The problem is that the director’s responsibilities cannot currently be delegated safely because the existing permission model grants overly broad access.
The business objective is to allow a deputy to perform selected duties without receiving full permissions. This provides the organization with greater operational continuity and a clearer division of responsibilities.
Scope: Add a new role and provide access to selected actions or views within a limited scope.
Out of scope: No redesign of the entire permission model, no changes to other roles, and no redesign of the security module.
Acceptance criteria: The deputy can view reports and manage the schedule but cannot edit users or change their roles. Acceptance criteria should be specific and verifiable.
Open questions: Which areas should be available in read-only mode, and which should remain entirely inaccessible to the new role?
Technical Plan
The technical plan translates the specification into concrete decisions:
add the new role,
update role_hierarchy,
review usages of #[IsGranted(...)],
use Voters where permissions depend on context,
prepare tests that account for the risk of privilege escalation.
Task List
The task list can be short and specific:
Add the role and update the hierarchy.
Review usages of the Director role.
Allow read access and block unauthorized write operations.
Add tests and run static analysis.
Implementation
AI modifies specific files only after the specification and technical plan have been approved.
Guided by the project’s rules, it is expected to stay within the agreed scope rather than expand it or resolve open business decisions on its own—and the review step exists precisely to enforce that.
Version-Controlled Specifications: the history of code and decisions
One of the greatest advantages of SDD is that the specification, technical plan, and task list can be stored alongside the code in the repository as spec.md, plan.md, and tasks.md.
As a result, they follow the same version control, review, and change history processes as the implementation.
The repository history should show not only how the code changed, but also why the requirements changed.
When a code change is linked to an update in spec.md, plan.md, or tasks.md, it becomes easier to reconstruct the business decision, understand changes in scope, and conduct a meaningful audit.
This does not necessarily mean that everything must be included in a single commit. However, the related changes should be connected through the same pull request, task number, or clear references between changes.
Simply adding Markdown files to the repository is not enough. Clear commit messages and pull request descriptions are also required.
Suppose the first version of the specification gives the Deputy Director access only to reports. Later, the scope is expanded to include schedule management, while user editing remains prohibited.
The change should follow this order:
This change should first be added to spec.md, then reflected in plan.md and tasks.md, and only then implemented in the code.
What SDD provides to the Business and the Team
From a business perspective, SDD helps align the scope of a change before implementation begins.
A specification makes it easier to identify ambiguities early, reduce the cost of rework, preserve the history of decisions, and improve communication between the business, product team, and technical team.
The specification is not a document that is handed over to the development team and then set aside. It is an artifact that evolves together with the change.
From a technical perspective, SDD provides:
better control over scope,
greater architectural consistency,
smaller diffs that are easier to review,
more precise delegation of tasks to AI.
Instead of assigning entire, poorly defined problems, teams can delegate clearly scoped implementation tasks.
Limitations and costs of SDD
SDD also comes with a cost. Preparing and maintaining specifications takes time, and an incorrect specification may simply accelerate an incorrect implementation.
For small changes, the full process may be unnecessary. A specification can also create a false sense of confidence if it has not been validated with the business, users, or the actual behavior of the system.
Regardless of the process, tests, reviews, and human accountability are still required.
AI implements, Humans remain accountable
AI can accelerate implementation, but humans remain responsible for the objective, scope, and consequences of a change.
SDD does not delegate accountability. It only enables execution to be delegated more effectively.
SDD does not slow down working with AI. It shifts the cost of thinking to before implementation, where it is cheapest, and leaves behind a trail of decisions, not just a trail of code.
