Code Review Is Becoming Team Alignment

A bug can usually be fixed with one deployment.

A feature that customers need, sitting unmerged for weeks because it is stuck in review purgatory, can kill momentum.

Yes, there are bugs that deserve panic rooms, incident calls, and someone staring at a database backup with the facial expression of a man reconsidering every life choice. Security bugs. Money bugs. Data corruption bugs. Protocol compatibility bugs. The fun stuff.

I am not talking about those.

I am talking about the very normal product change where everyone agrees the thing should exist, the implementation is mostly there, and then it spends two weeks becoming stale because review has turned into archaeology.

The author had context on Monday. The reviewer opens it next Thursday. CI is red because main moved. The customer who asked for the thing builds a workaround, churns, or decides the product is moving too slowly.

But hey, at least we caught the trailing whitespace.

Stonks.

I am not saying reviews are bad. Reviews are good. Having another human understand what changed before it hits production is good.

What I am saying is that the thing worth reviewing is changing.

The old game was: can another engineer inspect this diff and decide whether it is good?

The new game is: does the team have mental alignment about what this change means?

Those are not the same question.

The old bottleneck was typing

For most of software history, writing code was expensive enough that the diff itself was a decent proxy for effort.

Somebody had to think through the problem, type the implementation, write tests, run it locally, push the branch, and open the PR. By the time code appeared in review, a human had already spent real time wrestling with the problem. So reviewing the lines made sense. The lines represented the work.

Now the lines are increasingly just the exhaust.

With AI coding agents, producing 800 lines is Tuesday. Producing three alternative implementations in three worktrees while you are making coffee is not impressive anymore, it is just the slightly cursed baseline we are drifting toward.

The expensive part moved to:

• knowing what should be built
• knowing why this shape is right
• knowing which invariants must not break
• knowing what the rest of the system assumes
• knowing how the change will be rolled out
• knowing when to stop the agent before it confidently implements the wrong thing

If review is still optimized around manually inspecting every generated line, it is reviewing the cheapest artifact in the pipeline.

That is how teams end up with a responsible-looking process that quietly hurts the product.

Review queues are product risk

There is a comforting engineering story that slow review protects quality.

Sometimes it does.

Sometimes slow review is just a professional-looking way to not make a decision.

If a feature is risky because nobody understands the domain, leaving the PR open for two weeks will not fix that. Make the risk explicit earlier:

• write the design doc
• name the invariants
• define the rollback path
• add the tests that matter
• decide what telemetry proves it worked
• ship it behind a flag if needed
• publish experimental builds when field testing is the only honest validation path

That last one matters for tools like rote.

A PR review can tell you whether the code looks reasonable. It cannot prove the binary behaves correctly across every weird laptop, cached manifest, old config folder, suspicious shell alias, corporate proxy, and cursed local setup that real users drag into your life like wet cats.

At some point the responsible move is not “one more person should read the diff”. It is an experimental build: clearly labelled, easy to upgrade away from, instrumented enough to learn from, and handed to the people who actually exercise the edge cases.

This is the part review culture often gets wrong. Waiting is not the same as being careful.

Shipping speed changes what you can learn. If a customer needs something today, and you can safely ship a thin version today, you get feedback today. If you wait three weeks for the perfect version, you might learn that the perfect version solved the wrong problem.

This is basically Lean Startup with more YAML.

And there is a whole research program for this stuff too: DORA — Google’s DevOps Research and Assessment program. They are the people behind the State of DevOps reports and the famous four-ish delivery metrics: deployment frequency, lead time for changes, change failure rate, and time to restore service.

The non-boring version: strong teams do not make deployment rare and theatrical. They ship frequently, keep failures survivable, and recover before everyone has finished writing the incident haiku.

The point is not YOLO deploys. The point is that keeping valuable changes stuck for weeks has a cost: lost learning, lost momentum, and occasionally lost customers.

AI did not remove review. It made bad review obvious.

AI-generated code can look complete while being deeply wrong.

A human might write a small ugly hack and leave obvious fingerprints of confusion. An agent will produce a polished abstraction, name the functions nicely, update four files you did not ask it to touch, and calmly violate the one invariant that mattered.

Beautiful little menace.

