Spec-Driven Development (SDD) & BDD in the Agentic Era
Shifting bottlenecks to specification, decision-complete documents, translating decisions into Gherkin BDD contracts, and instruction lifecycle hierarchies.
Speed moves the bottleneck downstream
The first four days built the parts of an agent product: a bounded user outcome, interoperable tools, reusable skills, security controls, and evaluation evidence. Day 5 integrates them into a production decision.
Agentic development can generate implementation faster than a team can review, test, and integrate it. That speed creates an illusion of progress when intent is still vague. A thousand lines of plausible code are not valuable if they create a larger verification queue or move the product away from the user's job.
The bottleneck shifts from code production to product clarity and system verification. PMs and engineers spend more time defining behavior, reviewing evidence, managing boundaries, and deciding what is safe to release. The agent handles more implementation detail, but humans remain accountable for the blueprint and the release.
Spec-Driven Development (SDD) is the operating model for that shift: treat reviewed intent and behavior as the durable source of truth, while implementation code remains replaceable when it no longer matches the blueprint.
This is why "vibe coding" cannot mean "vibe in production." Experimentation can start with a rough intent. Production work needs a source of truth that another person, an agent, and an evaluation system can all inspect.
Use one running example throughout Day 5: a sales-research agent that reads approved account evidence, drafts a briefing, and proposes a CRM update. In the first pilot it cannot write to CRM or send external email. The user problem is real-research is slow and evidence is fragmented-but the risk is also real: stale account data or a hallucinated recipient can turn a plausible draft into an external incident. We will take this workflow from specification through integration, review, safety controls, evaluation, launch, and rollback.
A reviewable path from spec to release
Every transition adds evidence before the product receives more authority.
Reviewed source of truth
User outcome, boundaries, contracts, policy, owner, and rollback trigger
Observable normal, boundary, ambiguous, and unsafe behavior
Commit-bound delivery
Runtime decision
Thresholds hold
Continue monitoring the approved cohort without expanding authority.
A rollback trigger trips
Disable write tools, revoke credentials, preserve traces, and return to read or draft-only mode.
A failure becomes a new BDD and eval case. Review the spec before starting the next small batch.
The specification is the shared contract
A specification is the architectural north star for the workflow. It explains what to build, why it matters, what states exist, which systems are involved, and how the team will know the result is correct. Store task-specific specifications with the project so they can be reviewed and versioned with the implementation.
SDD keeps the blueprint ahead of generated code
SDD is a loop, not the act of writing a large document. First, the team states the user outcome and boundaries. Second, it resolves product and architecture decisions before generation. Third, it turns critical behavior into examples and acceptance evidence. Fourth, the agent implements one reviewable batch against that versioned spec. Fifth, tests and evals compare the result with the blueprint. When implementation exposes an undecided rule, the team updates and reviews the spec before continuing. Code can be regenerated; an unreviewed product decision cannot.
For the sales-research agent, the initial spec says which account sources are authoritative, what makes a claim evidence-backed, when data is considered stale, which CRM fields may be drafted, and that email and direct CRM writes are out of scope. That prevents the implementation agent from inventing a freshness rule or interpreting “prepare outreach” as “send outreach.”
A good agent product specification contains:
- The user problem, target user, and job to be done.
- Supported and unsupported scenarios.
- Data sources, freshness, and evidence requirements.
- Tool contracts, permissions, and state changes.
- User journey, status, approval, and recovery states.
- Functional, visual, behavioral, and accessibility expectations.
- Evaluation cases, guardrail metrics, and release thresholds.
- Rollout, ownership, incident, and rollback plans.
Use narrative Markdown for intent and tradeoffs. Use structured tables or YAML for schemas, permissions, and configuration when nesting matters. The format is secondary to clarity. A long document that repeats itself and buries the acceptance criteria can create the same context problems as a giant system prompt.