SDD x VibeCoding: Where Structure Meets Intuition

What if you could describe your vision in natural language AND have it implemented with the rigor of specification-driven development?

This is the promise of combining Vibe Coding with SDD (Specification-Driven Development).

The Two Extremes

Pure Vibe Coding

You: "Make me a task management app. The vibe should be
minimal and zen, like a paper notebook."

Claude: [Creates the app]

You: "Add subtasks"

Claude: [Adds subtasks]

You: "Actually, make them nested infinitely"

Claude: [Refactors for infinite nesting]

You: "And add due dates... and tags... and..."

What happens: Fast start, but scope creep. No documentation. Hard to maintain. Six months later, you don’t remember why anything works the way it does.

Pure SDD

You: /speckit-specify Task Management Feature

[Writes 5-page specification]
[Clarifies 12 ambiguities]
[Creates technical plan]
[Defines 20 tasks]
[Finally starts coding]

What happens: Rigorous and traceable, but time-consuming upfront. Sometimes you just want to explore an idea, not write a thesis about it.

The Sweet Spot: VibeSDD

VibeSDD combines the creative freedom of vibe coding with the structural rigor of SDD:

┌─────────────────────────────────────────────────────┐
│                    VibeSDD Flow                     │
│                                                     │
│   ┌──────────┐                                      │
│   │  VIBE    │  Describe freely in natural language │
│   │  INPUT   │  "I want X that feels like Y"        │
│   └────┬─────┘                                      │
│        │                                            │
│        ▼                                            │
│   ┌──────────┐                                      │
│   │  SPEC    │  Claude structures into spec format  │
│   │  CAPTURE │  You review and refine               │
│   └────┬─────┘                                      │
│        │                                            │
│        ▼                                            │
│   ┌──────────┐                                      │
│   │  VIBE    │  Iterate vibes on the spec           │
│   │  REFINE  │  "More of this, less of that"        │
│   └────┬─────┘                                      │
│        │                                            │
│        ▼                                            │
│   ┌──────────┐                                      │
│   │  SDD     │  Structured implementation           │
│   │  EXECUTE │  Full traceability                   │
│   └──────────┘                                      │
│                                                     │
└─────────────────────────────────────────────────────┘

Why This Works

Vibe Coding Captures Intent

When you say “Make it feel like Notion but simpler,” you’re conveying:

• A mental model (blocks, flexibility)
• An aesthetic (clean, modern)
• A user experience (fast, intuitive)
• A complexity level (simpler = fewer features)

This is valuable information that would take pages to specify formally.

SDD Provides Guardrails

Specifications prevent:

• Scope creep (“and add one more thing…”)
• Forgotten requirements (“wait, we needed that?”)
• Implementation drift (“this isn’t what I meant”)
• Documentation debt (“how does this work again?”)

Together: Creative Rigor

Vibe Coding	+	SDD	=	VibeSDD
Fast exploration		Structured output		Rapid specification
Intuitive input		Clear requirements		Vision to spec
Iteration-friendly		Traceable changes		Controlled evolution

The VibeSDD Workflow

Phase 1: Vibe Specification

Instead of writing formal specs, describe your vision:

## The Vibe

"I want to build an expense tracker for freelancers.
It should feel like a personal finance journal, not
a corporate accounting tool.

Key feelings:
- Quick to add expenses (under 5 seconds)
- Satisfying to categorize (maybe swipe?)
- Clear monthly overview (not overwhelming)
- Feels trustworthy with money data

Think: Minimal like Things 3, colorful like Notion,
but for money."

Claude captures this into specification structure:

# Specification: Expense Tracker for Freelancers

## Overview
A personal expense tracking application designed for
freelancers, emphasizing speed, simplicity, and a
journaling-like experience.

## User Stories
- As a freelancer, I want to add expenses quickly so
  I don't interrupt my workflow
- As a freelancer, I want to see my monthly spending
  clearly so I can manage my budget
- As a freelancer, I want categorization to feel
  natural so I actually use it

## UX Requirements
- Expense entry: < 5 seconds
- Interaction style: Gesture-friendly (swipe to categorize)
- Visual density: Low (breathing room)
- Data display: Monthly-focused, not transactional

## Design References
- Things 3: Minimalism, white space, subtle animations
- Notion: Colorful accents, playful without being childish
- Emphasis: "Journal" not "Ledger"

## [NEEDS CLARIFICATION]
- Currency support: Single or multi?
- Data storage: Local-first or cloud-synced?
- Export formats: PDF? CSV? Tax software?

Phase 2: Vibe Refinement

Now iterate on the spec using vibe language:

You: "The categorization section feels too corporate.
More like choosing a mood, less like filing taxes."

Claude: Updates spec...

