Spec driven development for product managers

wpnews.pro

Hey Product people,

A quick life update: I have officially relocated to Austin, TX. I have spent the last year off the grid, heads-down on a massive enterprise-grade agentic AI rollout. I’ve been deep in the weeds figuring out the exact tools, workflows, and decision frameworks required to make AI agents actually function at scale within a real enterprise.

I have a lot of learnings to share with you all. It’s great to be back in your inbox!

What is spec/specification? #

In an AI-native development model, the Spec is the strict instruction file you give to a coding agent, not a developer/engineer. Because AI cannot read between the lines or tap you on the shoulder for clarification, the Spec must be absolute.

Here is the simplified breakdown of what spec means for product managers:

It sets the boundaries: You must explicitly state what the coding agentshould andshould not touch.
An LLM helps you write it: You collaborate with a “Spec Agent” that challenges your ideas and spots missing edge cases before you build anything.
It locks at Gate 1: Once you approve the Spec, it is locked. The LLM goes to work, and you cannot sneak in new features mid-build.
Instructions must be exact: You cannot use vague terms like “make it intuitive.” Your acceptance criteria must be binary and testable (e.g., “API responds in under 200ms”).
You get a receipt: When the build is done, you receive an “As-Built Record.” This proves the LLM built exactly what your Spec demanded.

Ultimately, the Spec is your only steering wheel. You front-load your effort into perfecting the Spec, and the LLM handles the rest.

What is spec-driven development :

Instead of coding first and writing docs later, in spec-driven development, you start with a spec. This is a contract for how your code should behave and becomes the source of truth your tools and AI agents use to generate, test, and validate code. The result is less guesswork, fewer surprises, and higher-quality code.

Spec-Driven Development is a structured process that emphasizes:

Intent-driven development where specifications define the “what “ before the “how “
Rich specification creation using guardrails and organizational principles
Multi-step refinement rather than one-shot code generation from prompts
Heavy reliance on advanced AI model capabilities for specification interpretation

Spec-Driven Development (SDD) Is:

A governing operating model for all network and infrastructure automation work
A five-phase framework with two formal approval gates
A system that defines what must be produced at each phase and what must be approved before work advances
A discipline that applies to every automation engagement, not just complex or high-risk ones
A way to make automation outcomes trustworthy, documented, and reusable across teams

Spec-Driven Development (SDD) Is Not:

A documentation practice bolted on after delivery
A tool or platform (platforms enforce it, but SDD is the model)
A replacement for automation tooling
An agile or IT service management framework
A methodology applied selectively based on project size or risk level

Why spec-driven development and why now? #

Software development is moving fast, but AI coding tools often get stuck in vibe coding loop. You give an agent a prompt, it gives you code that looks almost right, but is broken somewhere, and you spend hrs fixing it. The problem isn’t that the AI is bad, it’s that it lacks solid planning.

The Problem: Intent vs. Implementation

When you go directly from idea to code using AI, you’re asking it to guess the architectural details, edge cases, and business logic. This leads to:

Context drift: it fixes one bug but breaks three other files it didn’t “see”
Regression: new features dont respect existing design patterns

- **Wasted tokens:** endless back-and-forth prompts to fix small errors

#### **The Solution: Spec-Driven Development (SDD)**

Instead of “code first”, SDD allows you to start with structured, versioned specifications that act as the single source of truth.

In SDD, you dont just describe a feature. You define phases, technical constraints, and exactly what end product looks like. Your agent then uses these specs as its roadmap. It stops guessing and starts executing against a verified plan. This ensures that the code matches your actual intent, not just a random prompt.

Predictability: you know exactly what AI is going to touch before it writes a single line.
Decomposition: It breaks complex changes into tiny, reviewable steps that AI can handle accurately.
Traceability: If a year from now you wonderwhy a specific logic exists, the answer is in the spec, not buried in a massive Git diff.

Core spec-driven development philosophy:

Spec-first : A well thought-out spec is written first, and then used in the AI-assisted development workflow for the task at hand.
Spec-anchored : The spec is kept even after the task is complete, to continue using it for evolution and maintenance of the respective feature.
Spec-as-source : The spec is the main source file over time, and only the spec is edited by the human, the human never touches the code.

GitHub’s Spec Kit Engineering lifecycle

The lifecycle is simple: define intent, remove ambiguity, plan with constraints, implement with AI, and validate against the spec.

Constitution – Define principles, standards, and guardrails.
Specify – Capture requirements, scenarios, and acceptance criteria.
Clarify – Resolve ambiguity, dependencies, and edge cases.
Plan – Translate intent into architecture, flows, and constraints.
Tasks – Break the work into implementation-ready units.
Implement – Use AI to generate and refine code and tests.
Validate – Verify that the output matches the spec.

Key Concepts in SDD

The terms and concepts that define the operating model. Understanding these is the foundation for everything else in the guide series.

