The Shipping Gap In The Fast Lane

The Shipping Gap, Episode 1: Why code review became the new bottleneck, and three things to do about it.

Six months ago we looked at our cycle time and noticed something we didn’t expect. The time from “branch created” to “code complete” had collapsed. Engineers paired with coding agents were shipping in hours what used to take days. Great news. But the time from “PR opened” to “PR merged” had not moved. For some teams it had gotten worse.

The bottleneck had moved. We just hadn’t caught up to it.

This is the gap I want to write about. Not a single bottleneck, but the whole space between “we wrote the code” and “the customer got the feature.” AI has compressed the first half of that sentence and left the second half mostly untouched. Closing the gap is the work of the next few years for every engineering organization. This post is the first in a series I’m calling The Shipping Gap, and it covers the part most teams hit first: code review. Future episodes will cover deployment, on-call, hiring, planning, and the shape of the team itself.

If your team uses AI to write code, this will happen to you if it hasn’t already. The work that fits inside one engineer’s head got cheaper. The work that requires two or three engineers to align on a change got more expensive, relative to everything else. Reviewers became the constraint.

Throwing more reviewers at the problem does not help. You cannot hire your way out of an attention problem. What helps is rethinking what a code review actually is, and using the same tools that created the volume to handle it.

Here is what worked for us. None of it is exotic. It is three deliberate moves.

1. Standardize on one architecture and stop drifting

The biggest hidden tax on review time is not unfamiliar code. It is unfamiliar shape. When every service in your org has a slightly different folder structure, slightly different naming conventions, slightly different idea of where a database call should live, every PR begins with the reviewer reorienting themselves. Multiply that across a team and you have spent hundreds of engineer hours per quarter on cognitive overhead nobody planned for.

Pick one architecture. Write it down. Make it boring.

For us it is a domain-first, ports-and-adapters layout. There is a core module that holds the business logic and depends on nothing. There is an app module that wires the core to the outside world: web, database, queues, third-party APIs. Dependencies only point inward. There is one canonical reference application every new service is modeled after. New engineers and new agents both learn it on day one.

This sounds rigid. It is rigid. That is the point. When the shape is predictable, a reviewer opens a PR and instantly knows where to look. A new validation rule belongs in the domain. A new database table belongs in an adapter. A new API endpoint is a thin shell that calls into a use case. If a PR puts something in the wrong layer, it stands out before you even read the logic.

Once the shape is written down, you can write tests that enforce it. Architecture tests, ArchUnit and its equivalents in other languages, let you encode your layering rules as actual test code. A domain class importing from an adapter, build fails. A controller calling a repository directly instead of going through a use case, build fails. A package leaking types it should not expose, build fails. These tests are deterministic. They run in milliseconds. They catch the same violation the same way every single time. No false positives. No hallucinations. This is the layer of enforcement no LLM-based reviewer can match, and you should put it in place before you build any AI-assisted review tooling on top.

Standardization pays another dividend you may not expect. Your coding agents get dramatically better. An agent given a clear, narrow architectural pattern produces work that looks like every other piece of work in your codebase. The agent stops freelancing. Reviewers stop having to evaluate “is this the right approach for this kind of change,” because the right approach was decided once, and now everyone follows it.

You will not get there overnight. You will have three or four legacy services that need migration. Pick the one with the highest review burden and start there. Migrate slowly. The point is direction, not speed.

2. Equip your reviewers with AI, not just your authors

Most teams have rolled out coding agents to authors. Very few have rolled them out to reviewers. This is backwards. If AI generated the code, AI should help review it.

We built two things, and each took less than a week.

The first is a pre-commit and CI plugin that knows our engineering standards. The standards live in a markdown document, not in someone’s head. Layering rules. Naming conventions. How to handle errors. When to use a value object versus a primitive. The plugin reads the standards and runs every changed file against them at commit time and again on the PR. Most of what reviewers used to flag, wrong layer, missing input validation, leaking persistence types into the domain, gets caught before a human ever sees it. The signal-to-noise ratio of human review goes up because the trivial stuff is gone.