## Category System
- Mood-based categorization: "Business Stuff",
  "Life Things", "Creative Work", "The Boring Stuff"
- Custom emojis per category
- Color-coded, not icon-coded
- No hierarchies—flat and simple

You: "The monthly overview—I don't want charts.
I want something I'd actually look at. Like a
month in review, not a dashboard."

Claude: Updates spec...

## Monthly Overview
- Narrative format: "March 2026: You spent..."
- Highlight surprising changes from last month
- Show trends in plain language, not percentages
- One "insight" per month, not twenty metrics

Phase 3: Vibe-Check Before Implementation

Before coding, do a vibe check:

You: "Read back the spec. Does it still feel right?"

Claude: Here's the essence of what we're building...

"A personal expense journal for freelancers.
Quick to add (< 5 seconds), satisfying to categorize
(mood-based, gesture-friendly), and provides a
monthly narrative rather than corporate dashboards.
Feels like Things 3 meets Notion, but for money."

Does this match your vision?

If it doesn’t, adjust. If it does, proceed.

Phase 4: Structured Implementation

Now Claude implements with full SDD rigor:

/speckit-implement SPEC-001

Claude:
→ Creates technical plan from spec
→ Breaks into traceable tasks
→ Implements with spec references
→ Maintains documentation

The code references the spec:

/**
 * Quick Expense Entry Component
 *
 * @spec SPEC-001
 * @requirement "Expense entry < 5 seconds"
 * @ux "Quick to add expenses, don't interrupt workflow"
 */
export function QuickExpenseInput() {
  // Optimized for speed per UX Requirements
  // ...
}

VibeSDD in Practice

Example: Building a Habit Tracker

Traditional Approach:

/speckit-specify Habit Tracking Feature

[30 minutes writing formal requirements]

VibeSDD Approach:

You: "I want a habit tracker that doesn't make me feel
bad when I miss days. Most habit apps feel punishing.
This should feel like a gentle friend reminding me to
take care of myself.

Inspiration: Headspace's calm vibe, but for habits.
Definitely not Streaks' aggressive chain-counting."

Claude captures:

# Specification: Compassionate Habit Tracker

## Core Philosophy
Non-punitive tracking. Missing days is expected and
okay. Focus on patterns over streaks.

## UX Principles
- No broken chains or lost streaks
- No red X's or failure indicators
- Show "attempted days" not "missed days"
- Celebrate any progress, however small

## Visual Language
- Soft colors, rounded shapes
- Nature metaphors (growth, seasons)
- Words: "rest day" not "skipped day"
- No numbers on homepage—just vibes

## Anti-Requirements (What to Avoid)
- NO streak counters
- NO gamification that punishes
- NO comparative features
- NO notifications that shame

You refine:

You: "The 'no numbers' thing—I still want to see
progress somehow. Just not aggressively."

Claude: Updates spec...

## Progress Visualization
- Heatmap with soft gradients (not stark binary)
- "Seasons" view: How did Spring look vs Winter?
- Optional stats, hidden by default
- Language: "You showed up X times" not "X day streak"

Then implement with full traceability.

The VibeSDD Prompting Guide

Starting a VibeSDD Project

## High-Vibe Spec Starters

"I want to build [thing] that feels like [reference].
The key feeling is [emotion]. It's for [audience]."

"Think [inspiration A] meets [inspiration B], but
focused on [specific aspect]."

"Most [category] apps feel [negative].
This should feel [positive] instead."

Refining Specifications

## Vibe Refinement Phrases

"This section feels too [adjective]. Make it more [adjective]."
"When I imagine using this, I feel [emotion]. I want to feel [emotion] instead."
"The tone of [section] should match [reference]."
"This captures the what but not the why. The why is [reason]."

Checking Alignment

## Vibe Check Questions

"Summarize the spec in 3 sentences. Does it still resonate?"
"If this existed, would I be excited to use it? Why or why not?"
"What would make a user smile when using this?"
"What would feel off about this in 6 months?"

When to Use VibeSDD

Perfect For

Scenario	Why VibeSDD Works
New product exploration	Vibe first, refine, then build right
UX-critical features	Feelings captured in spec
Founder-led projects	Vision-to-execution without losing soul
Redesigns	Capture desired feel, not just features

Less Ideal For

Scenario	Better Approach
Pure infrastructure	Traditional SDD
API integrations	Standard specs
Compliance features	Formal requirements
Bug fixes	Just fix it

Common Mistakes

Mistake 1: Vibing Without Capturing

❌ Bad:
Session 1: "Make it feel like Notion"
Session 2: "Why isn't it like Notion?"

✅ Better:
Session 1: "Make it feel like Notion" → Captured in spec
Session 2: [Reads spec] Continue implementing Notion-like feel

