Spec-driven development for product teams
Spec-driven development is a methodology where structured, versioned specifications are the primary artifact, and code is generated or maintained against those specs by humans and AI coding agents. It has been adopted across every major AI coding tool: GitHub Spec Kit, Cursor, Claude Code, BMAD, AWS Kiro, Tessl. For product teams, the more interesting question is the one the engineering side isn't asking: where does the spec actually come from?
The engineering side has won the spec
The spec-driven movement has converged on a clear claim: narrative PRDs fail because AI coding agents fill gaps in the wrong places. What works instead is a structured artifact with outcomes, constraints, prior decisions, task breakdown, and verification criteria. Code becomes derivative of the spec. The spec is the source of truth.
That argument is correct, and it's how Revelica thinks about the Delivery phase of The Revelica Method. The product agent exports validated specifications your coding agent can execute directly.
The upstream problem nobody is solving
Every spec-driven development framework treats the spec as the starting point. But specs do not write themselves. Someone decided what to spec, for whom, and on what evidence. That upstream step is still narrative, still biased, still untested in most teams.
The failure mode is not exotic. A team writes a clean spec for a feature that nobody actually wants, or doesn't want in the form specified. The spec discipline is real. The user model behind it was projection. The coding agent ships exactly what was asked for. The customer never adopts it.
Product managers and LLMs share the same projection bias. Both default to assuming customers think like them. A spec inherits whatever bias was in the user model that produced it. Better spec discipline doesn't fix that. Better customer-model discipline does.
What a Revelica spec looks like
Specs come in two shapes depending on the work. Most product work scopes to a specific idea, where the spec is best expressed as a user story map. Some work is cross-cutting and lives outside any one idea, where a markdown document is the better fit. Both are evidence-cited and both export to formats your AI coding agent can consume directly.
Idea-scoped: the user story map
Most of the time the spec is a story map. Actors, moments in time, user stories with acceptance criteria, and the risky assumptions each story carries. The story map exports as structured JSON the coding agent can read directly. The customer context travels with the spec.
See AI user story maps for the shape and the template library for the playbook that generates them.
Cross-cutting: the markdown spec
When the work doesn't belong to one idea (a platform migration, a cross-feature refactor, a new system), the spec is a markdown document with a fixed section skeleton. Revelica uses its own convention internally, and the same convention is the one we recommend to teams that want a starting point.
Section skeleton
- Why: one-paragraph problem framing
- Goals: observable, "when this is done X will be true"
- Non-goals: specific, each rules out a real possible expansion
- Constraints: things given from outside that you don't get to change
- Current state: what exists today, with file references where useful
- Design: subsections, prose, code blocks
- Plan: numbered, each item has an acceptance criterion
- Open questions: each tagged with what they block
- Decisions log: every entry has a Why: line
- Alternatives considered: each with verdict and reason
The convention has a few hard rules. Every decision needs a Why: line. Non-goals must be specific. Plan items each have an acceptance criterion. Open questions each have a Blocking: tag. The point of the rules is to make the spec self-contained: a fresh reader, human or agent, can pick it up and act without needing the original conversation.
Product teams own the spec
Engineering teams have built tremendous tooling for the spec to code step. The spec to customer step has been left to PRDs. That asymmetry is what causes shipped-but-unused features in the AI era. The fix isn't more engineering discipline. It's product teams owning the spec, backed by a customer model the spec inherits from, with the same epistemic discipline applied to both.
FAQ
- Does spec-driven development replace product management?
- No. It changes the unit of work product managers produce. Less narrative PRD, more structured specification with cited evidence and surfaced assumptions. The product judgment behind the spec, whose problem to solve, what evidence is enough, which assumptions are worth testing, is more important under SDD, not less.
- Is the Revelica product agent a spec-driven development tool?
- Yes, on the product side. The product agent produces structured, evidence-cited specifications (user story maps with assumptions, or markdown specs for cross-cutting work) that coding agents like Cursor, Claude Code, and Codex can execute directly. The output is declarative: what needs to be true for the feature to succeed, not imperative implementation instructions.
Run spec-driven discovery, end to end
Try the Revelica product agent free at app.revelica.com. See how cited customer evidence feeds story maps and markdown specs that feed your coding agent.