OpenSpec: Stop 'Vibe Coding', Give AI a Clear Roadmap
Vibe Coding is like asking a contractor to build a house without a blueprint — the result? Chaos by the third month. OpenSpec arrives as an 'architectural blueprint' for AI coding, shifting the paradigm from random chatting to structured Spec-Driven Development.
Faisal Affan
- OpenSpec: "Architectural Blueprint" for AI Coding
- The Problem: Why "Vibe Coding" Is Like Building a House Without a Blueprint?
- The Solution: Spec-Driven Development — Give AI the Blueprint First!
- What is OpenSpec?
- Foundation of Thought: Where Did This Idea Come From?
- Architecture: Two-Folder Model
- Workflow: Three Simple Commands
/opsx:propose— Design First/opsx:apply— Now Build/opsx:archive— Archive & Clean Up- "Project Constitution" — The Rule Book AI Cannot Violate
- Efficiency: Why Does OpenSpec Save Tokens?
- Spec Writing Rules: Firm and Unambiguous
- Required and Forbidden Language
- Scenario Format: GIVEN / WHEN / THEN
- Four Types of Changes (Delta Operations)
- Comparison: OpenSpec vs Competitors
- Comparison Map
- Criticism and Risks: Is This Waterfall 2.0?
- Conclusion: When Should You Use OpenSpec?
- The Bottom Line
- References
OpenSpec: "Architectural Blueprint" for AI Coding
"A wise man builds his house on rock, not on sand." — A universal proverb that also applies to software engineering
TL;DR
OpenSpec is an open-source framework from Fission AI that forces AI to read the blueprint first before starting to build. Instead of back-and-forth chatting without a plan (vibe coding), OpenSpec transforms how AI works into something structured, predictable, and safe for large-scale projects.
The Problem: Why "Vibe Coding" Is Like Building a House Without a Blueprint?
Imagine hiring a contractor to build a house. But instead of giving them an architectural blueprint, you just say:
"Build a room over there. Oh yeah, add a kitchen too. Hey, make it a sliding door instead."
At first it's fine. The room is done, the kitchen is done. But by the third month:
- The kitchen water pipe crashes into the room's foundation 💥
- The contractor forgot you asked for a sliding door, so they installed a regular door
- Want to renovate? The new contractor has no idea why the wall was built at an angle — the old contractor is gone
This is exactly what happens with vibe coding. You chat with AI, ask for code here and there, everything goes smoothly... until the project grows. Then:
🧠 AI Forgets
The conversation context window is limited. AI doesn't remember decisions made 3 days ago.
👻 Intent Lost
Why was the architecture designed that way? Lost when the chat session is closed.
💸 New Technical Debt
Code grows beyond both human cognitive capacity AND the AI's context window simultaneously.
🧱 The Third-Month Wall
Adding new features breaks old ones because there's no system mapping.
The Complexity Wall
Many projects built purely with vibe coding reportedly hit the "complexity wall" by the third month. Adding new features ends up breaking what already works — because no one recorded why the code was written that way.
The Solution: Spec-Driven Development — Give AI the Blueprint First!
Spec-Driven Development (SDD) is the opposite of vibe coding. Its philosophy is simple:
Don't tell AI to write code before there's a clear specification.
If vibe coding is "chat → code → hope it's right", then SDD is "write intent → validate → then code".
And at the forefront of this SDD movement stands a platform called OpenSpec.
What is OpenSpec?
OpenSpec is an open-source framework built by Fission AI that serves as a universal planning layer between human intent and AI execution.
The analogy: if an AI coding agent is the contractor, then OpenSpec is the architect's desk where blueprints are drawn, validated, and stored — before hammer and nail are touched.
Prop
Type
No Vendor Lock-in
OpenSpec doesn't need a special API key or closed protocol. All specifications live inside your Git repository, side by side with your code. Moving from Claude to Gemini? The specs stay the same.
Foundation of Thought: Where Did This Idea Come From?
Architecture: Two-Folder Model
OpenSpec's most important innovation is the physical separation between "current truth" and "change plans". Imagine it like this:
- 📚
specs/= Official school notebook — contains rules that are already in effect - 📝
changes/= Scratch paper — where new ideas are tested before entering the official book
Analogy: Like a constitution — the official document currently in effect.
- 📖 Represents the current system reality that has been validated
- 🗂️ Grouped by domain (auth-login/, checkout-cart/)
- 🔒 Read-only for AI — cannot be modified directly
- 🏛️ Stable until an official archiving process occurs
Analogy: Like a bill (draft law) — a proposal that hasn't been enacted yet.
- 🧪 Sandbox for hypothetical future features
- 📋 Grouped by task (add-dark-mode/, fix-payment-bug/)
- ✍️ AI may write here — but still reviewed by humans
- 📊 Records specification deltas — what changed and why
Why Is This Separation Important?
Imagine AI hallucinates and writes a wrong spec. With this separation,
the damage is contained in the changes/ folder — it doesn't spread to the main
source of truth. Like an airlock system on a submarine: a leak in one
compartment, the ship stays afloat.
Workflow: Three Simple Commands
The entire OpenSpec development cycle runs on just three commands. Like the Design → Build → Archive cycle:
/opsx:propose — Design First
You describe what you want in everyday language. AI then:
- Searches existing specifications for relevance
- Analyzes related code
- Generates four artifacts in the
changes/folder:
Prop
Type
Analogy: Like an architect drawing the blueprint, calculating materials, and creating a work schedule — before the contractor starts drilling.
/opsx:apply — Now Build
After the human approves the proposal, AI starts implementation:
- Pulls tasks from
tasks.md - Works on them one by one iteratively
- Updates the checklist in real-time
- Must not make decisions that contradict
design.md
Analogy: The contractor starts drilling — but must follow the blueprint. Want to move a pipe? Gotta go back to the architect first.
/opsx:archive — Archive & Clean Up
After implementation and testing are complete:
- All artifacts are moved to
archive/with a timestamp - The realized spec delta goes into
specs/(source of truth) - Working folder is cleaned up, ready for the next cycle
Analogy: After the house is built, the architectural blueprint is updated and stored in a vault. Scratch paper is thrown away. Clean.
"Project Constitution" — The Rule Book AI Cannot Violate
The first time you run openspec init, the platform scans your entire project and generates a project.md file — a kind of "constitution" for your project:
🎯 Business Goals
What is the goal of this project? AI must not make decisions that deviate from the goals.
🔧 Tech Stack
TypeScript? Go? React? AI knows its technology boundaries and must not suddenly use another framework.
📏 Code Conventions
Naming convention, folder structure, style guide — AI must follow existing standards.
🧪 Testing Strategy
Unit test mandatory? E2E tests for critical features? AI knows what needs to be tested.
20+ AI Agents Supported
OpenSpec rejects vendor lock-in. During initialization, the platform automatically
detects agent folders (.claude/, .cursor/, etc.) and injects
relevant rules. You're free to use Claude, Gemini, Codex, or whatever.
Efficiency: Why Does OpenSpec Save Tokens?
This is the technical part — but the analogy is simple.
Vibe Coding is like asking the contractor to reread the entire building manual every time you ask them to install one light. Expensive, slow, and the contractor often forgets details on page 847.
OpenSpec gives the contractor only the relevant pages — the electrical blueprint for the 2nd floor, the wattage standards used, and the safety checklist. That's it.
AI receives: ENTIRE repository (millions of characters)
Consequences:
❌ API costs balloon
❌ High latency
❌ AI "forgets" details in the middle
❌ Hallucinations increase drasticallyAI receives: project.md + relevant changes/ folder
Results:
✅ API costs are much lower
✅ Faster response
✅ Signal-to-noise ratio nearly 100%
✅ Hallucinations drastically reducedTechnically, this is because transformer architecture has quadratic complexity — the longer the input, the more expensive and more "forgetful" the AI becomes. OpenSpec cuts the input to the necessary minimum.
Spec Writing Rules: Firm and Unambiguous
OpenSpec has strict rules about how specs are written. The goal: so that AI (and humans) don't misinterpret.
Required and Forbidden Language
OpenSpec adopts the IETF RFC 2119 standard — the standard commonly used for writing global internet specifications:
Prop
Type
Why Does This Matter?
The word "must" in everyday language is ambiguous — it could mean mandatory or just a suggestion. With MUST vs SHOULD, AI immediately knows: MUST is the law of gravity (cannot be violated), SHOULD is a guideline (can be bent with a good reason).
Scenario Format: GIVEN / WHEN / THEN
Every specification MUST have at least one test scenario. The format is borrowed from Behavior-Driven Development (BDD):
#### Scenario: User logs in with valid credentials
- GIVEN the user is registered with email "user@example.com"
- WHEN the user enters the correct email and password
- THEN the system returns a valid access token
- AND the user is redirected to the dashboard pageAnalogy: This is like an exam question for your code. If it can't answer this question, the code isn't correct yet. OpenSpec can run openspec validate --strict to ensure all questions exist and are properly formatted.
Four Types of Changes (Delta Operations)
When proposing changes, OpenSpec forces you to categorize them:
New standalone functionality.
Like adding a new room to a house — it doesn't interfere with other rooms.
## ADDED Requirements
### Dark Mode Support
Sistem MUST menyediakan opsi dark mode...Modifying existing behavior. Must rewrite the spec completely (not just the changed parts).
Like renovating a kitchen — you rewrite the floor plan from scratch, not just scribble on the old one.
## MODIFIED Requirements
### Login Flow (UPDATED)
Sistem MUST mendukung OAuth2 selain email/password...Removing a feature. Must include two things: reason and migration path.
Like demolishing a wall — you need to explain why and how the occupants move to another room.
## REMOVED Requirements
### SMS Verification
- Reason: SMS costs too high, replaced with WhatsApp OTP
- Migration: All users will be migrated to WhatsApp OTPRenaming without changing functionality. To maintain an audit trail.
Like renaming a street — the address changes, but the house stays the same.
## RENAMED Requirements
- FROM: User Authentication
- TO: Identity VerificationComparison: OpenSpec vs Competitors
Where does OpenSpec stand among other SDD platforms?
Comparison Map
| Parameter | OpenSpec | GitHub Spec Kit | Amazon Kiro | BMAD |
|---|---|---|---|---|
| Focus | 🏚️ Brownfield (legacy code) | 🏗️ Greenfield (new projects) | 🏢 Corporate (AWS) | 🤖 Multi-agent |
| Workflow | 3 simple commands | 4 rigid phases | Integrated IDE | Autonomous delegation |
| Context | Delta (efficient) | Full documents (heavy) | Steering files | Sharding |
| Tech Stack | TypeScript/npm | Python/UV | Terminal/VS Code | Framework-agnostic |
| Vendor Lock-in | ❌ None | ⚠️ GitHub bias | 🔒 AWS only | ❌ None |
Criticism and Risks: Is This Waterfall 2.0?
No approach is perfect. Here are the sharpest criticisms of SDD and OpenSpec:
🌊 The Waterfall Shadow
Critics say SDD is 'Waterfall in new clothes.' Early documentation obsession risks killing Agile adaptability.
📄 The Illusion of Control
A pile of spec documents does NOT automatically mean quality code. It could be a false sense of security.
🔄 Context Drift
If specs aren't updated when mid-flight improvisation happens, stale specs are more DANGEROUS than having no specs at all.
⚖️ The Balance Dilemma
Too little structure = chaos (vibe coding). Too much structure = gridlock (waterfall). Where's the sweet spot?
Lessons from History
Model-Driven Development (MDD) in the 2000s had a similar vision: "model first, code automatic." The result? It failed because it was too heavy, not flexible, and couldn't adapt to change. OpenSpec is aware of this risk — that's why they chose a delta approach (lightweight) instead of a full-spec approach (heavy).
Conclusion: When Should You Use OpenSpec?
- Large-scale projects with many developers and AI agents
- Complex legacy codebases (brownfield) prone to regression
- Teams that need an audit trail and accountability for AI decisions
- Projects where architectural consistency matters more than speed
- Corporate environments that need a review gate before AI can commit
- Quick prototypes or proof-of-concepts that will be discarded
- Small side projects worked on by one person
- Simple automation scripts that don't need long-term maintenance
- When you're still exploring ideas and don't yet know what to build
The Bottom Line
OpenSpec is not a replacement for creativity or agility. It is a safety net — ensuring that as AI becomes a more sophisticated "contractor," we as the "architect" don't lose control over the building's design.
Vibe coding is like jazz improvisation — beautiful for a short solo. Spec-Driven Development is like an orchestra — it needs a score so that 50 musicians play harmoniously.
OpenSpec is the score.