Spec-driven Development

Yesterday, I learned about spec-driven development (SDD), the newest AI development workflow that all the hipsters and vibe-coders have been talking about for most of the first half of 2026. I even confirmed it with a friend who was working with a tech company at a time that this was how they were doing things. After reading about it, and asking AI a lot too, I came to the conclusion that my current workflow of creating JobbedIn is not too far off from what SDD is.

Basic explanation

Essentially, instead of having AI generating code right away, you and the AI agent generate a document called SPEC.md. This document defines user requirements, acceptance criteria, UI/UX requirements, and explicit out-of-scope boundaries. For every feature, epic, you get one SPEC.md, with one PLAN.md and one TASKS.md. PLAN.md outlines technical approach, file modifications, and database schema changes required for that specific feature. And TASKS.md is the actual tasks the AI agent need to do to implement that feature. There are more specifics that I learned and condensed into this doc here.

An important part that most explanations of SDD won't give you, that I had to learn from my friend and digging around, is that in this methodology, "Spec First, Code Second". Any update or changes you make to the feature, you either have to update the SPEC.md first and let the agent re-generate the PLAN.md, TASKS.md, code, or you have to reflect the code changes back to SPEC.md to synchronize them and avoid "Spec Drift". In SDD, the core principle is:

Thoughts

As I am learning more about this methodology, I feel like we just rediscovered Waterfall methodology, which is to define everything before a line of code is written. The problem with this approach is that it assumes we can plan and anticipate ahead of everything. The reality of software development, and life in general, is that we don't know what we want. Heck, I didn't even know what I wanted when I was developing JobbedIn and Papersy. I just wanted to learn multi-agent, RAG, and I needed a cover letter generator. Imagine your clients, who also don't know what they want. How would you define a vague requirement into a rigid, static specification document and expect it to not change? As you work through a problem, requirements and specifications change. That's not to mention that many would argue that SPEC.md should be written as clear, well-defined as possible so the code generated won't be a slop because AI hallucinates. But if I have to define that clearly, I might as well just write it in code. I entered the workforce during the Agile era, and I believe in the Agile way of iterating as we go (some definitions on scope boundaries, budgets, key milestones, and dependencies would be extra helpful).

Another article I read was The three levels of SDD from The AI Agent Factory. According to the article, I am at level 1. I generated a PLAN.md, consisting of tasks for AI to handle. Afterward, I throw it away. It is still in git history, but I never look back. SDD would be in level 2, where SPEC.md and its related folder live near the code and it is generated before the code. Spec will be updated alongside the code if there is a change in feature. There is also level 3, but I don't think we will be near that level in the foreseeable future, since coding agents right now continue to be unreliable in code generation. Level 3 is more suited for solved problems: simple CRUD, one-off script.