Spec Driven AI Development
Spec driven development is a workflow for AI-augmented coding where you develop a spec/plan before starting execution. This is the golden workflow of AI coding: balancing memory, correctness, user expectations, and historical context of the feature. In this post, I’ll talk about the more primitive forms of prompting and then detail why spec driven development is the best approach.
Miracle prompting
Most newcomers to AI coding will put an ambiguous prompt (like “build me an app that lets me track my sleeping habits”) in their textbox and expect miracles. The more ambiguous your prompt, the more assumptions need to be made by the AI model, which means the picture in your head will not match the output of the model. Many of these users will publicly vow that AI coding is a gimmick and write it off, when they used the wrong workflow.
Unfortunately, models don’t ask clarifying questions unless you ask them to, so miracle prompts (also known as “zero-shot,” or “no example“ prompts) rely on the knowledge that the model has from its training.
The folks that don’t abandon the session, will endure a very arduous and lengthy back and forth, forcing a solution that kind of looks like what they wanted, but starting from the wrong foundation. They’ll also have so much extra code that over-engineered for things they never wanted, making the codebase more complex and harder to extend.
Informed prompting
Eventually, you learn that you need to supply more details (examples of features you want) up front. This reduces the set of assumptions that the model has to make, which produces an end result (with relatively less effort than before) closer to what you had in mind. This is what’s known as one-shot, multi-shot, or multi-example prompting.
Though a much better approach, the hard part is coming up with “the perfect prompt.” It takes a lot of time to write up. It forces you to articulate more of the solution in your mind. But it may still lack sufficient detail and require back and forth. Plus, the model will forget this initial prompt since it has limited memory (context window) and has to purge details to make space for satisfying upcoming chats in your session. This can result in “hallucinations” (the model making things up because it doesn’t know or remember the details of what it was working on).
Pro-tip: Ask the model to “make sure you understand” your prompt, which will force it to ask you clarifying questions (improving your prompt).
Spec driven prompting
In this approach, you and the model collaborate on a dedicated plan that’s saved in a file (markdown is the growing standard) on your computer. You go back and forth on this plan until you’re happy with the detail. Only then, do you tell the model to start execution work. The model’s plan will/should include phases/milestones of the work, use cases to satisfy, testing guidelines, edge cases to consider, constraints on what it should NOT do, features you want built, details on the user interface, and more.
This is, so far, the best approach. When the model has to purge its memory to make room for handling upcoming chats, you can point it back to your dedicated plan to pick up where it left off. The plan’s verbosity reduces the back and forth needed to achieve the picture in your head. Many of the model’s assumptions are laid out for you to critique/correct/extend. You can come back to the plan at a later time if you need to switch projects/features. The phased nature of the plan means that there are stopping points where you can correct the plan as you learn more without having to start all over. Depending on how your plan is structured, you may be able to have multiple phases implemented in parallel (using subagents).
Pro-tip: after the model completes a phase of the plan and you’re happy with the progress, git commit the changes before proceeding with the next phase. This way, you can always cleanly go back to the last good state versus relying on IDE checkpoint features or the model’s ability to undo all of its changes successfully.
When you’re done implementing the feature, you can ask the model to simplify the plan to serve as a concise, historical artifact of the what the feature is, how it works, and why it was built. You can then reference this plan if you’re building a new feature that builds on top of this old one (almost like long term memory).
Pro-tip: Tell the model to “create a plan in feature-name.md” as the initial part of your prompt to implement your ask (signaling that you don’t want the model to jump to execution). You could provide an informed (detail filled) upfront prompt to save time here too. If you want to plan more during any phase of execution, tell the model to “plan with me” and then “write those details in the plan myapp.md” when you finished planning out the changes you want.
I don’t see spec driven development going away, even as the models have larger context windows (more memory, meaning fewer purges). It’s the perfect workflow to force you and the model to clarify assumptions and stay on track as you build features together.