Spec: The formal, approved requirements document that locks intent at Gate 1. The spec is the authority everything downstream answers to – not the ticket, not the conversation, not the Slack thread.
Approval Gate: A platform-enforced checkpoint between phases. Gate 1 locks requirements; Gate 2 locks the execution contract. Gates are not reviews, they are stops. No approved gate, no next phase.
Execution Contract: The approved solution design produced at Gate 2. The execution contract is the locked authority the build phase answers to – not the engineer’s interpretation, not a verbal design discussion.
As-Built Record: The reconciled, authoritative record of what was built — what was designed, what was implemented, where deviations occurred, and what the production state is. The starting point for all Day 2 work.
Day 2 Operations: Every automation engagement that follows the initial build — change, extension, debug, audit, handoff. Day 2 is where most automation value is realized, and where the absence of as-built records compounds into permanent operational debt.
TTV (Time-to-Value): The elapsed time from automation request to production-ready, trusted output. SDD compresses TTV by eliminating rework loops caused by unstable requirements, late design discoveries, and undocumented assumptions.
Reuse Dividend: The compounding operational advantage that accumulates when every automation engagement produces a trusted, reconciled as-built record. Reuse dividends make each subsequent engagement faster, cheaper, and more reliable.
Governed Autonomy: The operating model state in which AI agents execute automation within platform-enforced boundaries. The approved spec defines the agent’s authorization scope. Every agentic engagement remains within a governance envelope.
Artifact Chain: The complete, linked sequence of SDD outputs — spec → discovery report → solution design → automation → as-built record – that provides an auditable history of every decision from intent to production state.

Spec responsbilites :

When does SDD works the best #

Spec-driven development is especially useful in three scenarios:

Greenfield (zero-to-one) : When you’re starting a new project, it’s tempting to just start coding. But a small amount of upfront work to create a spec and a plan ensures the AI builds what you actually intend, not just a generic solution based on common patterns.
Feature work in existing systems (N-to-N+1) : This is where spec-driven development is most powerful. Adding features to a complex, existing codebase is hard. By creating a spec for the new feature, you force clarity on how it should interact with the existing system. The plan then encodes the architectural constraints, ensuring the new code feels native to the project instead of a bolted-on addition. This makes ongoing development faster and safer. To make this work, advanced context engineering practices might be needed — we’ll cover those separately.
Legacy modernization : When you need to rebuild a legacy system, the original intent is often lost to time. With the spec-driven development process offered in Spec Kit, you can capture the essential business logic in a modern spec, design a fresh architecture in the plan, and then let the AI rebuild the system from the ground up, without carrying forward inherited technical debt.

The core benefit is separating the stable “what” from the flexible “how,” enabling iterative development without expensive rewrites. This allows you to build multiple versions and experiment quickly.

Tools of SDD : #

GitHub Spec Kit : An open-source CLI toolkit that scaffolds a.spec-kit/ repository directory to guide external coding agents (like Claude Code or Copilot) through an immutable Specify → Plan → Tasks → Implement lifecycle.
OpenSpec : A repo-resident Markdown layer that captures requirement deltas using Given/When/Then scenarios, stacking small, isolated change files into a collective “source-of-truth” document over time.
BMAD-METHOD : A multi-agent orchestrator that simulates a full, 21-persona software product team to force deep conversational loops and automatically generate exhaustive PRDs and threat models before writing code.
AWS Kiro*(formerly Curo)* : An IDE-native copilot backed by AWS that treats requirements engineering as a mandatory hard gate, forcing clarifying questions, building Mermaid diagrams, and establishing property-based testing boundaries.
Traycer : A spec-anchored lifecycle management tool built as a VS Code extension layer that continuously cross-references active runtime tests and types against markdown constraints to eliminate context drift.
Tessl : An open platform and registry where the markdown specificationis the source code, allowing the developer to edit functional requirements while the platform automatically compiles and manages the application.
CodeMySpec : An opinionated, full-stack spec compiler optimized for rapid backend systems that hooks an autonomous QA verification agent directly into your running application to ensure live behaviors match markdown specifications.
Spec Kitty : A community-driven fork of the original Spec Kit CLI that leverages native Git worktrees so multiple AI agents can simultaneously execute distinct tasks across separate specification files without merge conflicts.
Superpowers : A cross-platform framework that injects automated macro skills and conditional logic checks directly into generic agent prompts, layering strict SDD gates over standard interfaces like Cursor.
GSD (Get Shit Done) : A highly optimized markdown convention engineered explicitly for solo developers that condenses instructions, memory banks, and task logs into dense context prompts to maximize agent token efficiency.

Good reads for SDD

Spec-driven development with AI: Get started with Spec Kit – GitHub Blog
Exploring Gen AI – Birgitta Böckeler on martinfowler.com
Spec-driven development: Unpacking one of 2025’s key new AI-assisted engineering practices – Thoughtworks

- **[From chat to specs: a deep dive into AI-assisted development with Kiro](https://kiro.dev/blog/from-chat-to-specs-deep-dive/)** – Kiro
- **[Spec Kit Learnings from a Real-World SDD Experiment (Vidocq)](https://www.manorrock.com/blog/2026/07/29/spec_kit_sdd_in_practice.html)** – Manor Rock
- **[What’s The Deal With GitHub Spec Kit](https://den.dev/blog/github-spec-kit/)** – Den Delimarsky
- **[How to Implement Spec-Driven Development with AI Coding Agents](https://reenbit.com/how-to-implement-spec-driven-development-with-ai-coding-agents-a-step-by-step-framework/)** – Reenbit
- **[Spec-Driven Dev Tools: Spec Kit vs Kiro vs Tessl](https://particula.tech/blog/spec-driven-development-tools-spec-kit-vs-kiro-vs-tessl)** – Particula
- **[Spec-Driven Development (SDD): The Definitive 2026 Guide](https://thebcms.com/blog/spec-driven-development)** – BCMS
- **[Spec-driven development](https://www.thoughtworks.com/radar/techniques/spec-driven-development)** – Thoughtworks Technology Radar
- **[Bonus: Structured-Prompt-Driven Development](https://martinfowler.com/articles/structured-prompt-driven/)** – martinfowler.com

source & further reading

productmindset.substack.com — original article