Vibe coding has a ceiling

I write most of my code through AI agents. For quick scripts, brainstorming, and prototypes, I talk to the model, iterate on output, and ship. Vibe coding. It’s fast, it’s fun, and it works. I’m not here to tell you to stop.

But there’s a ceiling, and I hit it.

The symptoms

The project that broke my conversational workflow was this site. Multiple pages, a design system, a content schema, architecture decisions that carried across files. Every new session started the same way — re-explaining the tech stack, re-stating decisions I’d already made, watching the AI suggest patterns I’d explicitly rejected two conversations ago.

The symptoms are predictable:

• Context amnesia. Requirements live in chat history that expires. Next session, the AI starts from zero.
• Decision drift. You settled on REST over GraphQL last week. The AI doesn’t know that and proposes GraphQL.
• Inconsistency. File A follows one pattern, file B follows another, because they were generated in different conversations with different context.
• Relitigating. The AI keeps asking questions you’ve already answered, or worse, silently picks a different answer.

These aren’t prompting problems. You can’t fix them by writing better instructions. The issue is structural: the AI’s working memory is the context window, and context windows don’t persist.

The fix: specs, not vibes

The fix is externalizing your requirements into files the AI can read. Instead of describing what you want conversationally, you write it down as structured specifications. The AI executes against specs, not against your ability to re-explain the same thing for the fifth time.

I built a custom system for this — a .ai/ directory with product requirements, schemas, design tokens, and a set of slash commands covering the full dev lifecycle. Eight commands, from /x-feature for product planning to /x-verify for validation. It worked. The AI had persistent context, consistent constraints, and a repeatable workflow.

But it was bespoke. I maintained the commands, the skills, the templates. It was tied to Claude Code. And it was heavier than it needed to be.

OpenSpec

OpenSpec does this better.

It’s an open-source spec-driven development tool that works with 20+ AI assistants — Claude Code, Cursor, Copilot, Windsurf, Gemini CLI, and others. The philosophy is right: fluid not rigid, iterative not waterfall, built for brownfield not just greenfield.

The core workflow is three actions: propose, apply, archive.

Propose creates a change directory with a proposal (why), delta specs (what’s changing), a design document (how), and a task list (the work). Apply implements the tasks against those specs. Archive merges the completed specs into the main spec directory and preserves the change for history.

That’s it. No phase gates, no heavyweight process, no JIRA tickets. You describe the change, the AI implements it against explicit requirements, and you archive the result. The specs accumulate over time, building a source of truth that grows with the project.

What makes it click

Two things stand out.

Delta specs. Instead of rewriting entire specification documents, you describe what’s changing — what’s added, modified, or removed. This is brownfield-native. Most real work is modifying existing systems, not building from scratch. Delta specs let you scope changes tightly without touching unrelated requirements.

Separation of state. Current specs live in openspec/specs/. Proposed changes live in openspec/changes/<name>/. Multiple changes can coexist without conflicts. When a change is done, its deltas merge into the main specs. This is version control for requirements — a concept that’s been missing from most AI-assisted workflows.

When to use what

This isn’t a binary choice. Vibe coding and spec-driven development serve different purposes.

Vibe code when you’re exploring, prototyping, writing one-off scripts, or working on something that fits in a single session. The cost of context loss is zero because there’s no next session.

Write specs when the project outlives a single conversation. When multiple files need to stay consistent. When you’re making decisions that future sessions need to respect. When the cost of the AI guessing wrong is higher than the cost of writing it down.

The skill isn’t picking one approach. It’s recognizing when you’ve hit the ceiling and switching.

#

Related: The prompt stack

Specification engineering is the top layer of the prompt stack — the discipline of writing complete, structured documents that agents execute against autonomously.