The Prototype Was Never the Hard Part

Why vibe-coded applications collapse on the way to production - and a contextual spec-driven framework for the engineers who have to scale them

There is a conversation I have had, in some form, with more than a dozen enterprise engineering organizations over the past eighteen months. It goes like this.

A team builds something remarkable in ten days. A working prototype of an internal claims tool, or a policy engine, or a customer-facing assistant; the kind of thing that would have taken a quarter to scope and two quarters to build. Leadership sees the demo. Budget appears.

The mandate comes down: productionize it.

And then, four months later, the team is still not shipping.

Not because the prototype was bad. Because the prototype was never a prototype in the engineering sense, it was never a scaled-down version of the real system. It was a different kind of artifact entirely: a sequence of conversations that happened to converge on working software, with no durable record of why any of it is the way it is. Nobody can safely change it, because nobody can predict what a change will break. So the team does the only rational thing available and rewrites it.

This is the vibe coding cliff. I want to be precise about what causes it, because the common diagnosis is wrong, and the wrong diagnosis leads to the wrong fix.

The failure is not the model

The instinct is to blame model capability. If the agent were smarter, the reasoning goes, it would have produced maintainable code the first time. Wait for the next release.

I have watched this bet fail repeatedly, and it will keep failing, because the constraint is not intelligence. It is context.

Hand any frontier model a 10,000-line product requirements document and ask it to build the system, and you will observe three things in sequence.

• Context degradation: details from early in the document stop influencing decisions made later.
• Logic drift: the model fills gaps with plausible invention rather than flagging ambiguity.
• Architectural sprawl: because no boundary was ever specified none is respected, and by week three you have four competing patterns for the same concern.

None of these are hallucination problems in the usual sense. They are orchestration problems. The agent is being asked to hold more coherent state than any single session can hold, and it does what any system under that pressure does, it degrades gracefully in ways that look fine locally and are catastrophic in aggregate.

Which means the fix is not a better model. The fix is a better decomposition of the work.

Principle: treat context as an artifact, not a conversation

Everything that follows rests on one shift. Whether you're working in Claude Code, Codex, Antigravity, or another agentic coding environment, context often begins life inside a chat or execution session: ephemeral, unversioned, unreviewable, and gone when the session closes. In what I'd call disciplined agentic execution, context lives in files that are committed, diffed, and reviewed like any other source.

This sounds like a documentation practice. It is actually a control mechanism. Once context is a file, you can constrain what the agent sees, audit what it was told, and hold it to a plan it cannot silently renegotiate.

The framework has four moving parts, and they compose into a single pipeline that runs from an unmanageable requirements document to a bounded, auditable unit of work:

None of this depends on a specific coding agent. The same principles apply whether your team builds with Claude Code, OpenAI Codex, Antigravity, or the orchestration layer that replaces today's tools next year. The orchestration is the differentiator, not the agent.

1. The Global Brain

Before any code is generated, you establish a small set of foundational documents that define the agent's operating envelope:

• product.md - the project goal, target users, and high-level feature set, distilled from the master PRD.
• tech-stack.md - strict definitions of languages, frameworks, and architectural patterns. Not preferences. Constraints.
• workflow.md - operational rules the agent must follow. Tests before implementation. No new dependencies without approval. Whatever your organization actually enforces.
• AGENTS.md - the rule file your harness natively reads, containing the directives that bind the agent to the spec-driven protocol itself.

The critical design decision here is that the agent loads summaries by default and retrieves specifics only when a task demands them. Dynamic context loading, borrowed straight from RAG practice. The agent should never be operating on implicit memory of what it thinks it decided three sessions ago.

2. Tracks: decomposition as a safety mechanism

The master PRD is then broken into modular vertical slices called Tracks; an authentication module, an invoice state machine, a policy evaluation service. One coherent capability each.

Each Track is executed in its own session with its own clean context. This is not a limitation you are working around; it is the entire point. A session that only knows about the invoice state machine cannot sprawl into the auth module.

For each Track, the agent produces two documents before writing a line of code:

• spec.md - what this Track is, and explicitly what it is not. Boundaries, interfaces, out-of-scope items.
• plan.md - a strict sequential checklist, divided into phases and tasks.

Then the agent stops.

3. The implementation loop and the two gates

Approval Gate 1 sits between planning and execution. A human engineer reads spec.md and plan.md and signs off. The agent is blocked until they do.

This is the highest-leverage twenty minutes in the entire process. Reviewing a plan is cheap; reviewing four hundred generated files is not. Most of the failures I have seen would have been caught by someone reading a checklist and saying this task is doing three things and should be three tasks.

Once approved, the agent works the checklist as a predictable worker:

1. Read the plan, select the next unchecked task.
2. Mark it in-progress.
3. Implement the code and its tests.
4. Commit locally.
5. Mark it done.

The plan.md file is doing quiet but essential work here, it functions as a durable state machine. When a session crashes or a context window fills, the next session reads the checklist and knows exactly where it is. State lives on disk, not in the conversation.

Approval Gate 2 governs progression between tasks or phases. And here I want to be honest rather than promotional: this gate is a dial, not a switch. Per-task human approval is the right setting for a payments flow and the wrong setting for a CRUD scaffold. Teams that leave it maximally strict for everything will conclude the framework is slow, because it will be. Set it by blast radius.

One more constraint that matters more than it sounds: the agent commits locally only. Nothing reaches a shared branch without a human pushing it. The senior engineer retains full control of the commit history.

4. Document-based reverts

This is the part that surprises people, and it is the strongest argument for the whole approach.

Because every commit maps to a named task in a plan document, rollback stops being a Git archaeology exercise. You do not hunt through hashes trying to reconstruct which of nine commits introduced the regression. You say: | Revert the changes made for Phase 2, Task 3 in plan.md.

The agent uses the documented state of the plan to reset the local branch, unchecks the task, and leaves you in a clean state for a retry. The plan document and the repository stay in sync, which means the plan document remains trustworthy and a plan you can trust is the thing that makes the next session possible.

What this costs you

I would rather you adopt this with clear eyes than abandon it in week three.

It is slower at the start. Distilling a PRD into Global Brain artifacts is real work, and it is work that produces no demo. Teams accustomed to a working prototype on day two will feel the difference and should be warned in advance.

It requires senior engineers. The approval gates are only as good as the person reading the plan. If you staff this with people who rubber-stamp, you have added ceremony and removed nothing.

And it is early. Agentic software engineering is a young discipline, and I expect the specifics here; the file names, the gate structure, the revert mechanics to look dated within a year. The durable part is the principle: bound the context, write the plan down, gate the execution, keep the audit trail human-readable.

Where to start

1. Initialize context.Take an existing PRD and distill it into product.md and tech-stack.md. Notice how much ambiguity surfaces during this exercise alone, that ambiguity was always there, silently being resolved by the model on your behalf.
2. Decompose one Track. A single vertical slice. Something real but bounded.
3. Pilot end to end. Run the full loop, including a deliberate revert, so you validate the gates and the rollback mechanics before you depend on them.

The teams getting durable value from agentic development are not the ones with the best prompts. They are the ones who accepted that this is an orchestration problem and designed accordingly, who treat an AI agent less like a brilliant collaborator and more like a very fast contractor who needs an unusually precise statement of work.

The prototype was never the hard part. It never has been.

In the next parts of this series, I'll go beyond the principles and show the implementation. We'll walk through how this framework works in production using modern agentic development tools including Claude Code, Codex, Antigravity, and similar harnesses and the practical patterns that make large AI-assisted codebases maintainable at enterprise scale.