Spec-driven development with AI agents
When to use SDD and when to skip it.
When a task gets non-trivial, I switch to spec-driven development (SDD). It keeps AI-assisted engineering high-signal, reduces rework, and makes reviews faster.
For small tasks, I just use plan mode and keep moving. SDD is for when the work is substantial enough that you'd regret not having a shared map.
The workflow
I wire up four markdown templates as custom commands:
/sdd-spec <description> # what are we building and why?
/sdd-plan <slug> # how are we going to build it?
/sdd-tasks <slug> # concrete steps
/sdd-verify <slug> # how do we prove it works?
The templates are simple: spec.md captures goal, non-goals, constraints, and acceptance checks. plan.md documents the approach, file-level changes, and risks. tasks.md breaks work into small diffs. verify.md lists what to run before shipping.
The point isn't the exact template. It's that the agent and I always have the same shared map.
Why it works
SDD forces explicit interfaces, edge cases, and tests before code diverges. It limits the blast radius—the agent can be "biased for action" safely because the spec constrains what "action" means.
Martin Fowler's analysis of tools like Kiro, Spec Kit, and Tessl shows the trade-off: SDD adds upfront work, but reduces total time-to-production by cutting rework and misunderstandings. It's overkill for bug fixes, but pays off for substantial features.
I also maintain AGENTS.md at the repo root so agents can find commands, architecture, and conventions quickly. (More on this in AI coding agents are general-purpose harnesses.)
Specs in PRs
I include the spec doc in the PR and use the review as an alignment checkpoint. It keeps devs aligned on the goal, and reviews go faster because everyone is reacting to the same intent.
Whether you commit all the SDD docs or just spec.md depends on the team. The important part is that the intent is easy to find during review.
When to skip SDD
If the task is small—a one-liner fix, a config change—skip the ceremony. Use plan mode, ship it, move on.
SDD is for the work that matters enough to get wrong.