After spending an evening trying Structured Prompt-Driven Development (SPDD), I came away thinking it is a genuinely useful addition to the AI-assisted development toolbox—but not a replacement for every kind of work.
SPDD, as described by Thoughtworks and implemented in the open-source open-spdd project, treats prompts as first-class engineering artifacts. Rather than relying on a series of chats that disappear into history, you create a structured prompt, keep it under version control, use it to generate code, and update it when the code or requirements change.
In principle, that sounds obvious. If prompts influence implementation, why should they be less durable than the code they produce?
In practice, I found it more useful than I expected.
What worked well
The biggest benefit was task analysis.
SPDD pushed me to think through missing parts, unclear assumptions, and potential inconsistencies before I asked the model to write code. This was valuable because the hard part was not generating implementation. The hard part was deciding what exactly should be implemented.
The REASONS canvas is the core structure behind the approach:
- Requirements
- Entities
- Approach
- Structure
- Operations
- Norms
- Safeguards
It makes the AI work from intent, domain concepts, architecture, concrete tasks, shared engineering standards, and boundaries. That is a much better starting point than “please add feature X.”
I do not completely love the name, and I would personally prefer a shorter structure with fewer overlapping sections. “Approach” and “Structure,” for example, can feel close together depending on the task. Still, the primary audience is not a human reader—it is the AI. If the structure gives the model clearer boundaries, repetition is not necessarily a problem.
Another pleasant surprise: SPDD generated notably fewer files than a typical Spec-Driven Development workflow. That made the process feel lighter. I did not end up with a sprawling pile of design documents, plans, tasks, and checklists before doing useful work.
The generated prompt was also exhaustive and self-contained enough that I could hand the coding phase to a cheaper model. That is a practical advantage. Use a stronger model where reasoning and clarification matter most; then use a more economical one to implement a well-scoped specification.
And, in my small experiment at least, the implementation was correct on the first attempt. That does not mean SPDD magically guarantees correct software. It does suggest that spending more effort on a clear, structured prompt can dramatically reduce the usual back-and-forth.
The final part that impressed me was synchronization (spdd-sync). When I made code-side changes, syncing those changes back into the prompt worked surprisingly well. This matters because prompt/code drift is the obvious failure mode of this whole idea.
A specification that no longer reflects the system is worse than no specification at all—it creates false confidence.
What did not change
SPDD does not remove the core truth of AI-assisted development: Writing the code took much less time than thinking everything through.
That was true with SDD, and it remained true here.
The model can produce code quickly. It cannot remove the need to make product decisions, understand the existing system, define boundaries, or decide what “done” actually means. In fact, SPDD makes this more visible because it asks you to articulate those decisions upfront.
That is a feature, not a flaw. But it is worth being honest about. If someone tells you AI makes software development instant, they are probably measuring typing speed rather than delivery.
SPDD vs. SDD: when would I use each?
Right now, my rule of thumb looks like this:
- A simple code change: use the agent directly, with its planning mode.
- A relatively small new feature with uncertainty: use SPDD.
- A larger feature with several phases of work: use SDD for design and planning, then use a plain coding agent for each well-defined piece.
SPDD feels especially useful when the work is contained but underspecified. It gives enough structure to expose ambiguity and guide implementation without turning every feature into a documentation project.
For large, multi-stage initiatives, a fuller SDD process still makes sense. There, the problem is not only implementing individual tasks correctly; it is coordinating phases, dependencies, interfaces, migration paths, and delivery milestones.
Should prompts live in the repository?
This is the question I am still undecided about.
My instinct is that prompts should stay in the repository only when they retain value after the immediate task is complete. That includes prompts that capture:
- important domain rules;
- non-obvious architectural decisions;
- reusable generation patterns;
- compliance, security, or performance constraints;
- reasoning that would otherwise be rediscovered during the next major change.
Those are useful engineering assets.
But I would not preserve every temporary prompt just because it exists. A one-off prompt for a small refactor can become documentation clutter quickly. Keeping every artifact creates another maintenance burden, and stale prompt files are especially dangerous because they look authoritative.
So my current preference is selective retention: keep prompts that explain enduring intent, archive or remove prompts that only served as temporary scaffolding.
The real test is simple: would a developer—or an AI agent—benefit from this prompt six months from now when changing the same area of the system? If yes, keep it. If not, let it go.
My takeaway
SPDD is not revolutionary because it invents a new way to write code. It is useful because it applies familiar engineering discipline—clarity, reviewability, version control, and feedback loops—to prompts.
That may be exactly what AI-assisted development needs right now.
The code is increasingly cheap to generate. Clear intent is not.
Comments
Post a Comment