Beyond Vibe Coding: A Deep Dive into OpenSpec Spec‑Driven Development

Problem with Vibe Coding

Vibe Coding, introduced by Andrej Karpathy in early 2025, relies on natural‑language interaction with AI to write code based on a developer’s “feel”. It works for tiny demos but quickly encounters three critical issues when a project grows:

Context drift – later dialogue rounds weaken the original architectural constraints.

Model hallucinations and over‑design – the model may introduce unrelated third‑party libraries or fabricate non‑existent interfaces.

Verification gap – AI reports “code completed” while the code fails at runtime, lacking an objective checklist.

Spec‑Driven Development (SDD)

To avoid these pitfalls, the article advocates Spec‑Driven Development: before any AI‑generated line of code, a complete specification document (Spec) must be created and treated as the single source of truth for the project.

OpenSpec design

OpenSpec implements SDD by separating three concepts:

Specs – the authoritative list of all system behaviours (single source of truth).

Changes – proposed modifications or new features.

Archive – historical record of all changes.

This separation forces the AI to produce a spec before code, allowing early detection of unnecessary dependencies or logical flaws. Unlike many SDD tools that only support 0→1 projects, OpenSpec also supports scaling from an existing codebase (1→n).

Installation

# Install the latest version (current: 1.3.1)
npm install -g @fission-ai/openspec@latest
# Initialize a project
openspec init

Running openspec init creates an openspec/ folder, a config.yaml file, and injects slash commands into the Claude Code environment.

Opsx commands

/opsx:apply

– implement code based on the task list. /opsx:archive – archive and organize specification documents after development. /opsx:explore – research, troubleshoot, and clarify requirements. /opsx:propose – generate change proposals and system architecture designs.

Custom commands can be listed with openspec config profile.

Full development workflow (attendance‑management example)

1. Design a prompt describing the desired system (Chinese example):

请设计一套考勤管理系统，员工可通过该系统完成上下班打卡操作。
系统权限分为管理员与普通用户两类：管理员支持新增、编辑、删除用户账号。
新增用户时，系统会自动发送邮件，告知用户登录密码。
员工可在系统内发起请假、加班申请；所有假单申请都需要走审批流程，支持年假、调休两类假期申请，同时配套代办代理人机制。
技术选型：前端采用 Vue3 + JavaScript，后端使用 Spring Boot3.5.0 + Java21，数据库选用 MySQL8+，禁止使用Lombok。
整套项目基于 docker-compose 一键启动。

2. In Claude Code, run /opsx:propose 需求. OpenSpec creates: proposal.md – project goals and scope. design.md – technical design, risk analysis, and solutions. specs/ – directory with fine‑grained functional specifications. task.md – empty checklist.

3. Review and adjust the specs, then execute /opsx:apply. The tool generates front‑end and back‑end code and updates task.md with checkmarks for completed items.

4. After verification, run /opsx:archive. OpenSpec populates an archives/ folder with dated documentation and fills the previously empty specs/ folder with finalized specification files.

Project initialization and Claude configuration

After the initial setup, the /init command creates a CLAUDE.md file that loads automatically in each Claude session, providing the model with the project’s architecture, tech stack, and development standards.

A prompt such as the following can be used to fill openspec/config.yaml with detailed project information:

请阅读 openspec/config.yaml 并帮我填写项目、技术栈和规范的详细信息。

Feature iteration

When new requirements arise, a request like “帮我设计漏打卡的处理方案，规则要具备灵活性，采用 OpenSpec 规范驱动开发实现。” triggers OpenSpec to create the corresponding spec documents. The developer then runs /opsx:apply to generate the implementation and /opsx:archive to record the change.

Artifacts produced by OpenSpec

proposal.md – validates project goals and scope.

design.md – details technical choices, risks, and mitigation.

specs/ – directory of fine‑grained functional specifications.

task.md – checklist for verification, updated automatically.

CLAUDE.md – loads project context for Claude in every session.

archives/ – dated snapshots of specifications and documentation.

By enforcing a specification‑first approach, OpenSpec catches architectural drift, unnecessary dependencies, and logic errors early, reducing later rework costs.