Always capture vibes into specs. Vibes fade; specs persist.

Mistake 2: Over-Specifying Vibes

❌ Bad:
"The button should be exactly 44px, with #3B82F6
background, 4px border radius, and 'Inter' font
at 14px with 500 weight..."

✅ Better:
"The buttons should feel friendly and clickable.
Not corporate, not toy-like. Goldilocks zone."

Specify feelings, not pixels. Claude knows CSS.

Mistake 3: Skipping the Vibe-Check

❌ Bad:
[Write spec] → [Implement immediately]

✅ Better:
[Write spec] → [Read back] → [Feel if it's right] → [Implement]

Always pause to vibe-check. 5 minutes now saves hours later.

The VibeSDD Cheat Sheet

## VibeSDD Quick Reference

### Starting a Feature
1. Describe the vibe (2-3 paragraphs, feelings and references)
2. Let Claude structure into spec
3. Vibe-refine sections that feel off
4. Vibe-check the whole spec
5. SDD implement with traceability

### Vibe Vocabulary
- Feelings: calm, energetic, playful, serious, trustworthy
- Comparisons: "like X but Y", "X meets Y"
- Negations: "NOT like X", "avoid Y feeling"
- Directions: more/less, simpler/richer, warmer/cooler

### Spec Sections to Vibe
- User Stories → "As someone who feels..."
- UX Requirements → "It should feel..."
- Design References → "Like X meets Y"
- Anti-Requirements → "NOT like..."

### Quality Checks
- Would I be excited to use this?
- Can I explain the soul in one sentence?
- Does reading the spec give me the feeling?

Implementing VibeSDD with Skills & Agents

Community Pattern Notice: The following skills and agents are from the Claude Bootstrap Kit, a community-developed extension for Claude Code. They are not official Anthropic features.

VibeSDD isn’t just a concept—it’s a workflow you can execute today using Claude Code’s custom skills and agents.

The VibeSDD Skill Pipeline

┌─────────────────────────────────────────────────────────────────┐
│                    VibeSDD Skill Pipeline                       │
│                                                                 │
│   VIBE INPUT          STRUCTURED CAPTURE        IMPLEMENTATION  │
│   ───────────         ──────────────────        ──────────────  │
│                                                                 │
│   Your natural    →   /spec-writer         →   /tech-planner   │
│   language vibe       (captures to spec)       (architecture)   │
│                            │                        │           │
│                            ▼                        ▼           │
│                       /spec-clarifier         /task-decomposer  │
│                       (resolves [?])          (breaks tasks)    │
│                            │                        │           │
│                            ▼                        ▼           │
│                       specification-          /speckit-implement│
│                       validator agent         (TDD execution)   │
│                       (quality check)                           │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Phase 1: Vibe → Specification

Use /spec-writer to transform your vibe into a structured specification:

You: "I want to build an expense tracker for freelancers.
It should feel like a personal finance journal, not
a corporate accounting tool. Quick to add, satisfying
to categorize, minimal but trustworthy."

/spec-writer Expense Tracker for Freelancers

The spec-writer skill:

• Structures your vibe into user stories
• Extracts acceptance criteria
• Identifies UX requirements from feelings
• Marks ambiguities with [NEEDS CLARIFICATION]
• Keeps it pure product—no technical details yet

Phase 2: Clarify Vibes

Use /spec-clarifier to resolve the [NEEDS CLARIFICATION] markers:

/spec-clarifier SPEC-001

The spec-clarifier skill:

• Scans for all ambiguous sections
• Generates structured questions with options
• Uses AskUserQuestion for interactive decisions
• Updates the spec with your choices
• Documents decision rationale

Example interaction:

Claude: Found 3 items needing clarification:

1. Currency support?
   a) Single currency (simpler) [Recommended]
   b) Multi-currency (complex)

   Your vibe said "minimal"—single currency aligns better.

2. Data storage?
   a) Local-first (private, offline)
   b) Cloud-synced (accessible anywhere)

   Your vibe said "trustworthy"—which feels more trustworthy to you?

You: Single currency, and local-first feels more trustworthy for money data.

Claude: [Updates spec with decisions and rationale]

Phase 3: Validate the Vibe-Spec

Use the specification-validator agent to ensure quality:

Claude uses Task tool with specification-validator agent

The validator checks:

• Structure completeness (all required sections)
• SDD compliance (no premature technical details)
• Clarity score (remaining [NEEDS CLARIFICATION] count)
• Vibe consistency (does it still match the original feeling?)

Scoring:

• 90-100: Excellent, ready for implementation
• 75-89: Good, minor refinements needed
• 60-74: Needs work, missing sections
• <60: Fail, fundamental issues

