>_nexthopreachable

From Vibe Coding to Spec-Driven Development with OpenSpec

Ali Bahadır Coşkun8 min read

I’ve spent a lot of time experimenting with AI-assisted coding, and I find it genuinely fun. You describe what you want, the model writes it and you have a working solution well maybe sometimes. This can be very useful. I can build a small tool in one evening. You can also ruin a whole project in one evening. Thats where spec-driven development comes in. It is a method to keep the code correct for a long time. Before today I had no real method. I just vibe coded and hoped for the best. Now that I have discovered spec-driven development vibe coding feels less like a gamble and more like a tool.

What I am building

I was thinking of what to build so I can try spec-driven development. So I came up with this idea of building a coaching platform. For 10 years I coached weightlifting and CrossFit. But I have been out of the game for a while. I want to get back into it, but I do not want to coach in person this time. I want to coach online. So I decided to build a platform where people can get coaching from me using spec-driven development.

The Podcast

This whole thing was inspired by the Art of Network Engineering episode Stop Vibe Coding: Start Spec-Driven Development, with John Capobianco. Before this episode I had no idea that spec-driven development was a thing. As soon as I watched the first 10 minutes I knew I had to try it.

Vibe Coding: What Works and What Does Not

Vibe coding is great at the start. The first version comes fast. Small scripts that I will throw away are perfect for it. It is also good when I do not know the answer yet and I just want to explore an idea.

The problems start when the project grows. The decisions live only in the chat, so when the chat is gone, the reason is gone. The model forgets what we decided early and makes new choices. A new prompt changes things I did not ask it to change. And I can only review the code. I cannot review what I wanted, because I never wrote it down.

For me it is like typing config directly on a production router. It is fast and it often works. When it breaks, you do not know what changed.

Spec-Driven Development

Spec-driven development is an approach to building software where you define what the system should do before writing the code. Instead of jumping straight into implementation, you create a clear specification outlining the requirements, expected behavior, and constraints. This specification serves as a shared reference for developers and AI coding agents, helping them plan, implement, and test features against the same requirements. The goal is to reduce ambiguity, prevent unnecessary rework, and ensure the final product actually matches what you intended to build.

OpenSpec

There are a couple of tools for spec-driven development. These are the main ones:

  • GitHub Spec Kit: an open-source toolkit from GitHub. It gives you a step-by-step flow from constitution to code. This is the one John uses in the episode.
  • OpenSpec: a very light tool. It uses plain markdown files and is built for changing existing code.
  • Kiro: an IDE from AWS with the spec workflow built in. It is a full editor, not a toolkit you add to your own setup.
  • Tessl: it treats the spec as the source. You edit the spec and regenerate the code.
  • BMAD-METHOD: an open-source framework that uses many AI agents with roles, like analyst, architect and developer, across the whole development process.
  • Agent OS: it focuses on giving the agent your standards and conventions, not on keeping long-lived specs.

I decided to use OpenSpec. It keeps the specs as markdown files inside the repository, next to the code. Each change gets its own folder with a proposal, a task list, and the changes to the spec. The model and I review these first. When the code is done, I archive the change and the main spec is updated.

The good part is that the spec does not get old in a wiki. It changes together with the code.

What I saw in practice:

  • The output is more accurate. The model has a clear target, so it guesses less.
  • It drifts less as the project grows. The spec brings the model back to what we decided.
  • It costs more time before the first line of code. For a very small task this is too much.

OpenSpec vs GitHub Spec Kit

Both tools do the same basic thing. The specs are markdown files in your repo and the model works from them. The difference is how they organize the work.

Spec Kit is a full pipeline. You go through constitution, specify, clarify, plan, tasks and implement, and every feature gets its own set of files. This is the flow John uses in the episode. It is very structured. I think it fits best when you start a new project from zero and want the full process.

OpenSpec is lighter. It keeps the current specs (what the system does today) separate from the proposed changes (what you want to change). You write each change as a small delta on top of the current spec, and when you archive it the delta is merged in. I think this fits better for a project that already exists and keeps changing, because you do not need to run the full pipeline for every small change.

If you want strong process and a constitution, look at Spec Kit. If you want less ceremony and you already have code, look at OpenSpec.

Spec-Driven Development vs Older Frameworks

Writing things down before coding is not new. Engineers have been trying different ways of doing it for a long time.

TDD. You write a failing test first, then write code until it passes. The test checks the behavior, but it does not say why you want the feature. A spec explains the intention and a test proves it. With a model they work well together, because the model can generate tests from the spec. The episode talks about this too.

BDD. This is the closest one to SDD. You describe the behavior in plain language (Given, When, Then) before you write code. The difference is who reads it. BDD scenarios are written for humans to agree on, and then someone automates them by hand. A spec in SDD is written so the model can read it and build from it.

Waterfall. The obvious question is did we go back to waterfall again? Waterfall wrote one huge requirements document at the start and was slow to change it. Here every spec change is small, and the spec is updated after every change. There is also a practical reason. Writing code used to be the expensive part, so people skipped the specs. Now the model writes the code so we can focus more on the spec.

Comparison

These are not exclusive. You can mix them.

ApproachWhat you write firstGood atWeak at
Vibe codingA promptSpeed, prototypes, exploringDrift, no record of decisions
OpenSpecProposal, tasks, spec changesExisting projects, small changes, specs that stay in the repoWriting before coding, too heavy for tiny tasks
Spec KitConstitution, spec, plan, tasksA full structured pipeline, new projectsMore steps and more process
TDDA failing testThe machine checks the behaviorTests do not explain why you want the feature
BDDGiven/When/Then scenariosBehavior that humans can read and agree onScenarios need work to keep them alive
WaterfallA full requirements documentClear scope and sign-offSlow to change, the document gets old
Plan-first with a rules file (CLAUDE.md)Standing rules, then a planKeeps conventions stable across sessions, low costRules cover style and structure, not the behavior of each feature

What I Do Now

  • If its a throwaway script just vibe code it.
  • Anything I will keep and extend I write the spec first.
  • Standing rules for the project go in a rules file. Behavior of features goes in specs.

This way I can keep the speed of vibe coding for small tasks, but I have a method to keep the code correct for the long term.