Writing AI Prompts for Code Review That Find Real Bugs

Most engineering teams do not have a code review problem so much as a triage problem. Diffs arrive faster than anyone can read them well, so reviewers skim the familiar ones and spend their attention on the changes that look frightening. The outcome is predictable: the frightening diffs get read, and the quiet defects sitting inside ordinary diffs ship to production.

An AI model can shift that balance, but not by doing the reading for you. It shifts when you stop asking 'review this code' and start asking a precise question that demands a precise answer. The first request returns fifty style notes about naming. The second returns one missing authorization check and a test that would pass even if the function returned garbage.

This guide is about building review prompts that survive contact with a real repository, routing them through a workflow that humans still own, and knowing when the model's answer should be ignored. If prompt structure is new to you, the prompt library is a sensible place to see reusable patterns before you write your own.

Why 'review this code' produces noise

A model asked to review code has no idea what you care about. It optimizes for the signals that are easiest to see: naming, indentation, comment density, function length, the presence of a TODO. Those are real concerns, but they are the cheapest ones to catch, and most of them are already handled by a linter, a formatter, or a type checker running in continuous integration.

The value of a prompt is that it encodes priority. When you tell the model that this service moves money, that a partial write is unacceptable, and that you would rather see three real defects than thirty style notes, the shape of the output changes. You are not asking the model to be smarter. You are narrowing the space of acceptable answers.

There is a second benefit that teams underestimate. Prompts are reviewable artifacts. A prompt committed to a repository next to the code is a written statement of what your team considers a serious defect. New engineers read it and learn. Experienced engineers argue with it and revise it. That is a more useful document than a wiki page nobody opens, because it lives where the work happens and it changes when the architecture changes.

The anatomy of a prompt that finds real defects

Strong review prompts share five components. Skip any one of them and the output degrades in a specific, recognizable way.

Review the diff, not the file

Most review prompts fail at the input stage. They hand over a nine-hundred-line file when forty lines changed. Models attend to what is present in the context, so extra code dilutes attention and invites commentary on lines the author cannot act on in this change.

Send the unified diff instead, with a little surrounding context:

git diff --unified=8 origin/main...HEAD > review.diff

Eight to ten lines of context matter more than they look. They let the model see the guard clause that already validates the input three lines above the new call, which is frequently the difference between a genuine finding and a false alarm. Generate the diff against the merge base rather than your last local commit, and strip generated files, lockfiles, vendored dependencies, and minified assets before anything leaves your machine.

State context once, briefly

A short preamble pays for itself. Include the language and version, the framework, the trust boundary the code sits behind, and any invariant the team treats as non-negotiable. A single line such as 'this handler runs behind an authenticated gateway, so do not flag missing authentication here' removes an entire class of noise that would otherwise consume the review.

Also state what the repository already enforces automatically. If formatting, import order, and static typing are handled in continuous integration, say so. The model will stop reporting them and spend its attention elsewhere. Context is not the same as volume: three accurate lines about your system beat three paragraphs of generic background.

Demand a severity ladder

Ungraded findings are close to useless. A list where 'missing database index' and 'trailing whitespace' appear as siblings forces the reviewer to re-triage everything the model produced, which can take longer than reviewing the diff unaided.

Define three or four levels with concrete meaning for your team, from blocker to nit, and require one sentence of justification for each assignment. Severity labeling also gives you something to measure later. If nearly every finding comes back as a nit, your prompt is aimed at the wrong target.

Require a specific output shape

Pick a format and insist on it: file, line, severity, failure mode, and fix. Some teams want a Markdown table; others prefer findings ordered by severity with a short summary at the end. The shape matters because it shapes reasoning. A required line asking what would have to be true for this code to fail pushes the model from pattern matching toward actual analysis.

Say what to do when uncertain

Models invent APIs, imagine configuration keys, and describe behavior of library versions that never existed. One instruction does a surprising amount of work: 'if you are not certain, describe what you would check to confirm it.' That converts a confident wrong answer into a useful question, which is a far better artifact for a reviewer to receive.

A reusable prompt template

The template below works for most application code. Replace the bracketed sections and delete anything your repository already enforces.

You are performing a focused code review.

Context:
- Stack: [language, framework, version]
- This code path: [what it does, who calls it]
- Trust boundary: [is input untrusted, who is authenticated]
- Invariants we care about: [writes are transactional, amounts are integer cents]
- Already enforced by CI: formatting, lint, type checks, import order

