Spec-Driven Development for Agent Workflows

Spec-Driven Development works because it moves the ambiguity forward, into files that can be reviewed, versioned, and reused, instead of leaving that ambiguity trapped inside the latest chat window.

1. Why SDD still matters in 2026

AI coding is faster than it was a year ago. That has not removed the oldest problem in engineering: unclear intent.

The reason I still like SDD is simple. It gives the agent a durable trail:

• what the work is
• what good looks like
• what research matters
• what architecture was chosen
• what tickets are still open

Without that trail, every turn becomes memory theatre.

2. The current flow is smaller and stricter

The version I use now is intentionally compact:

1. initialize the workspace
2. write the project brief
3. render prompts with repo-aware context
4. produce research and architecture artifacts
5. sync tickets into backlog files
6. implement against the open backlog
7. run janitor and status

That flow maps directly to the current sdd toolkit:

• bin/sdd-init
• bin/sdd-prompts
• bin/sdd-backlog sync
• bin/sdd-backlog janitor
• bin/sdd-status

The important part is not the names of the scripts. It is that each phase leaves a file behind that another human or agent can inspect.

3. The agent is not the first step

A lot of teams still open with "build X" and then wonder why the output is strangely plausible and slightly cursed.

The healthier sequence is:

• describe the task in .sdd/project.md
• gather research in .sdd/best_practices.md
• make decisions in .sdd/architect.md
• materialize work items in .sdd/backlog/open/

Only then should the implementation agent start editing the repo.

That order matters because it changes the job of the agent from guessing to executing.

4. Tickets are the bridge between architecture and code

The ticket layer is still the most underrated part of SDD.

When the architecture step emits a machine-readable appendix, the repo can turn that into durable backlog files instead of treating the plan as a paragraph someone promised to remember.

That gives you:

• smaller implementation scope
• explicit done conditions
• cleaner janitor logic
• a better handoff point between people and agents

In other words, the architecture stops being literature and becomes input to operations.

5. Research and architecture should compress decisions

The best SDD artifacts do not try to sound exhaustive. They try to make decisions legible.

I want the research doc to answer:

• what practices are current and relevant
• what trade-offs matter
• what constraints are non-negotiable

I want the architecture doc to answer:

• what path we chose
• why we chose it
• what interfaces or workflows change
• how the work breaks into implementable tickets

Anything beyond that is allowed, but not required.

6. Janitor matters more than people expect

A workflow that opens tickets and never closes them is just a nicer way to grow dust.

The janitor step is useful because it checks concrete repo evidence and moves closed work out of the active backlog. That keeps the state believable, which matters the moment a second engineer or second agent enters the loop.

7. What SDD is good for

I reach for SDD when:

• the task has more than one non-trivial decision
• the repo context matters
• the work may span multiple sessions
• another engineer will need to understand what happened later

I do not reach for it when the task is tiny and the overhead would exceed the value.

That is the whole point. SDD should structure work, not turn every bug fix into a municipal procedure.

Quick start

bash bin/sdd-init /path/to/project --stack "Python/FastAPI" --domain "legal"
python bin/sdd-prompts /path/to/project
python bin/sdd-backlog sync /path/to/project
python bin/sdd-status /path/to/project

Then fill the core .sdd files, implement against backlog/open, and run janitor once the repo evidence agrees.

Further reading

• SDDRush repository