Can Spec‑Driven Coding Tame AI‑Generated Messy Code? An OpenSpec Walkthrough

OpenSpec Overview

OpenSpec is a spec‑driven AI programming framework that follows a "spec first, code later" approach. The framework stores planning artifacts—proposal, specification, design, and task list—in a Git repository (over 53k stars). After human confirmation, AI generates code that aligns with the documented requirements.

Core Workflow

/opsx:explore

— Enters exploration mode to discuss and clarify requirements via dialogue. /opsx:propose — Generates planning artifacts: proposal.md — Why the change and what to do. specs/spec.md — Structured requirements and acceptance criteria. design.md — Technical design description. tasks.md — Implementation steps. /opsx:apply — Executes tasks sequentially, producing code and updating task progress. /opsx:archive — Moves completed planning documents into an archive directory.

Installation and Initialization

npm install -g @studyzy/openspec-cn@latest

cd your-project
openspec-cn init --tools opencode

Initialization creates an openspec directory for planning artifacts and registers the opsx command prefix. The dashboard can be opened with:

openspec-cn view

Example: Front‑end/Back‑end Blog Platform

Workflow demonstration using a blog site project.

Run /opsx-explore to start a pure‑conversation requirement discussion.

The system asks clarification questions to confirm the basic direction.

It presents three technical solutions for selection.

For the chosen solution, it prompts key design decisions.

A data model is generated for review.

Subsequent dialogue covers implementation concerns, performance considerations, and fine‑grained details.

When the overall plan is satisfactory, /opsx-propose init-project creates the planning artifacts. /opsx-propose init-project The resulting artifact tree includes proposal.md, specs/spec.md, design.md, and tasks.md (illustrated in the image below).

Execute the implementation with /opsx-apply init-blog-platform. /opsx-apply init-blog-platform Task execution produces a summary overview (shown in the image below).

Archive the completed documents with /opsx-archive. /opsx-archive All planning files are moved into the archive folder (illustrated in the image below).

Conclusion

Adding a lightweight specification layer makes AI‑generated code more controllable and better aligned with real project needs.

Project Links

Original repository: https://github.com/Fission-AI/OpenSpec

Chinese version: https://github.com/studyzy/OpenSpec-cn