Input: the unified diff below.

Report findings in this priority order:
1. Correctness: wrong results, unhandled edge cases, off-by-one errors, race conditions
2. Security: authorization gaps, injection, unsafe deserialization, secret leakage
3. Data integrity: partial writes, missing transactions, migration hazards
4. Test gaps: behavior this diff changes that no test exercises
5. Maintainability: only issues that would genuinely mislead the next reader

Rules:
- Comment only on lines in the diff or code directly affected by it.
- For each finding give file:line, severity (blocker/major/minor/nit),
  one sentence describing the failure mode, and a concrete fix.
- If unsure, state what evidence would confirm the finding instead of guessing.
- Do not restate the diff or summarize obvious changes.
- End with a three-sentence summary and a recommendation to ship, revise, or block.

Diff:
[diff here]

Two lines in that template do most of the work. 'Failure mode' forces the model to describe a scenario rather than a smell, which makes the finding testable. 'Recommendation to ship, revise, or block' gives you one line to read first when you are triaging a queue of fifteen pull requests at the end of a sprint.

Prompt patterns for specific review jobs

One prompt cannot serve every review. Different changes fail in different ways, and the highest-leverage move is writing narrow prompts for the failure modes your codebase actually experiences.

Security at the trust boundary

Point the model at the boundary explicitly and ask it to trace user-controlled data to sinks: database queries, shell commands, template rendering, file paths, redirect targets, log lines. A useful instruction is 'for each user-controlled value, trace where it ends up and what escapes it along the way.'

Then ask a harder second question: 'which of these findings would still be exploitable if the framework defaults were misconfigured?' That catches the class of defect where developers trust an abstraction that a configuration change or an upgrade quietly disabled.

Concurrency, retries, and state

Ask for interleavings instead of a line-by-line reading. 'List the orderings of two concurrent requests to this endpoint and say which produce an inconsistent state' produces concrete scenarios rather than vague warnings. Follow with idempotency: what happens when this webhook arrives twice, or when a client retry lands after a timeout that already succeeded on the server.

Tests that would actually fail

A test review prompt should ask one question: if this function returned a wrong result, which test would fail? Coverage percentages are a weak proxy, and a test that only asserts no exception was raised proves very little. Ask the model to name the specific assertion that would break, and to flag tests coupled to implementation details rather than observable behavior.

Performance, with numbers attached

Give the model the query, the row counts, and the expected call frequency. Without numbers, performance commentary is guesswork. With them, you get observations worth acting on: a loop that runs once per page load, an index that will not be used because the predicate wraps a column in a function, a response payload that grows without bound as a tenant's data accumulates.

Dependency and configuration diffs

Changes to dependency manifests, environment configuration, and infrastructure files deserve a separate prompt. Ask which version constraint changed, what behavior that unlocks or removes, whether a pinned transitive dependency now conflicts, and whether any secret material appears anywhere in the diff. This is also the category where a model is most likely to invent a changelog entry, so require it to mark anything it cannot verify from the diff itself.

Readability without churn

Refactor suggestions are the easiest thing for a model to produce and the most expensive for a team to act on. Constrain them: 'only suggest refactors that reduce the number of concepts a reader must hold in mind; do not propose renames, file moves, or new abstraction layers unless the current code contains a demonstrated defect.' That single sentence prevents a great deal of review churn.

Fitting AI review into a real workflow

Author-side pre-review

The best place for an automated review is before a human sees the change. The author runs the prompt, fixes the genuine issues, and leaves a short note on the pull request: what was flagged, what was fixed, and what was deliberately ignored. This turns a defensive conversation into a discussion about trade-offs.

A narrow first pass in continuous integration

Keep automation narrow. A bot that posts forty comments on every pull request gets muted within a week, and a muted bot is worse than no bot because it hides the one finding that mattered. A better configuration: run the prompt only for security and data-integrity categories, post findings as a single collapsed comment, and fail the check only for the blocker tier. Record which findings humans dismissed, because that list is the best input for the next prompt revision.

Keep prompts in version control

Store review prompts next to the code they review, in a directory such as docs/review-prompts/. When the architecture changes, the prompt changes in the same pull request. Reviewers can propose prompt edits the same way they propose code edits, with a rationale and an approver.

Humans still decide

