The Hybrid Workflow: Vibe to Spec to Ship

The False Choice

Most discussions about vibe coding and spec-driven development frame them as opposites: you either vibe code everything or you specify everything. This framing misses how skilled developers actually work.

The best developers in the AI era don't choose between approaches — they flow between them based on the phase of work. They use vibe coding for exploration, specifications for definition, and structured prompting for production implementation. This lesson teaches the workflow that connects all three.

The 3-Phase Hybrid Workflow

Phase 1: Vibe (Explore) — 15-30 minutes

Use vibe coding to explore the solution space. Open Bolt.new, v0, or your AI IDE and rapidly generate two or three approaches to the feature. Don't overthink — let the AI surprise you. Try different layouts, different interaction patterns, different approaches.

The goal is NOT production code. The goal is understanding what's possible and what feels right. Prototypes are thinking tools.

What you produce: A rough prototype or two to three screenshots of approaches you like. Notes on what worked and what missed.

Tools: Bolt.new, v0.dev, Cursor in rapid-iteration mode.

The key insight: Vibing first makes specifying easier. When you write a spec from imagination, you have to invent every detail. When you write a spec from a prototype you've seen, you're codifying something concrete. The spec almost writes itself.

Phase 2: Spec (Define) — 15-30 minutes

Now that you know what you want — from Phase 1 — write the specification. You've seen what the AI can do and identified the approach you like. Turning it into a spec is 10x easier than writing one from scratch.

Write:

• User story with acceptance criteria (Lesson 3.5 format)
• List of components and screens (informed by what you saw in Phase 1)
• Edge cases (now informed by what the AI missed in Phase 1)
• Wireframe or screenshot reference from Phase 1
• Technical constraints and stack requirements
• Test scenarios

The Phase 1 → Phase 2 advantage: In pure spec-driven development, you enumerate edge cases from imagination and often miss some. When you specify after vibing, you saw the AI generate something and noticed where it failed. Those failures become edge cases in your spec. Your spec is grounded in reality rather than imagination.

Format: Spec Package (Lesson 3.5) for most features. Full SDD pipeline (Module 4) for complex production work.

What you produce: A structured specification document.

Phase 3: Ship (Build) — 30-60 minutes

Feed the specification to your AI coding tool. Because the spec is informed by Phase 1 exploration, it is realistic and grounded — not a wishlist written in the abstract. The AI generates high-quality output on the first pass.

Review, test against acceptance criteria, refine once or twice, and ship.

Tools: Claude Code for full SDD integration, Cursor for IDE-based work, Bolt.new for continued full-stack development.

What you produce: Production-quality code with documented edge case coverage and a spec for future maintenance.

---

Complete Example: Notification System

Feature: "Add a notification system to the SaaS app"

Phase 1 — Vibe (20 minutes)

Open Bolt.new: "Build a notification bell component with a dropdown showing recent notifications. Use shadcn/ui and Tailwind."

Iterate:

• "Add a badge count on the bell"
• "Add a mark-all-as-read button"
• "Make it look more like Linear's notifications"

Take a screenshot of the version you like. Note what the AI handled well (the visual design, the dropdown animation) and what it missed (no empty state, no real-time updates, no read/unread distinction).

Phase 2 — Spec (20 minutes)

Write the spec informed by Phase 1:

User story: "As a user, I want to see a notification bell with unread count so that I know when there are updates requiring my attention."

Acceptance criteria:

1. Given I have unread notifications, when I view any page, then a red badge shows the unread count (up to 99, shows "99+" above that)
2. Given the dropdown is open, when I click a notification, then it is marked as read and I am navigated to the relevant page
3. Given I click "Mark all as read," then all notifications are marked as read and the badge disappears
4. Given I have no notifications, when I open the dropdown, then I see "No new notifications"
5. Given a notification arrives while the dropdown is open, then it appears at the top without requiring a page refresh

Edge cases (from Phase 1 failures): empty state, real-time updates, read/unread visual distinction, 100+ notifications (pagination).

Technical constraints: shadcn/ui Popover, React Query for state, /api/notifications endpoint, Prisma Notification model.

Phase 3 — Ship (30 minutes)

Feed the spec to Claude Code or Cursor. The AI generates a complete notification system handling every specified case on the first pass.

Review against acceptance criteria. One minor fix: the timestamp format. Write tests — the Given/When/Then criteria map directly to test cases.

Total time: ~70 minutes for production-quality notifications with tests and documentation.

Compare to pure vibe: 2+ hours of iteration, unknown edge case coverage, no documentation.

---

Adapting the Workflow to Team Size

Solo developer: All three phases yourself. The spec is short (bullet points + Phase 1 screenshots) because you're the only audience.

Small team (2-5): Phase 1 solo or in a pair. Phase 2 as a team review. Phase 3 individual implementation against the spec. The spec is the alignment mechanism.

Larger team: Phase 1 during sprint planning (explore approaches together). Phase 2 formal spec review with stakeholders. Phase 3 assigned to developers with the spec as the contract.

When to Skip Phases

Skip Phase 1 (go straight to spec) when: you already know exactly what you want, you've built similar features before, or requirements come from clearly defined business constraints.

Skip Phase 2 (go straight from vibe to ship) when: it's a personal tool, a throwaway prototype, or a simple UI change with no edge cases.

Never skip Phase 3: If code ships to users, it gets built properly.

Key Takeaways

• The hybrid workflow captures vibe coding's exploration speed and SDD's production quality — you don't have to choose
• Phase 1 (Vibe): explore the solution space, produce rough prototypes, understand what's possible
• Phase 2 (Spec): codify what you learned, write acceptance criteria informed by Phase 1 failures, produce the spec
• Phase 3 (Ship): implement against the spec, producing production-quality code
• Vibing before specifying makes spec-writing faster and more accurate — Phase 1 failure modes become Phase 2 edge cases
• The total time is roughly the same as pure vibe coding but produces dramatically better output