We walk into an engineering org that adopted Cursor (or Claude Code, or Copilot) eight months ago. Leadership says shipping velocity went up. The engineers say they're miserable. Reviews take twice as long. Tests are inconsistent. Nobody quite remembers why that module was designed the way it was. This is the post-vibe-coding cliff - and the answer isn't to remove the AI. It's to change how the team uses it. Here's the actual playbook.

What vibe-coding is, and why it works for the first 10 PRs

Vibe-coding - the term is a bit unfair but useful - is the pattern where an engineer types a prompt into an AI coding tool, takes the first acceptable output, tweaks it slightly, and merges. It's fast. For small changes on well-understood surfaces, it produces good PRs. Your team's velocity goes up measurably in the first 2–3 months after AI adoption, which is why leadership is excited.

Then velocity flattens. Defect rate creeps up. The senior engineers start complaining that the junior PRs are correct-looking but architecturally inconsistent. The first post-vibe-coding cliff has arrived, and it happens for a structural reason: AI coding tools are optimizers of local quality. They produce plausible, idiomatic code that compiles, passes the visible tests, and matches the surrounding style. They do not maintain architectural coherence across a codebase over time. That's a human job, and if no human is doing it, the codebase accumulates entropy at the speed the AI can generate it.

The core move: specs come first, code second

Spec-Driven Development inverts the prompt-and-commit workflow. Every non-trivial change starts with a written specification - the intent, the constraints, the test cases, the failure modes, the observability it must produce, the migration story if any. The spec is written by a human. The AI reads the spec before generating code. The reviewer compares the output to the spec, not to a vibe.

This sounds slower. It isn't - once the muscle is built. A 20-minute spec trades against three rounds of reviewer ping-pong on a PR where the reviewer and the author never agreed on what the change was supposed to do. Teams that adopt SDD consistently report that review time drops, merge-to-main time drops, and the number of "fix the follow-up" PRs drops. The compounding effect on velocity is visible by week 6–8 after adoption.

What a good spec looks like

We use a lightweight but strict format. Every non-trivial change is a markdown file with the following sections:

1. Problem. One paragraph: what's broken, why it matters, who it affects. No proposed solution yet.
2. Constraints. What must be preserved - public API shape, database migrations, performance budgets, compliance posture, backward compatibility. This is the section where scope is defined and defended.
3. Behavior. What the change does, in prose and in test cases. Cases include at least: happy path, boundary conditions, known failure modes, observability behavior.
4. Non-goals. What this change is not doing. This section prevents scope creep and gives the reviewer a contract to judge against.
5. Open questions. What the author doesn't know. If there are more than three, the spec isn't ready; go back to step 1.

This is 150–400 lines of markdown for a meaningful change. It takes 20–60 minutes to write. It reads in 5 minutes. It generates code that reviewers can evaluate against a written standard rather than a taste test.

Evals go in CI - with teeth

For any AI-sensitive code - prompt changes, agent logic, model routing - you need evals in CI. Not vibes. Not "the demo worked." Numeric metrics per commit, with pass/fail gates that block merges if quality regresses.

What we run in CI for every agent-touching PR:

• Prompt regression. A reference dataset of 100–500 inputs with expected output characteristics. Precision/recall, specific-assertion checks, latency budgets. Any regression above a threshold blocks merge.
• Cost diff. Average tokens-in / tokens-out per intent, per commit. A change that silently doubles cost is visible before it ships.
• Audit-trail completeness. For critical paths, we require that every agent decision be reconstructable from logs. This is CI-enforced.
• Prompt-injection resilience. A small but growing set of adversarial inputs that the agent must refuse or handle safely. Numbers go up over time as we learn new attack patterns.

The hard part is writing the first evals. The compounding value comes from never again shipping a regression on a case you've already caught once.

Review conventions designed around AI-authored PRs

When 50-70% of your PRs are AI-assisted, the review categories need to shift. The traditional "does this compile / do the tests pass / is the style consistent" checklist catches very little of what actually goes wrong in AI-authored code. We add four explicit review categories:

