Strong piece, Gregor! The spike-as-reference-implementation point is the part most teams skip.
One thing worth flagging for readers working in brownfield: step 1 assumes the spike is cheap. In a regulated enterprise environment it's usually the most expensive item in the whole process. The unknown you need to resolve sits behind a system you can't touch in a throwaway way, data access takes weeks, the integration environment is shared, and the behaviour you're trying to prove is encoded in something nobody documented in twenty years.
Which inverts the economics of the workflow. Greenfield: the spec is a writing cost. Brownfield: the spec is a discovery cost, and most of it is documenting what the system already does rather than deciding what the new one should do. Same artefact, entirely different work.
The process still holds, it just stops being the cheap phase.
This is a great point! Right, especially in bigger, enterprise companies, the process and overall bureaucracy to get what you need, can be quite problematic.
Bureaucracy is a real part of it. The sharper problem is that in brownfield the unknown is usually epistemic rather than procedural, nobody currently at the company knows what the system does, so the spike isn't waiting on approval, it's doing archaeology. Approvals you can escalate. That, you can't.
I really enjoyed this, Gregor — especially the point about the reference implementation being worth more than a page of spec.
Curious about the lifecycle after implementation though:
Does Larridin keep the spec/plan artifacts connected to the codebase long-term (e.g., as onboarding material, architecture decision records, context for future AI agents), or are they mostly discarded once the code is merged?
This question about implementation seems to me to be the real difference between SDD and the purely “prompt-and-pray” approach.
Creating a spec to nail down ambiguity sounds like a good plan. My own experience though varied.
Suppose a "spec" contains
1) the expected user behavior/domain
2) based on that, we can create an implementation architecture. How does it integrate into the whole system, new components? New services? New APIs? New classes?
3) based on that, we can create an implementation plan. An ordered sequence of steps of code changes. Not the code changes themselves, but which parts to implement.
Each step could then be iterated on together with the agent. Human or agent discovers edge cases, ambiguous behavior, architecture inconsistencies and so on.
But what I usually observe, is that I burnt many tokens to keep the previous steps consistent with the following. During architecture, or implementation plan, the discovered ambiguity should also be correctly represented in the domain/user behavioral part. And when finally switching to "execute/implement it", new architectural or coding decisions needed to be made.
The devil is always in the details, and specifying all up front has never worked.
Thanks for the article! There is one thing I don't like about specs: saving them after implementation. In my understanding it creates a duplication, now we have 2 source of truth - a spec + our code.
But I believe only code should be our source of truth. A similar situation was with comments: comments could be clear, but they could also mislead, since there is no guarantee that the code does the same thing as the comments describe.
My daily approach is to create an implementation plan, based on requirements in PRD, Jira, and Figma design. Once AI implements the implementation plan - I remove it and leave my code as a source of truth.
I have been tinkering with making this self-evolving. Essentially keep spec around as a lean set of skills per feature area. Example, account handling and backup would have their separate skills and certain invariants encoded that AI is able to pickup when making changes into those subsystems.
Loved the article Gregor, and the visibility it’s bringing on benefits of SDD.
Two questions I had after reading the article was:
1. how do we quantify/assess the quality of spec and implementation plan?
2. You mentioned “Decisions on the fly” as a no-go approach. What would you recommend if teams/AI do stumble during implementation. Would you rather advise them to go back to the drawing board and start with spike/spec generation stage?
Thank you for all the linked examples! Going to take these away and apply them to some of my agentic workflows. I have been doing a variation of creating a spec using the grill me skill and have been looking for examples on how to structure a spec, so this is really helpful!
But one has to know the vision and goal before one creates all this. Or better yet, all that move fast break things approach now occurs before your write a line of code.
The spec is advisory. So is the implementation plan. Nothing in the pipeline actually prevents the LLM from wandering off-spec mid-implementation. When the model drifts, who catches it? The reviewer. And now the reviewer is doing the exact work the spec was supposed to eliminate, line by line, checking whether what got built matches what was specified.
Which means the spec reduced the probability of deviation. Cool. Didn't make deviation structurally impossible. The reviewer is still the only gate.
There's a missing step between "here's the plan" and "here's the PR." A deterministic check. Did the output touch only the files the spec declared? Did it satisfy the test plan's conditions? Did it introduce any architectural decisions that weren't in the spec? Those are all checkable. Automatically. Without a human reading every line.
Make that check structural and the spec stops being a document the model might follow. It becomes a constraint the model cannot violate. The reviewer goes from the only gate to the final gate which is a very different job.
Yes. The trouble is that much of this knowledge (and often the crucial parts) is tacit and/or counterfactual. And that finally means that no amount of documentation volume or rigor will solve the problem.
Some good points here. Spec-Driven development is very helpful indeed. What I am missing though is 1/the importance of context engineering, even in SDD, and 2/implementing testing/evaluation feedback loop.
Great article, thank you! I also use spec driven development more 6 months. Tried multiple frameworks and approaches, but I still have one problem that needs to be solved and I should like to hear your thoughts, how to handle the customer feedback and keep it in sync with spec?
Thanks for the article! I have using spec driven development and making teams to adopt and it is really making a difference.
We have adopted OpenSpec and to improve vanilla OpenSpec workflows, I created an open source project that we use in our projects and see great improvements. Please check it out, the project is in active development and would love to hear feedback and ideas from the community.
I moved to using specs couple of weeks ago and they really improved the way I worked. I was using some scattered version of this all the time, but only after I gave it some structure the benefit became obvious - the work is resumable and trackable, for me and for the agent. Instead of asking “Hey, do you remember what we were doing”, I just say resume. That’s also why I keep the spec after the work is done, there are usually important details about what was done and why which I can use as reference points later. What I added to mine is a drift section - basically tracking the gap when the work departs from what was agreed and why. Planned this, did that, because of this.
Strong piece, Gregor! The spike-as-reference-implementation point is the part most teams skip.
One thing worth flagging for readers working in brownfield: step 1 assumes the spike is cheap. In a regulated enterprise environment it's usually the most expensive item in the whole process. The unknown you need to resolve sits behind a system you can't touch in a throwaway way, data access takes weeks, the integration environment is shared, and the behaviour you're trying to prove is encoded in something nobody documented in twenty years.
Which inverts the economics of the workflow. Greenfield: the spec is a writing cost. Brownfield: the spec is a discovery cost, and most of it is documenting what the system already does rather than deciding what the new one should do. Same artefact, entirely different work.
The process still holds, it just stops being the cheap phase.
This is a great point! Right, especially in bigger, enterprise companies, the process and overall bureaucracy to get what you need, can be quite problematic.
Bureaucracy is a real part of it. The sharper problem is that in brownfield the unknown is usually epistemic rather than procedural, nobody currently at the company knows what the system does, so the spike isn't waiting on approval, it's doing archaeology. Approvals you can escalate. That, you can't.
I really enjoyed this, Gregor — especially the point about the reference implementation being worth more than a page of spec.
Curious about the lifecycle after implementation though:
Does Larridin keep the spec/plan artifacts connected to the codebase long-term (e.g., as onboarding material, architecture decision records, context for future AI agents), or are they mostly discarded once the code is merged?
This question about implementation seems to me to be the real difference between SDD and the purely “prompt-and-pray” approach.
Great question, they are kept. You can see an example in the superpower repo, how they keep the specs: https://github.com/obra/superpowers/tree/main/docs/superpowers/specs
and also the plans: https://github.com/obra/superpowers/tree/main/docs/plans
I do imagine that after some time, the ones that are not relevant anymore are cleaned up.
I love it !
Glad it resonated!
Creating a spec to nail down ambiguity sounds like a good plan. My own experience though varied.
Suppose a "spec" contains
1) the expected user behavior/domain
2) based on that, we can create an implementation architecture. How does it integrate into the whole system, new components? New services? New APIs? New classes?
3) based on that, we can create an implementation plan. An ordered sequence of steps of code changes. Not the code changes themselves, but which parts to implement.
Each step could then be iterated on together with the agent. Human or agent discovers edge cases, ambiguous behavior, architecture inconsistencies and so on.
But what I usually observe, is that I burnt many tokens to keep the previous steps consistent with the following. During architecture, or implementation plan, the discovered ambiguity should also be correctly represented in the domain/user behavioral part. And when finally switching to "execute/implement it", new architectural or coding decisions needed to be made.
The devil is always in the details, and specifying all up front has never worked.
Thanks for the article! There is one thing I don't like about specs: saving them after implementation. In my understanding it creates a duplication, now we have 2 source of truth - a spec + our code.
But I believe only code should be our source of truth. A similar situation was with comments: comments could be clear, but they could also mislead, since there is no guarantee that the code does the same thing as the comments describe.
My daily approach is to create an implementation plan, based on requirements in PRD, Jira, and Figma design. Once AI implements the implementation plan - I remove it and leave my code as a source of truth.
I have been tinkering with making this self-evolving. Essentially keep spec around as a lean set of skills per feature area. Example, account handling and backup would have their separate skills and certain invariants encoded that AI is able to pickup when making changes into those subsystems.
"Spec was simply for ensuring core logic works and is token efficient." => I think you meant Spike ?
Loved the article Gregor, and the visibility it’s bringing on benefits of SDD.
Two questions I had after reading the article was:
1. how do we quantify/assess the quality of spec and implementation plan?
2. You mentioned “Decisions on the fly” as a no-go approach. What would you recommend if teams/AI do stumble during implementation. Would you rather advise them to go back to the drawing board and start with spike/spec generation stage?
Thank you for all the linked examples! Going to take these away and apply them to some of my agentic workflows. I have been doing a variation of creating a spec using the grill me skill and have been looking for examples on how to structure a spec, so this is really helpful!
Or as I called it “Documentation driven dev”
But one has to know the vision and goal before one creates all this. Or better yet, all that move fast break things approach now occurs before your write a line of code.
The spec is advisory. So is the implementation plan. Nothing in the pipeline actually prevents the LLM from wandering off-spec mid-implementation. When the model drifts, who catches it? The reviewer. And now the reviewer is doing the exact work the spec was supposed to eliminate, line by line, checking whether what got built matches what was specified.
Which means the spec reduced the probability of deviation. Cool. Didn't make deviation structurally impossible. The reviewer is still the only gate.
There's a missing step between "here's the plan" and "here's the PR." A deterministic check. Did the output touch only the files the spec declared? Did it satisfy the test plan's conditions? Did it introduce any architectural decisions that weren't in the spec? Those are all checkable. Automatically. Without a human reading every line.
Make that check structural and the spec stops being a document the model might follow. It becomes a constraint the model cannot violate. The reviewer goes from the only gate to the final gate which is a very different job.
https://metacortexdynamics.substack.com/p/stop-letting-ai-coding-agents-decide
What this does is to make the spec a result of iterative and incremental steps, meant to reduce uncertainty with every iteration.
Why not name it for what it is: a living document, not a one shot exercise.
Thanks for rediscovering Agile.
We're rediscovering all classic engineering processes. Domain driven design, behavioral driven tests, creating ADRs before implementing.
The only difference is now we **have** to specify it, because LLMs dont know our knowledge.
Yes. The trouble is that much of this knowledge (and often the crucial parts) is tacit and/or counterfactual. And that finally means that no amount of documentation volume or rigor will solve the problem.
Some good points here. Spec-Driven development is very helpful indeed. What I am missing though is 1/the importance of context engineering, even in SDD, and 2/implementing testing/evaluation feedback loop.
good one.
Great article, thank you! I also use spec driven development more 6 months. Tried multiple frameworks and approaches, but I still have one problem that needs to be solved and I should like to hear your thoughts, how to handle the customer feedback and keep it in sync with spec?
Thanks 🙏
Thanks for the article! I have using spec driven development and making teams to adopt and it is really making a difference.
We have adopted OpenSpec and to improve vanilla OpenSpec workflows, I created an open source project that we use in our projects and see great improvements. Please check it out, the project is in active development and would love to hear feedback and ideas from the community.
opensource project: https://github.com/sudokar/openspec-plus
I moved to using specs couple of weeks ago and they really improved the way I worked. I was using some scattered version of this all the time, but only after I gave it some structure the benefit became obvious - the work is resumable and trackable, for me and for the agent. Instead of asking “Hey, do you remember what we were doing”, I just say resume. That’s also why I keep the spec after the work is done, there are usually important details about what was done and why which I can use as reference points later. What I added to mine is a drift section - basically tracking the gap when the work departs from what was agreed and why. Planned this, did that, because of this.