The second is a PR walkthrough generator. When a PR is opened, a Claude Code skill produces an HTML page that shows the full impact graph of the change as d2 diagrams. It traces every modified function or class and shows what calls into it and what it calls out to. It marks the upstream and downstream effects. It points out which areas need close inspection because they touch hot paths or critical contracts, and which areas are safe to skim. The reviewer opens the page and gets a guided tour of the change instead of a wall of diff.

The change in reviewer behavior is the part worth paying attention to. Reviewers used to scroll through diffs hoping to notice things. Now they read a one-page summary, look at the impact graph, and jump to the two or three files that actually matter. Reviews that used to take an hour now take fifteen minutes, and they catch more.

You do not need our exact setup. The shape of the idea is what matters. Pick the three or four things your reviewers spend the most time doing manually. Build small AI-assisted tools for each. Keep them inside the existing dev workflow, not in some side dashboard nobody opens.

3. Put the agent’s spec on every PR

This one is small in effort and the largest in payoff.

Require every PR to include the actual spec the developer wrote and handed to the coding agent. Not a polished after-the-fact summary. Not a paragraph stitched together for the reviewer. The real brief, in the same words the agent worked from.

This is the bit most teams get wrong. They ask for “a description of the change” and get a vague paragraph that says nothing about how the work was actually done. What you want is the input the agent saw. What problem the developer told it to solve. What approach they pointed it at. What constraints they specified. What edge cases they called out. What they marked as out of scope.

Why this matters is simple. The spec is the interface between the developer’s thinking and the agent’s output. If an edge case is not in the spec, there is a fairly real chance the agent did not handle it. The reviewer reading the spec is doing two things at once. They are auditing what the developer was thinking. They are auditing what the agent was told. Gaps in either one show up before you read a single line of code.

This changes the failure mode of review. You stop hunting for bugs in the diff and start hunting for blind spots in the brief. A missing constraint in the spec almost always means a missing check in the code. A vague “handle errors gracefully” almost always means whatever the agent felt like that day. The brief becomes the leading indicator, and the diff becomes the verification.

We expected pushback the first time we made this mandatory. We got the opposite. Engineers told us pasting the real spec on the PR made them write better specs in the first place, because they knew the spec was going to be read. Reviewers told us seeing the spec first changed how they read the code. They stopped asking “what is this doing” and started asking “is this doing what the spec asked for, and did the spec ask for the right thing.”

If you only do one of the three things in this post, do this one. It costs nothing. It works the next day.

Putting it together

The three shifts reinforce each other. Standardized architecture makes automated review tools possible because there is a known shape to check against. Automated review tools save reviewer attention for the things that actually need a human. Sharing the agent’s spec on the PR aims that human attention at the right question, which is whether the brief itself was sound.

The result is not “humans review less.” The result is humans review better. We catch more real issues. We catch them faster. Reviewers stop dreading the PR queue. The bottleneck we discovered six months ago is not gone, but it is no longer the constraint on the team. The customer started getting features again at the speed our standup charts had been promising for months.

What the engineering manager actually has to do

You do not need to write the code for any of this. You need to do four things.

Pick the architecture. Have the conversation, make the call, write it down. This is the only one where you cannot delegate the decision itself.

Treat the engineering standards as a living document. Assign an owner. Review it quarterly. If a recurring review comment is not in the standards, the standards have a gap.

Sponsor the tooling work. Give one or two engineers two weeks to build the pre-commit checks, the architecture tests, and the PR walkthrough. Treat it as platform work, not a side project.

Require the agent spec in the PR template. Add the section. Have the bot block PRs that ship with it empty.

That is it. No new headcount. No vendor. All of it is achievable in a quarter.

A note on what this is not

This is not about replacing reviewers. It is not about machines approving each other’s work. The human is still the one who says “ship it.” What we are doing is taking everything that should never have required a human in the first place and removing it from their queue, so the attention we have is spent on the things that genuinely need it.

The teams that pull ahead in the next year will be the ones that figure this out. The volume of AI-generated code is not going down. If your review process is the same one you ran two years ago, you are quietly accumulating a tax on every change. You can pay it forever or you can fix it once.

We chose to fix it. So can you.

About The Shipping Gap

This is episode one of a series on building engineering organizations for the age of AI-assisted coding. Coding got fast. Everything else mostly didn’t. Each episode picks one part of the gap and works through what changes.