Your AI Doesn't Know What You Want
(And Neither Do You)
Spec-Driven Development with OpenSpec
Agenda
- My painful story using AI without enough structure
- Where AI coding goes wrong and why context windows limit it
- What Spec-Driven Development (SDD) is
- Spec-Driven Development with OpenSpec
My Painful Story
- Changes scattered across multiple microservice repos + legacy monolith repo
- AI jumped straight to generating, no throughout exploration
- Long exhausting chat session with constantly steering back and forth.
- Wrong code. Wrong changes. Line-by-line review of nonsense.
- Performance dropped. Frustration rose.
- I started dreading the tool I was supposed to love.
Where Does It All Go Wrong?
- We are already vibe coding for serious work — we just don't call it that
- Our prompts are business-language: they say what the user want, not how it should be built
- AI explores the codebase — but guesses the technical detail we left out
- Vague intent → hallucinations → wrong class, wrong file, wrong assumption
Context Windows Limitation
What Is Spec-Driven Development (SDD)?
Create the specification artifact first — everything else is derived from it
The spec is the shared understanding between you and the AI
BDD, TDD, OpenAPI contract-first, ... share the same concept
The SDD Workflow
| Stage | What Happens |
|---|---|
| Spec | Define .md artifacts such as prd.md, research.md, design.md, tasks.md, ... |
| Implement | AI read Spec artifacts and implement within the Spec context |
| Validation | Verify implementation against the spec |
| Archive | Archive after implementation done |
Vibe Coding vs Spec-Driven
| Vibe Coding | Spec-Driven |
|---|---|
| Prompt → hope | Spec → high quality generated code |
| AI guesses scope | AI works inside defined scope |
| Session decays | Resume anywhere from the spec |
| Review code | Review intent |
| One long chaotic session | Small, scoped, well-defined changes |
The Intent Compiler
A compiler catches errors before your code runs. Spec catches misunderstandings before your AI codes.
- Spec stage → cheap to steer
- Implementation stage → expensive to steer
- Production → impossible to steer
Review the Spec
Always review the spec to ensure a shared understanding between you and your AI
- Catch Gaps early: Did we miss an edge case?
- Verify Design: Is this the right pattern?
- Check Scope: Too much or too little?
- Check Hallucination: Where does this come from?
SDD with OpenSpec
- OpenSpec is a meta prompt tool to instruct AI explore project context and generate Scoped Spec artifacts
- OpenSpec artifacts are well scoped, reviewable, and has browfield project as first-class support
| spec-kit | GSD | OpenSpec | |
|---|---|---|---|
| Artifact volume | High | Very high | Low |
| Human review checkpoints | Medium | Low | High |
| Noise level | High | Very high | Low |
Closing
Your AI knows what you want (and also you) if there is enough context
- The answer isn't a better prompt. It's a clearer understanding and better spec artifacts.
- SDD is ahead-of-time compilation for your intent.
- Apply SDD for implementing a feature then evaluate.
Thank You
If you have any questions, feel free to reach out on GitHub or scan the QR below.
| GitHub | Website |
|---|---|
 |
 |
 |
 |