Shipping an AI code reviewer people actually want

Every developer has met the reviewer who leaves forty comments on a two-file pull request. Half are about naming. A few are wrong. One — buried somewhere around comment twenty-eight — would have caught a real bug, but by then nobody was reading closely.

When I started building Vor, an AI code reviewer that runs as a GitHub Action, that reviewer was my anti-goal. A language model can generate forty comments effortlessly. That’s exactly the problem.

The easy part

The mechanics came together quickly. Vor is built on the Claude Agent SDK and ships as a GitHub Action, so adding it to a repository is one workflow file. On every pull request it reads the diff, explores the surrounding code when it needs context, and leaves inline comments — the same way a colleague would, in the same place a colleague would.

The Agent SDK does the heavy lifting: the model can open files, follow references, and check how a changed function is actually called before it forms an opinion. That last part matters more than it sounds. A reviewer that only reads the diff is guessing; a reviewer that reads the codebase is reviewing.

The hard part was saying less

The first working version of Vor was insufferable. Technically correct, frequently useful, and completely exhausting — a firehose of observations with no sense of which ones deserved a human’s attention.

Fixing that turned out to be the actual project. Three things helped:

Judge severity, then apply a floor. Every candidate comment gets weighed before it’s posted: would this change what a maintainer does next? Style nits, speculative refactors, and “you could also…” musings don’t clear the bar. The default posture is silence.

Review the intent, not just the lines. A pull request is an argument that the codebase should change in a particular way. The useful question isn’t “is this line odd?” — it’s “does this change do what it says, and what does it break?” Framing the prompt around intent cut the noise more than any filter did.

Let the human stay the reviewer. Vor comments; it doesn’t approve, doesn’t block, doesn’t demand. It’s a well-read colleague who speaks up when something genuinely looks wrong, and otherwise lets the humans get on with it.

Start slow, finish strong

Marathon training has a rule I keep coming back to: run the negative split. Start slower than your ego wants, so you’re the one passing people at kilometre thirty-five.

Building with AI right now rewards the same discipline. The temptation is to sprint — wire a model to an API, post everything it says, call it a product. The version that survives contact with a real team is the one that held back: fewer comments, better ones, posted where they’re read.

The line between helpful and annoying really is thinner than you think. Respecting it is most of the work — and, like most restraint, it’s invisible when it’s done well. The best compliment Vor gets is quiet: a small number of comments, most of them acted on, and a review that felt like it came from someone who’d actually read the code.

Because it had.