Taming Vibe Coding: How OpenSpec Enforces Spec‑Driven AI Coding

Problem

AI coding tools such as Claude Code, Codex, and Cursor often generate code that diverges from the original intent, leaving developers uncertain about what was actually requested.

Spec‑Driven Development

The core idea is to avoid letting AI guess from chat history and instead define the desired behavior in a specification before asking the AI to generate code.

Tool landscape

Spec Kit – GitHub official, Python CLI, heavy documentation.

Kiro – AWS, independent IDE, locks to Claude models.

Superpowers – plugin suite for Claude Code/Codex, includes 20+ skills, tightly coupled to the Claude ecosystem.

OpenSpec – npm package from Fission‑AI, lightweight, artifact‑driven, flexible.

BMad‑Method – community‑driven multi‑sub‑agent orchestration with nine dedicated agents, zero dependencies.

Trade‑offs: all‑in‑one solutions (Spec Kit, Kiro) require tolerating complexity; plugin‑centric approaches (Superpowers) fit those already using Claude Code; lightweight, unopinionated workflows favor OpenSpec.

OpenSpec overview

OpenSpec is a lightweight spec layer built for brownfield projects, emphasizing fluid, iterative, easy, and scalable usage.

Generated artifacts per feature

proposal.md

– why the change is needed. specs/ – requirements and scenarios in Given/When/Then format. design.md – technical approach. tasks.md – implementation checklist.

These files reside in an isolated changes folder and are archived after completion.

Installation

npm install -g @fission-ai/openspec@latest

cd your-project
openspec init

The initialization creates an openspec/ folder for specs and registers a skill command ( /opsx:*) in the appropriate harness directory.

Full workflow (OPSX)

Propose : /opsx:propose add-dark-mode. The AI creates the four artifacts and pauses for review.

You: /opsx:propose add-dark-mode

AI:  Created openspec/changes/add-dark-mode/
     ✓ proposal.md — why we're doing this, what's changing
     ✓ specs/       — requirements and scenarios
     ✓ design.md    — technical approach
     ✓ tasks.md     — implementation checklist
     Ready for implementation!

Apply : /opsx:apply. The AI implements tasks listed in tasks.md, marking each as completed.

You: /opsx:apply
AI:  Implementing tasks...
     ✓ 1.1 Add theme context provider
     ✓ 1.2 Create toggle component
     ✓ 2.1 Add CSS variables
     ✓ 2.2 Wire up localStorage
     All tasks complete!

Archive : /opsx:archive. Moves the change folder to an archive directory and merges specs into the main repository.

You: /opsx:archive
AI:  Archived to openspec/changes/archive/2025-01-23-add-dark-mode/
     Specs updated. Ready for the next feature.

Spec evolution (delta)

OpenSpec records spec changes as deltas rather than overwriting entire files, similar to git diff. This makes code reviews easier by highlighting exactly what has changed.

### Requirement: Session expiration
- The system SHALL expire sessions after a configured duration.
+ The system SHALL support configurable session expiration periods.

#### Scenario: Default session timeout
- GIVEN a user has authenticated
- - WHEN 24 hours pass without activity
- THEN invalidate the session token
+ - WHEN 24 hours pass without "Remember me"
+ THEN invalidate the session token
+ #### Scenario: Extended session with remember me
+ - GIVEN user checks "Remember me" at login
+ - WHEN 30 days have passed
+ - THEN invalidate the session token

Project configuration

Contextual information such as tech stack, API conventions, testing tools, and style rules can be injected via openspec/config.yaml, ensuring the AI includes relevant details in generated specs.

schema: spec-driven
context: |
  Tech stack: TypeScript, React, Node.js
  API conventions: RESTful, JSON responses
  Testing: Vitest for unit tests, Playwright for e2e
  Style: ESLint with Prettier, strict TypeScript
rules:
  proposal:
    - Include rollback plan
    - Identify affected teams
  specs:
    - Use Given/When/Then format for scenarios
  design:
    - Include sequence diagrams for complex flows

Suitable users

Individual developers or small teams seeking lightweight AI constraints without heavyweight processes.

Teams refactoring legacy projects that need AI to understand existing context.

Users mixing multiple harnesses (e.g., Claude Code today, Codex CLI tomorrow).

Anyone who values clear change history and traceable work.

Limitations

Relies on high‑quality models (e.g., Codex 5.5, Opus 4.7; Chinese models like Qwen 3.7 Max or DeepSeek V4 are needed for comparable quality).

The OPSX workflow is newly rebuilt and documentation may lag behind implementation.

Chinese language support exists but defaults to English; artifacts can be forced to Chinese via config.