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.
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.