Phase 4: Technical Planning

Once the spec is validated, use /tech-planner:

/tech-planner SPEC-001

The tech-planner skill:

• Analyzes the specification thoroughly
• Explores current codebase architecture
• Generates 2-3 implementation approaches
• Evaluates trade-offs (complexity, performance, risk)
• Outputs a detailed technical plan

The vibe is preserved:

# Technical Plan: Expense Tracker

## Architecture Decision

Based on the spec's emphasis on "quick" (< 5 seconds) and
"trustworthy" (local-first), we recommend:

- **Approach A: SQLite + React Native** ✓ Recommended
  - Aligns with "minimal" vibe (simple stack)
  - Supports "quick" via local-first architecture
  - Enables "trustworthy" via on-device encryption

Phase 5: Task Decomposition

Use /task-decomposer to break the plan into executable tasks:

/task-decomposer SPEC-001

The task-decomposer skill:

• Creates sized tasks with dependencies
• Links each task to spec requirements
• Estimates relative complexity
• Generates a TodoWrite-compatible task list

Output:

## Implementation Tasks

| ID | Task | Spec Ref | Size |
|----|------|----------|------|
| T1 | Create SQLite schema | UX-001 | S |
| T2 | Build expense input component | UX-002 | M |
| T3 | Implement swipe categorization | UX-003 | M |
| T4 | Create monthly narrative view | UX-004 | L |
| T5 | Add soft gradient heatmap | UX-005 | S |

Phase 6: TDD Implementation

Use /speckit-implement to execute with full traceability:

/speckit-implement SPEC-001

The speckit-implement skill:

• Follows strict Red-Green-Refactor TDD cycle
• References spec in every code file
• Checks 9-Article Constitutional Compliance
• Generates implementation reports

Constitutional Compliance (9 Principles):

1. Library-First - Reusable logic in libraries
2. CLI Interface - Features accessible via CLI
3. Test-First - Tests before implementation
4. Research-Driven - Evidence-based decisions
5. Specification Consistency - Match specs exactly
6. Simplicity - Choose simplest solution
7. Anti-Abstraction - No premature abstraction
8. Minimal Scope - Only what’s specified
9. Integration-First - Prioritize integration tests

The Complete VibeSDD Command Sequence

# 1. Transform vibe to specification
/spec-writer "Your vibe description here"

# 2. Clarify ambiguities interactively
/spec-clarifier SPEC-001

# 3. Validate specification quality
# (Auto-triggered or use specification-validator agent)

# 4. Create technical plan
/tech-planner SPEC-001

# 5. Break into tasks
/task-decomposer SPEC-001

# 6. Implement with TDD
/speckit-implement SPEC-001

# Or run the full pipeline:
/speckit "Your vibe description here"

Agent Orchestration for Complex Vibes

For complex features, use multiple agents in parallel:

Terminal 1: spec-writer agent
            → Captures vibe into specification

Terminal 2: tech-planner agent
            → Explores architecture options

Terminal 3: specification-validator agent
            → Validates SDD compliance

Terminal 4: implementer agent
            → Executes with full traceability

Multi-CLI delegation:

Large context analysis  →  Gemini CLI (1M tokens)
Bulk code formatting    →  Codex CLI (efficiency)
Interactive decisions   →  Claude CLI (conversation)

CLAUDE.md Configuration for VibeSDD

Add this to your project’s CLAUDE.md:

## VibeSDD Workflow

### Vibe Capture
- Always use /spec-writer for new features
- Mark vibes explicitly in specs: "Vibe: [description]"
- Include design references and anti-patterns

### Specification Standards
- Pure product specs (no technical details until tech-planner)
- All ambiguities marked with [NEEDS CLARIFICATION]
- Mandatory vibe-check before implementation

### Implementation Rules
- Constitutional compliance required
- TDD for all new features
- Spec references in code comments

The Philosophy: Why VibeSDD Matters

Software development has always had a tension:

Artists want to express and create freely. Engineers want to build correctly and maintainably.

VibeSDD resolves this by recognizing:

1. Vibes are requirements too. “It should feel X” is as valid as “it should do Y.”

2. Structure amplifies creativity. Specs aren’t constraints; they’re creative commitments.

3. AI bridges the gap. Claude can translate feelings into formal specifications.

The result: software that works correctly AND feels right.

---

Key Takeaways

1. Vibe coding captures intent that formal specs often miss
2. SDD provides the guardrails that vibe coding lacks
3. VibeSDD = creative freedom + systematic rigor
4. Always capture vibes into specifications
5. Vibe-check before implementing

Start with feeling. End with rigor. Build software with soul.

---

Related: Vibe Coding Guide, SpecKit Guide, Director Mode