1. Spec-adherence. Does the PR do what the spec said? Nothing more, nothing less.
2. Regression risk. What else in the codebase this could plausibly break. The reviewer is required to state this explicitly, not infer.
3. Prompt-eval delta. If the PR touches any prompt or agent, the eval results from the CI run are surfaced directly in the review.
4. Observability impact. New logs, new metrics, new audit events - are they present, correctly labeled, and ingested?

These categories are explicit fields in our review template. A PR can't be approved until each is addressed. It's slightly more friction per PR; it's substantially less friction per release, because the post-release firefights go away.

Measure velocity - before and after - with honest numbers

The cheapest way to lose your engineering org's trust is to claim AI made them 3× faster when their reality is that they're working longer hours to clean up AI-generated messes. Measure honestly:

• Cycle time: first commit to production for a typical PR.
• Review time: opened-to-merged for a typical PR.
• Defect density: bugs per 1,000 lines of merged code, normalized against historical baseline.
• Rework rate: percentage of PRs that require a follow-up PR within 2 weeks.
• P99 time-to-ship: the slow PRs matter more than the fast ones. A 5× speedup on the easy PRs that coincides with a 2× slowdown on the hard ones is a wash.

Track these from before your AI rollout. Track them after. If the metrics aren't moving in the direction you want, the rollout isn't working - change the playbook, don't retrospectively redefine the metrics.

The cultural program is the hard part

SDD is a social change before it's a technical one. Engineers who have been writing prompts for 6 months without a spec resist the process. The natural response - "I'll just write the spec after the code" - defeats the entire point.

What we've seen work:

• Workshops, not memos. Two-hour hands-on sessions where the team writes specs for real in-flight work and generates PRs from them. One workshop is worth ten all-hands presentations.
• Paired transitions. A senior engineer pairs with a junior for the first 5–10 spec-driven PRs, explicitly coaching on the spec itself.
• Office hours. A weekly slot where anyone can bring a tricky spec for group review. This becomes the cultural forum where shared judgment gets built.
• Public before/after metrics. The team needs to see that the process is working. Show the numbers on a dashboard everyone can watch.
• Principal-led defaults. Principal engineers model the behavior first. If the most senior people are still vibe-coding, nobody below them will adopt SDD.

Where SDD doesn't apply

Not every change needs a spec. Documentation typos, a test fixture update, a straightforward rename, a dependency bump - these are legitimate candidates for "just prompt it." The SDD bar kicks in for any change that (a) affects public API shape, (b) touches agent logic or prompts, (c) has multi-file impact, (d) has compliance or security implications, or (e) the author genuinely isn't sure about. We estimate 60-75% of merged PRs at a mature SDD shop have an associated spec; the rest are fine without one.

The results we actually see

At our own engineering org and across the customer teams we've coached into SDD, the pattern is consistent. Six to eight weeks after adoption:

• Review time per PR drops 20-35%.
• Defect density drops measurably - typically 25-40% off the pre-SDD baseline.
• Rework rate drops. PRs that required a same-sprint follow-up fall from 18-25% pre-SDD to 5-10% post-SDD.
• Engineers report lower cognitive load. They're not holding the architecture in their head all day to compensate for AI drift.
• New hires onboard faster, because the spec corpus becomes a teaching artifact.

The velocity gains are real but not what leadership was initially told to expect. The headline is not "3× faster." The headline is "same velocity with substantially less debt and substantially happier engineers." Over 12 months, that's the win that actually matters.

If your engineering team is on the cliff

We run Spec-Driven Development on our own product and delivery work - every case study we've shipped (Atlantic Logistics, Brinks, Apollo, Sensei, MAIA, PIBA) was built under SDD discipline. If your team is seeing rising review friction, drift, or just a general sense of "we ship faster but everything feels worse" - book a discovery call. We'll walk your engineering org through a structured SDD readiness assessment, and tell you honestly whether a four-week enablement program will move the numbers or whether something deeper needs to change first.