↓Skip to main content
  1. Posts/

Vibe coding vs spec-driven development: why OpenSpec matters for professional teams

·5 mins

AI changed the coding loop.

Now we can generate huge chunks of code in minutes. That sounds amazing until we need to review, integrate, and maintain what was generated.

This is exactly where the approach needs to change.

Vibe coding is not for professional software development, not because vibe coding is useless, but because once projects get real, speed without structure becomes expensive. This is where spec-driven development becomes necessary.

Why this matters #

AI can create faster than humans can validate.

That is the core problem.

In many sessions, AI can produce thousands of lines while I still need to answer basic questions:

  • What are we actually building?
  • What are the boundaries?
  • What assumptions is the model making?
  • How do these pieces fit with existing architecture?

If those answers are not explicit, generated code becomes a pile of “almost correct” fragments.

Vibe coding vs spec-driven development #

In simple terms:

  • Vibe coding: prompt fast, iterate fast, discover shape while generating.
  • Spec-driven development: define behavior and boundaries first, then generate against a concrete contract.

I have tried both in different moments.

Where vibe coding shines #

  • Early exploration.
  • Throwaway prototypes.
  • Looking for API ideas and alternative implementations.

Where vibe coding breaks down #

  • Cross-team features.
  • High-impact changes.
  • Flows with multiple integrations.
  • Any task where review quality matters.

When the generated output gets big, vibe coding often shifts complexity from “writing” to “understanding what was written”.

What spec-driven changes #

Spec-driven development forces the hard questions before code explosion:

  • Scope
  • Inputs/outputs
  • Constraints
  • Success criteria
  • Non-goals

That changes AI from “a fast typist” into “an implementation engine with a clear contract”.

Why OpenSpec specifically #

OpenSpec makes this process practical, not theoretical.

The key value is step-by-step pressure:

  1. Define exactly what we are building.
  2. Capture context and constraints.
  3. Validate acceptance criteria before implementation.
  4. Generate in controlled increments.
  5. Review each step against the spec.

That rhythm is critical in professional development because we are not only optimizing for speed, we are optimizing for correctness, maintainability, and team alignment.

A concrete OpenSpec workflow #

flowchart LR A[Propose change] B[Write proposal.md] C[Write delta specs] D[Write design.md] E[Write tasks.md] F[Apply implementation] G[Archive change] A --> B B --> C C --> D D --> E E --> F F --> G

I keep changes small and explicit, using the real OpenSpec artifacts.

After openspec init, OpenSpec works with two spaces:

openspec/
  specs/                        # Source of truth (current behavior)
    checkout/
      spec.md
  changes/                      # Proposed changes
    add-checkout-idempotency/
      proposal.md
      design.md
      tasks.md
      specs/
        checkout/
          spec.md               # Delta spec (ADDED/MODIFIED/REMOVED)

Example of a realistic delta spec:

# Delta for Checkout

## MODIFIED Requirements

### Requirement: Order submission
The system SHALL reject duplicate order submissions within 30 seconds.

#### Scenario: Duplicate submit blocked
- GIVEN a user submits checkout successfully
- WHEN the same request is retried within 30 seconds
- THEN the system returns the original order id
- AND no new order is created

Typical command flow in OpenSpec-aware assistants:

/opsx:propose add-checkout-idempotency
/opsx:apply
/opsx:archive

This is a development contract, not a runtime TypeScript type.

With this level of context, output quality improves and review cost drops.

What does this mean for real teams? #

OpenSpec helps in three practical ways:

  • Better handoff between engineers: everyone sees the same intent.
  • Better AI sessions: less random generation, more targeted output.
  • Better code review: reviewers validate against criteria, not guesswork.

In short: less ambiguity, less rework.

Also, documentation alone is not enough.

Some teams think that having lots of docs means they already have a spec-driven framework. They do not. Without a structured workflow, they still end up waiting on huge tasks that generate thousands of lines with no clear step-by-step validation.

That is exactly why OpenSpec matters: it gives a concrete workflow, not just documents.

Layering recommendation for AI-assisted features #

For advanced teams, I recommend spec artifacts per layer:

  • Domain spec: invariants and business rules.
  • Application spec: use cases and orchestration.
  • Infrastructure spec: adapters, APIs, persistence constraints.
  • Presentation spec: UI states and interaction expectations.

This avoids the common failure mode where AI generates cross-layer coupling in one pass.

Trade-offs and limitations #

Spec-driven development is not free.

  • You invest more upfront.
  • Poor specs still produce poor code.
  • Teams can over-spec and slow down unnecessarily.

The goal is not bureaucracy. The goal is controlled acceleration.

A good rule:

  • Low risk + short-lived work: vibe coding is often enough.
  • Medium/high risk + long-lived code: spec-driven wins.

Common mistakes with OpenSpec #

  • Writing abstract specs without measurable acceptance criteria.
  • Forgetting non-goals (scope creep starts immediately).
  • Trying to spec everything in one giant document.
  • Skipping iterative validation after each generated chunk.

If you want speed, shrink the spec unit and increase validation frequency.

Practical adoption plan #

If your team is currently pure vibe coding, do this:

  1. Start with one critical feature.
  2. Write a one-page OpenSpec before coding.
  3. Generate implementation in small chunks.
  4. Review each chunk against acceptance criteria.
  5. Capture misses and improve your next spec template.

You do not need a full process migration on day one.

Conclusions #

Vibe coding can help exploration, but it is not the right approach for professional software development by itself.

OpenSpec gives teams something simple and powerful: a way to move at AI speed without losing engineering control.

When AI can generate thousands of lines, the bottleneck is no longer typing. It is decision quality.

Spec-driven development improves that decision quality.

That is the difference between “fast demos” and “reliable software”.