Beyond Vibecoding: Spec Driven Development with OpenSpec & Open Code Review | Personal Blog<br>Table of Contents

Note This blog post is based on my personal experience of adopting OpenSpec when building a new greenfield project & using for legacy codebases. It&rsquo;s a tool that genuinely improves my workflow and I believe many teams can benefit from its adoption.

What&rsquo;s OpenSpec and Why Might You Need It?#<br>OpenSpec is basically a collection of skills / commands (read: markdown files) which will create specification files for you as the basis for you implementation. Think of it as a fancier plan mode!<br>Open Code Review can help you ensure quality of both your specs & implementation by running multiple review agents in parallel. It can minimize false positive findings by letting the independent review agents discuss their findings.<br>Why?<br>Given a good spec state-of-the-art models can one-shot even complex tasks. You can implement much quicker and guarantee quality at the same time. You might not be 10x faster, but 2-5x.

Specs live in your repository. You commit them along your code. If done right, you have a full audit trail of any decision made: Not just what is documented (that can be inferred from the code itself), but also the why . Your proposal and design are archived as markdown documents. So ideally, when you ask yourself in 12 months Why did choose DuckDB over Pandas again?, it&rsquo;s documented in the corresponding proposal & design.

Prerequisites<br>You need experience, you need to know what you want to build, or at least be able to identify during the explore phase what you don&rsquo;t want.

You need to be able to communicate your requirements and identify what context the LLM is missing if it goes off the rails. In cases where you know exactly what you want - as you might have built it many times before, with small variations, or generally just have the experience - you can build it fast & in better quality than you would have by hand.

The 5-Step Spec-Driven Workflow#<br>TL;DR: explore → propose → review → apply → review#<br>/opsx:explore your idea: Refine and ground in the codebase, give as much context as needed → most of your time should be spend here!<br>/opsx:propose your spec: Create specification docs - the basis for your implementation → does not require humand input; the explore phase&rsquo;s output is its input<br>/ocr:review your proposal: Catch unspecced edge cases, refine your spec → needs human attention<br>/opsx:apply your proposal: Implement your feature → needs no or limited human attention<br>/ocr:review your implementation: Ensure code quality & find bugs → needs human attention<br>Step 1: /opsx:explore - Refine your idea with idea#<br>Step 1 is where you should spend most of your time. When you have a general idea, but need to figure out what the best architecture is use /opsx:explore:<br>/opsx:explore I want to add Dagster to orchestrate this repo's jobs. Dagster should:<br>- Submit batch jobs<br>- Monitor / poll these jobs async<br>- Support AWS Batch & Azure Batch as production backends and Docker as a backend for local development

OpenSpec will ask dive deep into your codebase and continually ask you questions. The more context you give it here the better:<br>Architecture guidelines or even the full architecture you have in mind<br>Technologies to use or to consider<br>Reference repositories<br>Related tickets<br>etc.<br>Note Your idea here can be a big feature or component of your final product. It does not need to be small — if you want to break it up into smaller chunks, you can still ask it to do this at the end of your session. Your explore session can also be cross-repository if you have downstream or upstream dependencies.

Important things to keep in mind when exploring:<br>Answer any question you are being asked. If a question does not make sense to you, then your agent is usually missing context that might be obvious to you but it cannot infer. Ask it to slow down, explain itself or give it more context that might clear up this question

If a suggestion seems overly complex, call it out. Ask why it&rsquo;s needed, for easier alternatives and potential trade-offs

Generally: Explore mode works best when you 1. know what you want to build or 2. are good at recognosing when the LLM goes off in an overly complex direction. You need to be able to judge suggested architectures and overrule nonsensical LLM suggestions.<br>Step 2: /opsx:propose - Create the Proposal / Specs#<br>Once all open questions are answered and enough context was provided, /opsx:explore will tell you that you&rsquo;re now ready to create the proposal via /opsx:propose. It generates a change folder under openspec/ with the proposal, design decisions, and task breakdown:<br>openspec/<br>└── dagster-orchestration/<br>├── .openspec.yaml<br>├── proposal.md<br>├── design.md<br>├── tasks.md<br>└── specs/<br>└── spec.md<br>I recommend:<br>Read proposal.md. It should document the context:What&rsquo;s the current state?<br>Why do we need this?<br>Reference team internal discussions<br>etc.

Read...