SDD in practice: the spec template I use with AI agents

I've been writing about Spec-Driven Development (SDD) as a way of working with AI agents without losing control over what gets built. In this article I share something concrete: the spec template I use, section by section, with the reasoning behind each part. It's the same structure I apply to every change on this site, which I develop entirely with SDD: every change has a spec, a plan, and a verified close in production.

When working with AI agents on development tasks, the problem that quickly appears is this: without a clear structure, the agent interprets, assumes, and sometimes builds something that wasn't requested. For me, the spec isn't bureaucracy: it's the contract that gives the agent a bounded and verifiable workspace.

Why a template and not a free-form conversation

When you ask an agent something in natural language without structure, the agent fills the gaps with its own interpretation. That works for trivial tasks, but it breaks down as soon as the change touches business logic, integrations, or something that already exists in production.

A spec template helps solve this because:

• It forces you to make the context explicit before asking for code.
• It turns "I want it to work well" into verifiable criteria.
• It gives the agent (and whoever reviews afterward) a document to compare the final result against.

The spec doesn't need to be extensive. It needs to be complete in the essentials.

The template, section by section

This is the structure I use. I copy it exactly as is when starting any change, and I fill in each section before letting the agent write a single line of code.

# Spec: [short name of the change]

## Summary
[One or two sentences: what will be built and why]

## Context
[What exists today, what problem this change solves,
what technical or business constraints apply]

## Functional requirements
- [Requirement 1]
- [Requirement 2]
- [Requirement 3]

## Acceptance criteria
- [ ] [Verifiable condition 1]
- [ ] [Verifiable condition 2]
- [ ] [Verifiable condition 3]

## Out of scope
[What this change does NOT include, to avoid scope creep from the agent]

Summary

This is the sentence that forces you to know what you're asking for before asking anyone else, human or agent. If you can't summarize the change in one or two sentences, you haven't understood it well enough to specify it yet.

Context

This section is the one that prevents the most interpretation errors. An agent has no memory of why the current code exists, or of the decisions that were made before. The context gives it that background: what exists today, what technical constraint can't be broken, what business decision has already been made and isn't up for discussion in this change.

Functional requirements

Here I describe the expected behavior, not the implementation. It's the difference between "the user can filter results by date" and "use a date-picker from such-and-such library." Functional requirements leave the agent room to propose an implementation, but they fix what absolutely has to happen.

Acceptance criteria

This is the section that turns the spec into something verifiable. Each criterion has to be markable as met or not met, without ambiguity. This is what's later used to close the cycle: if a criterion can't be marked as met, the change isn't finished, no matter how much code was written.

Out of scope

This is the section that prevents the agent (or yourself) from starting to "improve" things that weren't requested. With AI agents this is especially important: they tend to expand the scope if they're not explicitly held back.

The gates: no spec, no cycle; no cycle, no code

This is the rule that holds the whole process together, and I apply it without exceptions: no spec, no cycle; no cycle, no code.

In practice this means:

1. No work cycle starts without an approved spec. Not by the agent, nor by me. If the spec isn't complete, there's nothing to execute yet.
2. No code is written without a defined cycle. The cycle is the execution plan derived from the spec: what will be touched, in what order, and how it will be verified.
3. The close is verified against the acceptance criteria, not against the feeling that "it turned out fine." On this site, every change has a spec, a plan, and a close verified in production: closing doesn't mean "I shipped it," it means "I shipped it and confirmed it meets what the spec said."

These gates aren't there to slow down the work. They're there to avoid the worst-case scenario with agents: code that works but doesn't solve what was requested, or that solves something different and nobody notices until production.

Flow lite vs. flow full: not every spec needs the same weight

A common mistake when adopting SDD is applying the same level of formality to every change. That generates unnecessary friction on small tasks and ends up pushing people to skip the process altogether. That's why I work with two modes:

Flow lite

For small, bounded, low-risk changes: a copy adjustment, a style fix, a specific fix with no impact on business logic.

• Summary + acceptance criteria. Nothing more.
• The context is resolved in one line if needed.
• The cycle is almost immediate: short spec, execution, verification.

Flow full

For changes that touch business logic, integrations, or anything that, if it goes wrong, generates considerable rework.

• All the sections of the template, fully completed.
• The context is detailed with the real constraints.
• The execution plan (the "cycle") is documented before touching code.
• The close is explicitly verified against each criterion.

The decision of which flow to use doesn't depend on the size of the code to be written, but on the impact of the change. A one-line change that alters a business rule goes through flow full. A large but mechanical, low-risk refactor can go through flow lite.

Logging token consumption per agent

Something I added to my practice that proved useful from the start: logging token consumption per agent and per cycle.

Why does it help me?

• Visibility into real consumption. A change that seems "small" can consume far more tokens than expected if the agent gets stuck in trial-and-error iterations. That data is information, not just a billing figure.
• Comparison between flow lite and full. With per-cycle logging you can see if a change that was treated as lite actually had flow-full-level consumption, a sign that the initial classification was wrong.
• Process traceability. When a close is verified in production, having the token consumption associated with that spec and that cycle gives a complete picture: what was requested, what was executed, what it cost.

You don't need a sophisticated tool for this. It's enough to note, alongside each closed spec, the agent used and the approximate consumption of the cycle. Over time, that log becomes a data source for deciding more wisely when flow full is worth it and when it isn't.

What it looks like in practice

On this site, every change, from a content adjustment to an infrastructure modification, follows the same skeleton: spec, plan (the cycle), execution, and close verified in production. It's not a process I reserve for big projects; it's the same discipline I apply to something as simple as a blog, because a discipline that doesn't hold up on the simple stuff will hardly hold up on the complex stuff.

What I'm taking away from this

• The spec is a working contract with the agent, not bureaucracy: it bounds the space and gives something to verify against.
• Verifiable acceptance criteria and the "out of scope" section are the parts that save me the most headaches.
• Gates without exceptions (no spec, no cycle; no cycle, no code) prevent code that works but solves something else.
• The weight of the process is decided by impact, not by size: flow lite for bounded changes, flow full for anything touching business logic or integrations.
• Logging consumption per agent and cycle helps review whether the classification was accurate.

The template I shared above is the one I use; it can serve as a starting point for other teams to adapt to their context. If you're working on something similar or your team is evaluating how to incorporate AI agents, I'd be interested in exchanging experiences: you can reach me on LinkedIn. And if you want to keep reading about SDD, I invite you to explore my project: https://sdd.estebanburgos.com.ar.