Spec-Driven Development with Agents

This skill turns you from a code generator into an executor of specifications. The core inversion, from GitHub's Spec Kit methodology: "Specifications don't serve code—code serves specifications." The spec — not the code — is what gets versioned, reviewed, and reasoned about; code is one possible expression of it in a particular language and framework, and can be regenerated. Google's Day 5 whitepaper from the 5-Day AI Agents Intensive course makes the production case: a rock-solid behavioral specification in Gherkin BDD format makes code disposable — the implementation can be safely regenerated from the spec when requirements or the stack change.

When to use

Use this procedure when:

• The output must survive past a demo: production features, enterprise code, anything with compliance or security requirements.
• Multiple sessions, agents, or humans will touch the same codebase — the spec is the shared contract you onboard them with, instead of explaining decisions from memory.
• Migrating or modernizing legacy code: write the spec once and regenerate on the new stack, instead of line-by-line translation.
• Requirements will change: with SDD you update the spec first, then regenerate — not patch code and let intent drift.

Do NOT use it when:

• Building a throwaway prototype or exploring UX directions — vibe coding's fast accept/reject loop wins there. SDD is slower per feature because you write documents before code; the payoff compounds only when the codebase grows, features interact, or you revisit code weeks later and need the rationale.
• The feature is small and the spec is already unambiguous — skip the optional /speckit.clarify and /speckit.analyze phases (see Rule 6) rather than skipping SDD entirely.

Rules

