Blueprint

Blueprint for efficient vibecoding

Eighteen months ago, the hard part of shipping software was writing the code. Today, an AI assistant can produce a working feature in roughly the time it takes to describe it. That shift is real, and most leaders have felt it: things that used to take a sprint now take an afternoon.

But anyone who has actually run an AI-assisted team has also felt the new problem. The code arrives fast, and it’s frequently not the thing you asked for. A founder approves a direction in a Tuesday standup. Two weeks later the feature exists, works, demos cleanly, and is subtly wrong: it solves a slightly different problem than the one everyone thought they’d agreed on. Nobody can quite say where it went sideways, because the actual decision (the “what we’re building and why”) never lived anywhere durable. It lived in a chat window that has long since scrolled into oblivion.

This is the quiet tax on AI coding. The bottleneck didn’t disappear; it moved. It moved from writing to agreeing. And agreeing is now the expensive part.

The failure mode no one priced in

Here’s the uncomfortable mechanic. When a human engineer received a vague instruction, they pushed back. They asked questions. They held the intent in their head and noticed when something didn’t add up. An AI assistant, by default, does none of that reliably. It is extraordinarily good at executing — including at faithfully executing your ambiguity. Give it a fuzzy prompt and it will confidently build a fuzzy thing, and it will do it quickly enough that the mistake is already three layers deep before anyone reviews it.

The cost shows up as rework, which is the most expensive kind of work because you pay for it twice. It shows up as misalignment between what a customer was promised and what got built. And it shows up as institutional amnesia: six months on, no one — human or machine — can reconstruct why a feature behaves the way it does, because the reasoning was never written down. When the person who improvised it leaves, the knowledge leaves with them.

The fix is boring, and that’s the point

The emerging answer has an unglamorous name: spec-driven development. The idea is almost aggressively simple. Before any code gets written, the human and the AI agree — in writing — on what’s being built and why. That written agreement, the spec, becomes the source of truth. Not the chat history. Not someone’s memory of the meeting. A document.

If that sounds like going backwards — like the heavyweight requirements binders of the 1990s — it isn’t, and the difference matters. Old-school specs were written once, by hand, and were obsolete the day coding started. A modern spec is lightweight, lives right next to the code, and is the thing the AI actually reads to do its work. It’s less like a 200-page requirements document and more like a contract: a short, clear statement of what both parties are committing to, that you can point at when there’s a disagreement.

This has quietly become a category, not a fringe idea. GitHub has shipped a tool for it; AWS built spec-driven development into its Kiro environment. OpenSpec is one of the most-adopted open-source options — it’s free, it works with the AI coding assistants teams already use rather than locking you into a proprietary environment, and its rapid uptake suggests it’s solving a problem people genuinely have. I’ll use it as the concrete example, but the principle is bigger than any single tool.

How OpenSpec works

OpenSpec is an open-source tool built for exactly this gap. It’s free, MIT-licensed, and — importantly — tool-agnostic: it works with the AI coding assistants teams already use, including Claude Code, Cursor, and GitHub Copilot, rather than locking you into a proprietary IDE. Mechanically it’s lightweight. Specs and proposed changes are plain Markdown files that live inside your code repository, so they’re versioned in git and reviewed in pull requests like everything else your team ships.

The workflow is a loop with three beats:

  1. Propose. You describe a change — “add SSO,” “let users export their data.” Instead of jumping to code, the AI generates a structured proposal: the rationale, a technical design, a task breakdown, and a precise delta spelling out exactly which requirements will be added, modified, or removed. A human reviews and refines this before any code is written. The decision moves to the cheap stage.
  2. Apply. With the plan agreed, the AI implements against it. The target was defined up front, so there’s far less room for drift.
  3. Archive. The change folds into the project’s living specification — the durable source of truth. The next change begins by reading it. Knowledge compounds instead of evaporating.

Two details matter in practice. First, it’s built for brownfield, not just greenfield: you can point it at an existing codebase and have it reverse-generate specs describing what the system currently does — a fast way to document something nobody fully understands before you change it. Second, it’s deliberately fluid rather than gated; you can revise any artifact at any time. That’s what separates it from heavier approaches like GitHub’s Spec Kit (more rigid phase gates, more setup) and AWS’s Kiro (powerful, but tied to its own IDE and model choices).

Why this is a business decision, not a developer preference

It’s tempting to file this under “engineering process” and move on. Don’t. The benefits land squarely on the business. Alignment before spend. You catch the “we’re building the wrong thing” conversation while it costs a five-minute edit, not a two-week rebuild. A paper trail. Every meaningful change has a reviewable record of intent — useful for accountability, for audits, and for the inevitable “who decided this, and why?” six months later.

  • Durable knowledge. The reasoning behind your product survives staff turnover and the end of any given chat session. Your system becomes legible to the next person who joins — and to the next AI you point at it.
  • Predictability. Fewer surprises, less rework, and a more honest answer to “when will this be done,” because the work was scoped before it began.
  • None of these are exotic. They’re the same reasons you’d want a contract before a renovation, or a signed-off brief before an agency starts a campaign. AI coding just made the absence of them suddenly, visibly expensive.

How to actually introduce it in your company

If you’re persuaded, resist the urge to mandate it company-wide on Monday. The failure mode here is turning a lightweight practice into heavyweight bureaucracy that your team quietly routes around. A few principles:

Start with one team and one feature. Prove the rhythm before you scale it.

Make the spec review a real checkpoint — the moment a leader or product owner actually signs off, the way you’d approve a budget. The practice only pays off if the review is genuine, not a rubber stamp.

Use it on the software you already have, not just new features. These tools can read existing code and generate a spec describing what it currently does — a fast way to document a system nobody fully understands anymore, before you change it.

Keep it light. The good tools, OpenSpec included, are built to be fluid and iterative, not to recreate rigid waterfall planning. If it starts to feel like ceremony, you’ve over-applied it.

The caveats

It’s discipline, not magic. It works only if your team is willing to write and review specs — and some won’t be, especially developers who reached for AI coding precisely to skip the planning. There’s a culture cost, and pretending otherwise sets you up to fail.

It earns its keep as complexity grows. A solo founder prototyping on nights and weekends probably doesn’t need it; the value scales with team size, system complexity, and how much it would hurt to get a feature wrong. Match the practice to the stakes.

And it doesn’t fix bad thinking. A vague spec produces vague software, now executed with terrifying efficiency. The tool guarantees that what you build matches what you wrote. It cannot guarantee that what you wrote was smart. That part is still your job.

Takeaway

The companies that win at AI-built software won’t be the ones that generate code fastest. Within a year, everyone will generate code fast; it will be a commodity. The edge will belong to the organizations that can reliably turn intent into working systems — that can take a fuzzy business goal and convert it into something a machine builds correctly the first time.

That conversion is exactly what a spec layer does. It’s the unglamorous infrastructure underneath the flashy demos. AI made code cheap. The scarce resource now is clarity — and spec-driven development is how you make it something your company produces on purpose, rather than hopes for by accident.

Sources