AI code review: instructions beat the tool every time

In 2024, GitHub publicly documented something many development teams already suspected: upgrading the model behind Copilot Code Review didn't improve review quality at the same pace it improved code generation. The company introduced repository custom instructions, a `.github/copilot-instructions.md` file where teams describe conventions, architecture, and review priorities in plain language. What changed the perceived usefulness of the tool wasn't the jump from one model to another, but that context file the team spent one afternoon writing. We've seen the same pattern in clients who first tried Copilot and then other reviewers: the feeling of 'this doesn't understand our code' repeats with any provider if nobody explains the rules of the game. The problem was never which AI, it was what that AI knew about the team.

That productivity figure for writing code isn't the same problem as reviewing someone else's code. Generating a new function is a task with local context: the model sees what's in front of it and completes a reasonable pattern. Reviewing a pull request is a task with historical context: you need to know why the team avoids a library, which service can't be touched due to a pending migration, or which naming pattern was decided two years ago after a production incident. A bigger model writes better autocomplete because the pattern is in the code it sees. A bigger model doesn't review better on its own, because the information it needs isn't in the diff — it's in someone's head, never written down anywhere.

When an AI reviews a pull request, it usually sees the diff, maybe a few related files, and little else: it wasn't there for the production incident two years ago, doesn't know that endpoint was rewritten three times over a concurrency bug, and doesn't know the team dropped a dependency after a known vulnerability. Every new pull request is, for the model, a cold start: it accumulates no memory between reviews unless someone gives it that memory explicitly. Making the model bigger doesn't fix this, because the problem isn't how much it can process but what information exists to process. If that architectural decision was never written down anywhere, not even the most advanced model on the market can infer it from the code alone.

The blind spot no model solves by itself

This blind spot isn't a temporary flaw the next model version will fix — it's structural: no system can reason about information it never receives. The fix isn't waiting for the next hyped model, it's treating review context as a company asset that needs maintaining, just like technical documentation or an incident runbook. In practice this means writing down decisions that today only live in the memory of two or three senior people. When those people move on, that knowledge disappears for human reviewers too, not just for the AI. That's why the instructions file isn't an AI configuration whim — it's architecture documentation most SMEs never got around to writing at all.

• Real team conventions, not a generic style guide copied from the internet
• Architecture decisions documented with the reason, not just the rule
• An explicit list of banned patterns or dependencies and why
• Real examples of review comments the team considers useful versus noise
• Expected severity level by code type — payments code isn't the same as an internal utility script

Common mistakes when writing AI instructions

• Don't copy a generic internet style guide as the main instruction
• Update the instructions file every time an avoidable incident happens
• Version the instructions file in git, just like the code it reviews
• Review quarterly whether the instructions still reflect the project's real state
• Don't delegate its writing to someone without historical team context

It's worth being honest here, even when it doesn't help sell more services: no instruction turns an AI into a senior reviewer. Instructions reduce noise and align style comments with the team's reality, but they don't give the model the ability to think like an attacker, or to intuit a business case nobody ever documented. We've seen very well-configured AI reviews still miss a subtle race condition or an incomplete permission check, precisely because catching those requires the same adversarial reasoning a pentester applies on purpose, not a pattern you can describe in a text file. That's why we don't recommend replacing human review for code touching payments, authentication, or personal data, no matter how well-instructed the assistant is. What we do recommend is using AI to absorb the volume of minor comments and let the human reviewer focus on what actually requires judgment.

AI doesn't review code worse as versions go by — it reviews the same code with the same ignorance about why your team decided what it decided. A better model doesn't fill that gap; an instruction written by someone who was in the room when the decision was made does.

Starting doesn't require a months-long project or picking the perfect AI provider first. Just pick one active repository, gather the two or three people who've been on it longest, and spend an hour writing down the decisions currently only in their heads: what shouldn't be touched, what's already been tried and failed, what pattern is mandatory and why. That first instructions file won't be perfect, and it doesn't need to be — it gets corrected by the first incident that reveals a gap. What matters is treating it as a living document that grows with every avoidable mistake, not a one-time configuration task. Switching AI models when the next one launches will, in most cases, be the least decisive part of the whole process.