Goodbye Vibe Coding: Spec-Driven Development with SpecKit + OpenSpec

You Explained the Requirement Three Times, and AI Still Built the Wrong Thing

#

“Vibe coding” has been enjoyable in the last two years: we describe what we want in natural language, the model writes code quickly, and if it runs we keep it; if it fails we continue chatting. The principle is “move first, refine later.” But it can also drive people crazy. Requirements are scattered in chat history, the original goal gets forgotten during edits, and team review becomes painful because reviewers can only stare at the diff and guess what changed.¹

A calmer approach is to treat a specification as the shared receipt between us and AI. Write What and Why clearly first, then let AI implement How. Coding becomes more controllable and easier to review.

Core Idea of Spec-Driven Development (SDD)

#

Spec-Driven Development² reverses the usual AI-coding pattern. Instead of asking AI to guess what you want, you agree with AI before coding begins and use an executable, living specification as the shared understanding. At each stage, your responsibility is not casual command-giving, but verification, reflection, and correction.

It usually has three parts:

• Spec: user journeys, requirements, and acceptance criteria (What / Why)
• Plan: technology stack, architecture decisions, and constraints (the frame for How)
• Tasks: executable atomic tasks for implementation

The key point is that each step has a checkpoint. AI writes the artifact first, we review it clearly, and only then do we let it write code. This is especially useful for team collaboration because review is not limited to code; you can also review what the change is supposed to achieve.

Core Advantages of SDD over Vibe Coding

#

spec-kit: Best for 0→1 Initial Development

#

If you are creating a new project from scratch, I strongly recommend trying spec-kit. Its strength is turning a vague idea into an executable plan through Constitution → Specify → Plan → Tasks.

Install and Initialize

#

1
2
3
4
5
6
7

# Create a new project (generates a folder)
specify init my-project --ai claude

# Or initialize in an existing project
specify init . --ai claude
# or
specify init . --ai codex

Note: specify init . --ai can be followed by any AI agent. See supported AI agents.

Pitfall note: if you use Codex, configure environment variables after installation. Slash commands currently support only system-level commands in Codex, not project-level commands. If that feels troublesome, try using opencode.

How to Use It

#

Commands

#

Basic commands:

Optional commands:

Workflow Demo

#

1. Establish project principles

Use /speckit.constitution to create project principles and development guidelines that govern later work.

1

/speckit.constitution

2. Create the specification

Use /speckit.specify to describe what you want to build. Focus on what and why, not the technology stack.

1

/speckit.specify Build a note app that supports Markdown, tags, and full-text search.

3. Create the technical plan

Use /speckit.plan to provide your technology stack and architecture choices.

1

/speckit.plan Use SQLite, a local-first architecture, and a simple web UI.

4. Split into tasks

Use /speckit.tasks to create an actionable task list from the plan.

1

/speckit.tasks

5. Implement

Use /speckit.implement to execute tasks and build the feature according to the plan.

1

/speckit.implement

OpenSpec: Better for Long-Term 1→n Iteration

#

Now look at OpenSpec. It is very suitable for 1→n work on an existing repository. GitHub repository: OpenSpec

OpenSpec’s core idea is to separate the current system truth from proposed changes. Existing capabilities live in openspec/specs/; new intentions live in openspec/changes/. A change is proposed, reviewed, applied, and then archived back into specs after it is complete.

Install

#

OpenSpec officially requires Node.js >= 20.19.0, so check node --version first.

1

npm install -g @fission-ai/openspec

Verify installation:

1

openspec --version

Initialize OpenSpec in a Project

#

1

openspec init

During initialization, it guides you to choose the AI tool to integrate and generates the openspec/ structure plus necessary agent instructions in the project.

Basic Workflow

#

1. Draft a proposal

Ask your AI to create a change proposal:

1

Create an OpenSpec proposal for adding dark-mode auto switching to this project.

2. Validate and review

Check whether the change was created correctly and review the proposal:

1
2
3

openspec list
openspec show <change-id>
openspec validate <change-id> --strict

3. Refine the specification

Iterate on the proposal and spec deltas until the requirement is clear.

4. Implement the change

When the spec looks good, apply the change through your implementation workflow.

5. Archive the completed change

After implementation is complete, archive the change:

1

openspec archive <change-id>

Tools with native slash commands, such as Claude Code, CodeBuddy, Cursor, Codex, Qoder, and RooCode, can use displayed shortcuts. Other tools can work through natural-language requests such as “create an OpenSpec proposal,” “apply an OpenSpec change,” or “archive a change.”

Which One Should You Use?

#

If you only want one rule, use this:

• If you are still opening new ground and turning an idea into an executable project, use spec-kit (0→1).
• If you already have a repository and code, and need continuous iteration with each change written as a reviewable receipt, use OpenSpec (1→n).

Comparison:

References

#