So no, AI does not mean review goes away. It makes review more important.

But line-by-line review does not scale when code volume jumps by an order of magnitude. The reviewer becomes the bottleneck, gets tired, pattern-matches, and misses exactly the subtle thing they were supposed to catch.

At that point the process is fake safety.

The useful review question becomes:

Is this change consistent with the team’s current understanding of the system?

That includes the code, but it is bigger than the code:

• Intent — what user or product problem is this solving?
• Boundaries — which modules, APIs, schemas, queues, jobs, and workflows does it touch?
• Invariants — what must remain true?
• Failure modes — how does this break, and how do we notice?
• Rollout — can this be enabled gradually, reverted, or disabled without a heroic Slack thread?
• Tests — are we testing the actual risk, or just the happy path so CI feels loved?
• Ownership — who understands this after merge?

A PR is not done when the code compiles. A PR is done when the team can carry it forward.

Review the artifact chain, not only the diff

In my AI workflow, the code is not the first artifact.

Usually the chain looks like:

1. Research the existing system.
2. Write down constraints and current behavior.
3. Produce a design doc.
4. Turn that into an implementation plan.
5. Let the agent write code.
6. Let other agents review it.
7. Then a human reviews the change.

The review target is not just the final diff. It is the reasoning chain that produced the diff.

If the design doc is wrong, the implementation can be beautifully wrong. If the plan misses a migration, the code can be locally correct and globally stupid. If the research misunderstood an invariant, the final PR may pass tests while quietly teaching production a new failure mode.

So human review should start earlier:

• Is the problem statement right?
• Did the agent inspect the right files?
• Did the design name the hard parts?
• Did the plan preserve the invariants?
• Did the tests target the scary paths?

This is why I like design docs as review artifacts. Not 40-page architecture astronaut PDFs. Just a markdown file that says: here is what we are changing, why, which paths matter, what can go wrong, and how we prove it works.

That document aligns the team. The diff is the implementation detail.

Sometimes the artifact should be a video

Also, not every review artifact needs to be more markdown.

I have found it very useful at work to use Screen Studio, Recordly, or literally any recording tool that can capture a decent walkthrough and does not make you want to throw your laptop into the sea.

Record 10-15 minutes of:

• what the hell you have been working on
• how the thing works now
• how the user experience differs from the baseline
• which part of the PR is the actual product effect
• what reviewers should look at before they open the diff

Why? Because the team needs to understand the effect.

People get tired from markdown. I love markdown. I am writing markdown right now. Still, there is only so much markdown you can read in a day before your brain starts converting every design doc into beige soup.

A short walkthrough changes the pace. It lets the author show the before and after, click through the flow, narrate the tradeoffs, and make the intention visible. Especially for UI, CLIs, workflows, developer tools, dashboards, and anything where the “change” is not obvious from the diff.

It also forces the person recording to prove they understand what the agent actually implemented.

That part is underrated.

If I cannot explain the PR in a 10-minute walkthrough, maybe I do not understand it yet. Maybe the agent built something plausible and I am just emotionally attached to the green CI checkmark. Happens to the best of us.

And if reviewers do not want to watch video? Fine. Generate a transcript. We live in the future. Whisper exists. Every meeting tool is trying to sell you summaries whether you asked for them or not. The point is not “video good, text bad”. The point is to create the artifact that transfers understanding with the least suffering.

Sometimes that is a design doc.

Sometimes it is a checklist.

Sometimes it is a 12-minute recording where you say: “Alright, here is what changed, here is the baseline, here is the new behavior, here is the scary part, and here is why I think this is safe.”

That is review too.

Let machines do machine review

A lot of review work is repetitive checking wearing a little hat.

Does this compile? Did the linter pass? Did we introduce an obvious SQL injection? Did a public API change without docs? Did this code call a blocking function in an async path? Did the generated migration have a down path? Did the agent forget to update the snapshot?

Computers should do that.

Use CI, linters, type systems, property tests, preview environments, feature flags, static analysis, and AI reviewers like GitHub Copilot code review or CodeRabbit for the first pass. Use role-based agents too: security, correctness, migration, API compatibility.