The model has no idea that the odd-looking code exists because of a contract signed two years ago. It cannot weigh the cost of delaying a release, and it cannot tell whether a teammate is ready to own a subsystem. Review is a social process whose purpose is not only to catch defects but to spread knowledge and agree on standards. Let automation raise the floor; keep people responsible for the ceiling.

Mistakes that make AI review worthless

• Reviewing too much at once. A two-thousand-line diff produces shallow findings across the board. Split it into reviewable units first.
• Leaving the prompt vague. 'Best practices' is not a criterion. Naming what failure looks like in your system is.
• Accepting findings without verification. Every blocker should be reproducible. If you cannot write the failing test the model described, treat it as a hypothesis rather than a defect.
• Ignoring the data-handling question. Sending proprietary code to a third-party service is a policy decision. Check what your organization permits, whether the provider trains on submitted inputs, and whether requests need secrets and customer identifiers stripped before they leave the network.
• Letting the bot set the tone. Comments forwarded verbatim read as impersonal. Summarize in your own voice and keep 'this is a defect' clearly separate from 'this is my preference'.
• Treating agreement as accuracy. If you agree with every finding, you may be reading your own assumptions back. Seed a known defect into a scratch branch and see whether the prompt catches it.
• Never revising the prompt. A prompt that produced a false positive last month will produce it again next month unless someone edits it.

Deciding when AI review helps and when it does not

Situation	Use AI review?	Why
Large mechanical refactor touching many files	Yes, with a narrow prompt	The change is repetitive; consistent checking beats tired eyes
Payment, authentication, or data migration code	Yes, plus an expert human	The cost of a missed defect is asymmetric
A one-line configuration flag flip	Rarely	The human already knows the change; context matters more than analysis
Novel protocol or algorithm design	Partly	The model can enumerate edge cases but cannot validate a design it has never seen
Code under a strict confidentiality rule	Only with an approved environment	Policy outranks convenience

Track three numbers over a few months: the share of AI findings that humans accept, the share of defects found in review versus after release, and the median time a pull request waits for a first response. If acceptance is low, sharpen your severity definitions. If escaped defects stay high, add prompt sections for the categories you missed. Most escaped bugs belong to a small number of recurring patterns, and each one deserves its own narrow prompt.

Be skeptical of speed wins that come with rising rework later. The goal is not fewer comments. The goal is finding expensive defects while the code is still cheap to change.

FAQ

Should I paste the whole file or just the diff?

Just the diff, with enough surrounding context to understand it, usually five to ten lines. Whole files invite commentary on code the author did not touch, which is precisely the commentary that gets ignored.

Can an automated reviewer replace a human reviewer?

No. It catches mechanical defects faster and more consistently, and it does not get tired on a Friday afternoon. It cannot weigh business context, mentor a junior engineer, or decide that a known flaw is acceptable given the release schedule.

How long should a review prompt be?

Long enough to include context, priorities, severity levels, and an output format, typically 150 to 400 words. Beyond that, returns flatten and models start ignoring instructions, especially constraints listed last.

How do I handle false positives?

Expect them and budget triage time. Reduce them by stating your trust boundary, listing what continuous integration already enforces, and requiring the model to explain its reasoning. A false positive with a clear rationale is cheap to dismiss; a bare assertion is not.

Is it safe to send proprietary code to a model?

That depends on your organization's policy and the provider's terms. Many teams run a self-hosted model for sensitive repositories, or strip secrets and customer identifiers before sending a diff. Decide this before you build the workflow, not after an incident.

Does this work for less common languages and frameworks?

Well-represented languages get sharper findings because there is more training signal behind them. For niche languages, include a short idiom guide in the prompt and explicitly ask the model to flag uncertainty about conventions rather than guess at them.

How often should the prompt itself be revised?

Revise when you notice a repeated false-positive pattern, or when a defect escapes that a prompt category should have covered. Small, evidence-driven edits every few weeks beat a large rewrite nobody reviews.

Turn your review standards into something the team can watch

Written guidelines get skimmed. A three-minute walkthrough of how your team reviews a diff gets remembered. Orelon is an AI video generator for cinematic ideas in motion, and teams use it to turn review checklists, architecture notes, and onboarding documents into short explainer videos that new engineers actually finish. Start from a template, paste in your prompt and your review rules, and publish a walkthrough next to the repository. The prompt is the tool; the shared standard is what makes it stick.