Spec-Driven Development
Spec-Driven Development (SDD) is a structured planning mode for complex or multi-part Infrahub builds. Instead of generating files immediately, the AI reasons through requirements with you first: capturing what needs to be built, validating the approach against Infrahub conventions, breaking the work into discrete tasks, and only generating once the plan is approved.
The key benefit: structural mistakes (wrong relationship cardinality, missing allow_upsert, incorrect generic usage) are caught before any file is produced.
When to use SDD vs. direct mode​
| Direct Mode | SDD |
|---|---|
| Adding an attribute to an existing node | Designing a new schema node with relationships |
| Writing a single validation check | Building a generator chain |
| Creating a menu section | Standing up a complete new domain (schema + objects + checks + generators) |
| Populating a batch of objects | Refactoring relationships across multiple schema files |
| Any well-scoped, single-skill task | Anything that involves design decisions or spans multiple skills |
The SDD workflow​
1. Specify​
Describe the feature or requirement in plain language. The AI captures requirements, asks clarifying questions about scope, Infrahub version, existing schema context, and dependencies. The goal is a complete picture of what needs to be built before any planning starts.
When you do not yet know what to model, or the work spans several domains, use the Model Designer to work through the business, the service and the data. Its design brief splits the work into ordered features, gives each one a handoff that names the brief and the feature, and draws the build order as a plan map you can review at a glance. Before you specify, review the brief with the people it affects, such as management, the service owner and the teams it names as owners: it states the value the design serves, how the service will be ordered and delivered, and who owns which data (see Discussing the brief inside your organization). Then use the F1 handoff as the input to this workflow's Specify step, and continue in dependency order.
Starting from a design brief​
With spec-kit, each feature's Handoff cell becomes the input to /speckit.specify. Taking the brief from the L3VPN example, you specify F1 first:
/speckit.specify Design and implement the L3Vpn and VpnSite model, then populate it from the customer export, as designed in F1 of docs/designs/l3vpn-service/design-brief.md.
The handoff names the brief, so the spec draws on its data model sketch, decisions and open items rather than on the one sentence. When F1 is built, specify F2 the same way with its own handoff. Follow the Depends on column for the order: a feature runs only after the features it names. In a spec-kit repository, the brief's Next steps section lists these /speckit.specify steps in order for you. When an open item is answered after a feature is specified, run the Model Designer again with the answer: it adds a step to re-specify that feature (see Coming back with an answer).
/speckit.specify does not offer the Model Designer by itself. Run the Model Designer first when the design is not settled, then paste the handoffs one at a time.
2. Plan​
The AI produces an implementation plan. For each component to be built (schema nodes, generators, checks, transforms), it identifies which skill to use, what the inputs and outputs are, and what dependencies exist between steps. The plan is validated against Infrahub skill rules before it's presented.
3. Review​
You review the plan. This is the key checkpoint: adjust the approach, correct assumptions, or request changes before any file is generated. The AI explains its reasoning for each decision so you can evaluate whether the approach is correct.
4. Implement​
Once approved, the AI executes each task using the correct Infrahub skill. Tasks run sequentially where dependencies exist, or in parallel where they don't. The AI manages the dependency tree.
Working with the plan​
- Interrogate: ask why a specific decision was made, request alternatives, or ask what would change if a requirement changed
- Adjust: describe what's wrong or what you want differently; the AI updates the plan before proceeding
- Approve: explicitly confirm the plan is correct. The AI does not proceed without confirmation
Sequential vs. parallel execution​
Simple builds execute sequentially: schema first, then objects, then checks. Complex builds with independent components can execute in parallel using sub-agents. The AI determines which tasks are independent based on the dependency tree it built during planning.
Compatible SDD frameworks​
SDD works with any framework that supports a spec, plan, task, and implement workflow. The infrahub-template repository scaffolds an Infrahub project and documents the Spec Kit setup it expects, which is the quickest starting point.
Where to go next​
- Set up the Infrahub routing extension for Spec Kit, so the
after_implementhook detects skill-guidance gaps automatically: Spec Kit integration. - See the workflow end to end, from a plain-language request to a loaded schema, object data, and a passing check: Walkthrough: VLAN management.