1. Treat the spec as the asset and code as disposable. Version, review, and evolve spec.md; regenerate code from it. Maintaining software means evolving specifications. If the code and the spec disagree, that is a review finding, not an accepted fact.
2. Keep the spec at WHAT/WHY altitude — never HOW. The spec holds functional requirements and user-observable behavior; no tech stack, no SQL tables, no API internals. Implementation detail lives in plan.md. This separation prevents premature technical decisions from contaminating requirements.
3. Write behavioral requirements in Gherkin BDD format. The whitepaper recommends Gherkin because its structured natural language keeps LLMs focused on state, action, outcome — precise enough that the entire codebase can be regenerated or translated from it.
4. Never guess on ambiguity — mark it. Use explicit [NEEDS CLARIFICATION] markers in the spec for anything the request doesn't specify, then resolve them (with /speckit.clarify or the user) before planning. An unmarked assumption becomes silently generated wrong code.
5. Run the Spec Kit loop in order. With the specify CLI (uv tool install specify-cli --from git+https://github.com/github/spec-kit.git, then specify init <project>; works with 30+ AI coding agents):
   • /speckit.constitution → constitution.md (governing principles)
   • /speckit.specify → spec.md (requirements, user stories)
   • /speckit.plan → plan.md plus data-model.md, research.md (stack, architecture, rationale)
   • /speckit.tasks → tasks.md (ordered, actionable steps)
   • /speckit.implement → code, executed task-by-task with checkoff Optional: /speckit.clarify (recommended before /speckit.plan for complex features), /speckit.analyze (cross-artifact consistency — most useful when the task list is long or the feature touches multiple subsystems), /speckit.checklist (final validation), /speckit.converge (assess an existing codebase against spec), /speckit.taskstoissues (tasks → GitHub issues).
6. Establish a constitution and gate against it. Non-negotiable project principles live at .specify/memory/constitution.md. Spec Kit's own reference articles: Library-First (Article I), CLI Interface Mandate (II), Test-First Imperative — non-negotiable (III), Simplicity with max 3 projects initially (VII), Anti-Abstraction — use frameworks directly (VIII), Integration-First Testing with real databases and contract tests (IX). Planning runs a Constitution Check with Simplicity, Anti-Abstraction, and Integration-First gates; /speckit.analyze flags violations as CRITICAL.
7. Emit tasks in strict checklist format. IDs, parallelizable markers, and file paths, e.g. - [ ] [T001] [P] Create reservations table schema in scripts/seed_db.py. Mark independent work [P]. Enforce ordering: contracts first, then tests (contract → integration → e2e → unit), then implementation.
8. Version-control every artifact. Artifacts live in specs/<feature-branch>/ in git — not buried in chat history. If a conversation is interrupted, everything decided so far is already on disk; resume from the files.
9. On requirement change, update the spec first, then regenerate. Debugging means fixing the spec and plan that generated the wrong code. Production feedback flows back into the spec for the next regeneration cycle.
10. Scale review by risk, not line-by-line reading. The whitepaper's production pipeline pairs SDD with automated code-review agents. Focus human review on behavioral tests, system contracts, and high-risk changes rather than every generated line — humans forced to read everything an agent generates stop catching anything.
11. Gate tool execution with policy, not trust. In the whitepaper's zero-trust pipeline, a hybrid Policy Server evaluates agent tool-calling actions before execution and blocks unsafe or non-compliant ones. In enterprise settings, agent actions are checked, never assumed safe.
12. Have the agent keep artifacts synchronized. When code changes, update the specs, regenerate tests, and update changelogs in the same pass; require human review and approval of spec/plan/tasks artifacts before implementation proceeds. Generated artifacts vary between runs — review, then accept, modify, or regenerate.
13. Optimize for business outcome, not generation volume. The whitepaper's core warning: the same speed that vibe-codes a prototype in minutes produces fragile code at production scale. Measuring success by how much code the agent generates just moves the cost into review and maintenance; measure verified behavior instead.

Checklist

• Decide: will this outlive a prototype? If no — vibe iterate. If yes — proceed.
• specify init (or confirm .specify/ exists) before any feature work.
• Constitution written at .specify/memory/constitution.md with the project's non-negotiables.
• /speckit.specify: spec.md states WHAT and WHY only; zero implementation details.
• Behavioral requirements expressed as Gherkin state/action/outcome scenarios.
• Every unknown marked [NEEDS CLARIFICATION]; all markers resolved before /speckit.plan.
• /speckit.plan: plan.md + data-model.md + research.md record stack choices with rationale.
• Constitution Check passed (Simplicity, Anti-Abstraction, Integration-First gates).
• /speckit.tasks: tasks.md uses [T00N] IDs, [P] parallel markers, explicit file paths.
• Test order enforced: contracts → contract tests → integration → e2e → unit → implementation.
• Long/multi-subsystem task list? Run /speckit.analyze before implementing.
• Human approved spec, plan, and tasks before /speckit.implement.
• All artifacts committed under specs/<feature-branch>/.
• Any requirement change went spec-first, then regeneration — never code-only patches.

Anti-patterns

• Vibe coding into production. Accepting generated code "because it looks right" is fine for demos; the same speed that builds a prototype in minutes makes it fragile in production, because there is no source of truth to regenerate from.
• Spec drift. Editing generated code without updating the spec. The spec silently stops being the source of truth and the next regeneration destroys your fixes.
• HOW in the spec. Naming databases, frameworks, or schemas inside spec.md — it locks in premature technical decisions and blocks regeneration on a different stack.
• Guessed defaults. Filling unspecified behavior from assumption instead of [NEEDS CLARIFICATION] markers.
• One-shot generation. Jumping from a one-sentence prompt to implementation without spec → plan → tasks; SDD is multi-step refinement, not single-shot codegen.
• Reviewing everything, line by line. Unsustainable once agents scale output, and it degrades into rubber-stamping; tier the review by risk and audit tests/contracts instead.
• Measuring generation volume. Counting generated lines or tokens as progress rather than verified, business-relevant behavior.
• Trusting agent tool calls. Letting tool execution proceed unchecked in enterprise settings instead of gating it behind policy (the whitepaper's hybrid Policy Server pattern); unsafe actions must be blocked before execution, not caught after.

Source

• Spec-Driven Production Grade Development in the Age of Vibe Coding (whitepaper, Google × Kaggle 5-Day AI Agents Intensive, Day 5) — https://www.kaggle.com/whitepaper-spec-driven-production-grade-development-in-the-age-of-vibe-coding — 2026-06
• DAY 5 Livestream — 5-Days of AI Agents: Intensive Vibe Coding Course With Google (official Kaggle channel; hosts' walkthrough of the whitepaper) — https://www.youtube.com/watch?v=Y3HfV4IroCU — 2026-06
• Spec-Driven ADK Agent Development with Antigravity and Spec-kit (official Google Codelab companion) — https://codelabs.developers.google.com/sdd-adk-antigravity — 2026
• Spec Kit — Spec-Driven Development toolkit (README + spec-driven.md methodology) — https://github.com/github/spec-kit — 2026-08

Distilled from the official document(s) above on 2026-08-12. If this skill and the source disagree, trust the source.