They will not be perfect. They are software. Software exists to disappoint us in increasingly automated ways. But they are tireless and annoying, which is useful.

The human should not spend their review budget finding things a bot could have flagged. The human should spend it on taste, intent, architecture, product fit, and the weird domain assumptions that live in people’s heads because we have not written them down like responsible adults.

The review process should look more like this:

1. Automation gates the obvious stuff. Formatting, linting, tests, type checks, generated files, basic security checks.
2. AI reviewers do broad first-pass scrutiny. They summarize the change, flag suspicious areas, and ask dumb-but-useful questions.
3. Humans review the mental model. Does this match what we think the system is? Does this move the product in the right direction? Are we accepting the right risk?

If humans are still doing step one by hand, the team is paying senior-engineer attention prices for checkbox work.

The mental alignment checklist

This is the code review checklist I increasingly care about.

Not “is every line perfect?”

This:

1. Can I explain the change without reading the whole diff? If not, the PR has failed communication. Maybe the code is fine. The team alignment is not.

2. Do I know why this has to ship now? Urgency does not mean panic. It means the PR is connected to a real learning loop: customer need, revenue, activation, retention, operational pain, whatever.

3. Are the invariants named? Money balances. Auth boundaries. Idempotency. Ordering. Protocol compatibility. User-visible state. Every system has ghosts. Name them.

4. Is the risky part tested directly? I do not care that the route returns 200 if the actual risk is duplicate billing, stale cache reads, or backwards compatibility with old manifests. Test the scary thing.

5. Can we undo this? Rollback is not a thing you discover after the deploy. If the migration is irreversible or the feature flag is fake, say the quiet part out loud.

6. Who owns the result after merge? AI makes it easy to produce code nobody feels responsible for. That is poison. Somebody has to understand the change enough to debug it later.

This is usually faster than traditional review, because it stops pretending the reviewer needs to simulate the entire program in their head from a GitHub diff at 11pm.

Small PRs still matter, but not for the old reason

People will say: “just keep PRs small.”

Sure. Small PRs are good. But AI changes the reason. Small PRs are no longer primarily about making line-by-line review easier. They are about keeping the mental model small enough that humans can stay aligned.

A 200-line PR that changes an auth invariant can be huge. A 900-line PR that mechanically threads a new parameter through boring callsites can be small.

Diff size is a terrible proxy for cognitive size.

The useful question is: how much of the system does the reviewer have to load into their head to understand whether this is safe?

So split changes around mental boundaries:

• schema change first
• compatibility layer next
• behavior change behind a flag
• experimental binary if real field testing is the only honest validation path
• cleanup after rollout
• UI wiring once the backend is real

Agents can generate cross-cutting changes with terrifying ease. If you ask an agent to “clean this up while you’re there,” it will. It will clean everything, unify abstractions, and remove the weird branch that was load-bearing for one enterprise customer in 2021.

Do not reward it.

What I would change in a team tomorrow

If I joined a team drowning in review queues while also shipping AI-assisted code, I would not start by yelling “move fast” in Slack.

I would change the shape of review.

First, every non-trivial PR needs a short context block:

## Why now

## What changed

## Risk / rollback

## Tests I actually trust

## What I want reviewers to focus on

Second, any PR over a certain cognitive size needs a design artifact before code. Just enough shared context that review starts with alignment instead of archaeology.

Third, AI review runs before human review. Not as the final authority. As the annoying intern who reads everything and asks why the migration has no test.

Fourth, CI owns formatting, obvious lint, and generated nonsense.

Fifth, review latency becomes a product metric. Long queues are signal: overload, unclear ownership, overly large PRs, or architecture that makes every change cross five boundaries.

Either way, “PRs sit for a week” is not neutral.

The punchline

AI did not make code review obsolete. It made the old version of code review insufficient.

When code was expensive, reviewing code was the natural bottleneck. When code gets cheap, the bottleneck moves to understanding, ownership, and judgment.

So yes, still review the code.

But do not confuse the diff with the change.

The change is the product bet, the architecture movement, the invariant being preserved or broken, the rollout risk, the customer learning loop, and the team’s shared understanding of all of that.

That is what needs review.

Code review is becoming team alignment.

Which is annoying, because it means the hard part is still people.

As usual.