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.
"A wise man builds his house on rock, not on sand." — A universal proverb that also applies to software engineering
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.
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:
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:
The conversation context window is limited. AI doesn't remember decisions made 3 days ago.
Why was the architecture designed that way? Lost when the chat session is closed.
Code grows beyond both human cognitive capacity AND the AI's context window simultaneously.
Adding new features breaks old ones because there's no system mapping.
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.
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".
graph LR
subgraph VC["❌ Vibe Coding"]
A["Chat with AI"] --> B["AI writes code"]
B --> C["Check, wrong"]
C --> A
end
subgraph SDD["✅ Spec-Driven Dev"]
D["Write specification"] --> E["Review & validate"]
E --> F["AI writes code per spec"]
F --> G["Archive & update spec"]
end
style VC fill:#450a0a,color:#fca5a5
style SDD fill:#052e16,color:#86efacAnd at the forefront of this SDD movement stands a platform called 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.
| Property | Type | Description |
|---|---|---|
| Core Philosophy | Design Philosophy | Brownfield-first — optimized for projects that are ALREADY running, not new projects from scratch |
| Technology | Tech Stack | TypeScript (98.7% codebase), distributed via CLI (npm/pnpm/yarn/bun) |
| Compatibility | Integration | Agnostic — supports 20+ AI agents: Claude Code, Cursor, Codex, Windsurf, Gemini CLI, etc. |
| Core Principle | Core Principle | Specifications are the source of truth, NOT code. Code can be replaced, specs are maintained. |
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.
In the 1990s, Charles Simonyi from Microsoft had a vision: domain expert intent should be the primary artifact, not code. Code is just a "side effect" of that intent.
The problem? Back then there was no technology that could translate natural language intent into code. Now there is — it's called LLM.
OpenSpec revives this vision: Markdown specifications are not just passive documentation, but executable representations of intent for AI.
When the cost of writing code becomes cheaper (because of AI), the source of truth automatically shifts UPWARD — from code to functional intent.
Prompt Engineering is tactical — focused on one instruction, one iteration. Like texting a contractor: "Build a room, okay."
Context Engineering is strategic — building a long-term reasoning landscape. Like handing over a complete playbook: building standards, blueprints, guardrails, and success criteria.
OpenSpec forces developers to break their thinking into manageable blocks:
The result? Prompts to AI become very simple, and the output shifts from "creative guesses" to "predictable algorithmic output".
In the Agile era, requirements documentation was often minimized. "Working software over comprehensive documentation," says the Agile manifesto.
But AI reverses this! LLMs need unambiguous instructions and strict hierarchical boundaries. Without them, AI will fill the gaps with its own assumptions — also known as hallucinations.
OpenSpec brings back the discipline of Requirements Engineering: every intent is articulated specifically, reviewed by humans, and validated by machine before AI is allowed to write code.
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 effectchanges/ = Scratch paper — where new ideas are tested before entering the official bookAnalogy: Like a constitution — the official document currently in effect.
Analogy: Like a bill (draft law) — a proposal that hasn't been enacted yet.
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.
The entire OpenSpec development cycle runs on just three commands. Like the Design → Build → Archive cycle:
/opsx:propose — Design FirstYou describe what you want in everyday language. AI then:
changes/ folder:| Property | Type | Description |
|---|---|---|
| proposal.md | Justification | Why is this change needed? What's the impact on other modules? |
| specs/ | Spec Delta | Spec delta — what changes functionally |
| design.md | Technical Design | Technical decisions: what technology, what patterns, what logic paths |
| tasks.md | Task List | List of atomic and deterministic implementation tasks |
Analogy: Like an architect drawing the blueprint, calculating materials, and creating a work schedule — before the contractor starts drilling.
/opsx:apply — Now BuildAfter the human approves the proposal, AI starts implementation:
tasks.mddesign.mdAnalogy: 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 UpAfter implementation and testing are complete:
archive/ with a timestampspecs/ (source of truth)Analogy: After the house is built, the architectural blueprint is updated and stored in a vault. Scratch paper is thrown away. Clean.
graph LR
A["🎨 Propose"] -->|"Review & Approve"| B["🔨 Apply"]
B -->|"Test & Verify"| C["📦 Archive"]
C -->|"Next cycle"| A
style A fill:#7c3aed,color:#fff
style B fill:#059669,color:#fff
style C fill:#d97706,color:#000The 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:
What is the goal of this project? AI must not make decisions that deviate from the goals.
TypeScript? Go? React? AI knows its technology boundaries and must not suddenly use another framework.
Naming convention, folder structure, style guide — AI must follow existing standards.
Unit test mandatory? E2E tests for critical features? AI knows what needs to be tested.
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.
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.
OpenSpec has strict rules about how specs are written. The goal: so that AI (and humans) don't misinterpret.
OpenSpec adopts the IETF RFC 2119 standard — the standard commonly used for writing global internet specifications:
| Property | Type | Description |
|---|---|---|
| MUST / SHALL | Mandatory | Absolutely mandatory. Cannot be compromised. Example: 'The system MUST validate JWT tokens' |
| SHOULD | Recommended | Highly recommended, but there are valid exceptions. Example: 'The response SHOULD be cached for 5 minutes' |
| MAY | Optional | Truly optional. Example: 'Users MAY enable email notifications' |
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).
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 "[email protected]"
- 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.
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 VerificationWhere does OpenSpec stand among other SDD platforms?
| 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 |
GitHub Spec Kit forces 4 super-rigid hierarchical phases: specify → plan → tasks → implement. Everything must be completed before a single line of code is written.
The problem? Markdown documents balloon, reviews can take hours. For complex legacy projects, this is overkill.
OpenSpec chooses an incremental approach — only track what changes (delta), with 3 simple commands. Lighter, more adaptable.
Analogy: Spec Kit is like writing a full thesis before starting research. OpenSpec is more like a daily journal — write what changed, validate immediately.
Amazon Kiro has tremendous power: deep file system access, SSH connections, MCP integration — all wrapped in a powerful IDE.
But? You're locked into the AWS ecosystem and exclusively Claude models. Switch to Gemini? Can't. Use outside VS Code? Can't.
OpenSpec works alongside your IDE of choice, supports 20+ AI agents, and doesn't require special infrastructure.
Analogy: Kiro is a showroom car — fast and luxurious, but service must be done at the official dealer. OpenSpec is an open standard car — any mechanic can handle it.
Similar names, but very different functions:
Analogy: OpenAPI is the specification for USB-C connector dimensions — port shape, voltage, pin assignment. OpenSpec is the instruction manual for a robot assembling USB-C in a factory — how the robot should work, step by step.
Both can synergize: OpenSpec can guide AI to generate perfectly validated OpenAPI files.
No approach is perfect. Here are the sharpest criticisms of SDD and OpenSpec:
Critics say SDD is 'Waterfall in new clothes.' Early documentation obsession risks killing Agile adaptability.
A pile of spec documents does NOT automatically mean quality code. It could be a false sense of security.
If specs aren't updated when mid-flight improvisation happens, stale specs are more DANGEROUS than having no specs at all.
Too little structure = chaos (vibe coding). Too much structure = gridlock (waterfall). Where's the sweet spot?
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).
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.
