Stop reading PRs

It’s time we all quit reading each other’s code before merging it.

In the spirit of Chesterton’s fence, let’s enumerate why code review exists.

• To catch bugs. Given enough eyes, all bugs are shallow.
• To enforce standards. We work at a company, we have standards here.
• Compliance. SOC II requires it, among others.
• To spread knowledge. Maybe you get hit by a bus tomorrow. Can’t have that.

All of these things are good things. None of them are best done by reading the code in 2026.

• Bugs? CI works. AI reviewbots have gotten pretty good. Your time is better spent elsewhere.
• Standards? If you don’t have a linter set up already, I don’t know what to tell you.
• Compliance? This is a separate post, but you can have both SOC II and 1-person PRs, actually.
• Knowledge sharing? This is worth spending the rest of the post on.

We used to have a deal: if it was worth your time to write the code, it was worth my time to read it. That code was going in the codebase, which meant it was in our mutual self-interests to be familiar with it, so when it invariably blew up, one of us might have a clue.

But you didn’t write the code, did you? Claude wrote the code. I’m slowing both of us down by painstakingly reading it.

I still want to know what the code does, though. AI or not, I’m on the hook for it. So what should I read?

What did you write?

Just send me the prompt is a great starting point. I should read what you wrote. I’ll read the prompt!

You probably didn’t type a prompt though. You went through a process. There’s a widely popular AI-native workflow that everybody thinks is some big secret. Maybe we’ve all been too busy juggling 8 Claude sessions to talk to each other?

It looks like this:

Step 1: create a markdown plan. Load up your favorite agent, your skills, and your MCPs, and fill the context with everything you know. Copy/paste in the Slack message from your PM or the ticket description to get things started, and annotate it with what you think should happen. The agent will propose 250 lines of markdown, which you’ll argue with, edit, and generally hammer into shape.

This is the fun part, for most people.

Step 2: one-shot each chunk of work. Maybe your plan contemplates multiple steps. For each step, have the AI implement it. If you’re working on trading systems or medical devices, you probably hold a tighter leash. Ideally, you have clear programmatic definitions of done for each step, so the agent can self-check.

If your plan is good, and the model is having a good day, this is quick. Sometimes it’s excruciating.

Step 3: perseverate and validate. 8 minutes after starting each step, you get back between 100 and 5,000 lines of code. Your agent swears the tests pass. You do some manual poking, ask some questions, and eventually, you wrap it up in a PR (using your PR skill), and put it up for review.

At no point in that process was there “a prompt” that made sense to send me.

The plan is a good starting point, though. Especially if you’ve declared clankruptcy and retried a couple times, that plan probably reflects everything you know.

Just send me the plan!

The plan isn’t enough

There’s still a real gap, though, because the plan isn’t what’s in the PR you’re trying to get signed off. That deal, you wrote the code so I’ll read it, was a good one, because it forces us to align on what was actually going into production.

The plan tells me what you hoped to do. But it’s the code that’s going to wake me up during my on-call shift. It’s the code that’s going to have bugs. It’s the code that my poor agent will be trying to unpack in 6 months. The plan will be long-deleted, or at best, checked into a /agent-plans folder that’s never accessed.

I want to review your plan, AND I want to make sure the code implements it faithfully. With a human, I can trust they’re trying to follow the plan. With an agent implementer, I’m less sure. Maybe they’re just trying to make the tests green.

I still want to read the plan, but there’s 3 things I’ll need to trust it.

Update the plan. You always learn something when you write code. The plan was, most likely, written in step 1 and never updated again. Your steering in step 2 and findings in step 3 didn’t flow back into it. Those decisions are crucial.

Make it complete. Your plan might be silent on major decisions. The agent probably made those decisions. Go figure out whether the agent added code that you never intended, make sure you agree with it, and put it in the plan.

Check adherence. If the plan is right, the code can still be wrong. This is effectively a new class of bugs, and it’s not the reviewer’s job to exhaustively check for bugs. Ideally there’s an automated check for this, because if not, somebody will have to exhaustively review every line of AI code. That’ll strip all the productivity gains we thought we found.

If you do that, send me all the 5,000-line PRs you want. I’ll read the plan, spot-check the bits of code I’m truly scared of, and get it out the door.