The pull-request review agent
Use an AI reviewer to inspect proposed code, tests and requirements. Keep revision-specific findings separate from fixes, build results and merge approval.
A pull-request review agent reads a proposed code change, compares it with the requirement and reports specific problems or unanswered questions. It can help a reviewer, but finding no problems does not prove that the change is correct or grant permission to merge it.
An agent adds a retry to an import job. A review agent notices that a timed-out request may already have created a record, so retrying could create a duplicate. It points to that path and asks for a check. The author makes the fix, and the reviewer examines the new version.
A review agent can examine changes people already propose. In a limited first version, it reads the code and test results and leaves an advisory report; it cannot edit the branch or merge it. That lets a team evaluate the findings before making them part of an approval decision.
Record the code and target version being reviewed#
A review needs an exact input: the proposed source revision, the destination revision it should work with and the requirements being checked. Branch names alone are not enough because both branches can move while review runs.
The figure highlights why the destination matters. One branch may change a method’s signature while another adds a caller using the old signature. Both changes can work against their original starting point and fail together. Review needs relevant surrounding code and integration checks, not just a list of the author’s commits.
Be precise about the diff. GitHub pull requests use a three-dot comparison: the topic branch is compared with the branches’ common ancestor. A direct two-dot comparison of the latest branch tips also includes differences caused by work only on the destination branch. It is not automatically a clean list of what the author proposes to add.
Review the proposed change and check how it integrates with the current destination. Where appropriate, use a tested merge result. Record the revisions used. If either changes, determine which findings and tests need to be refreshed; do not attach an old verdict to new code without checking.
A short quiet period can combine several pushes into one run. A saved input identity can help avoid duplicate analysis, but include more than the diff: changed requirements, reviewer instructions or tool configuration can change the result too.
Build status changes independently of code. Refresh it even when cached code analysis remains usable. If a newly completed test supplies information the review needs, revisit the affected finding. A cache hit must not be mistaken for a current approval decision.
Use automated checks and inspect what they miss#
Let the formatter check formatting and the linter check its configured rules. Asking a model to repeat those checks adds another result to reconcile. These tools still have execution costs, configuration and limitations; they are not infallible or universally free.
The reviewer can focus on whether the change meets the request, fits the surrounding design and handles relevant failures. Are unrelated edits included? Does the test exercise the changed behaviour? Could two concurrent requests produce an invalid result? Google’s review guidance discusses functionality, complexity and the quality of tests rather than treating a passing build as the whole review. When generated changes outpace that attention, the human attention bottleneck calls for limiting new work and making each decision easier to inspect.
Inspect tests as code. A removed assertion, newly skipped test or weaker expected result can conceal the defect the task was meant to fix. Such changes can also be legitimate when an approved requirement changes. Report the changed rule and require the appropriate review instead of assuming every test edit is wrong.
A useful finding names the affected behaviour, points to the relevant code or result and explains the consequence. In the illustrative import example, describe how a lost response can lead to a duplicate write. “Improve error handling” gives the author much less to act on.
Separate required fixes, optional suggestions and questions. Google’s comment guidance recommends explaining the reason and making comment severity clear. A naming preference and an unresolved authorisation check should not appear equally important.
Also state what the agent did not inspect or could not verify. An empty findings list is not proof of correctness. Give the person deciding on acceptance the scope, limitations and actual test results, not just a green summary.
Separate reporting a problem from fixing it#
In the first design described here, the reviewer cannot push code. It saves a finding for the author, who produces a repair commit. The reviewer then checks the new revision and records whether the finding was resolved.
This costs another handover, but it keeps code-writing permissions out of the review role and makes the sequence easier to inspect. The reviewer does not quietly replace its own finding with an unreviewed fix.
The separation is useful, not a guarantee of independent reasoning. Two agents can read the same incomplete requirement or trust the same incorrect summary. Give the reviewer the original requirement, code and check results rather than only the builder’s explanation.
A comments-only identity still performs an external write and may have access to private code. Check destinations and permissions, restrict unnecessary network access and treat issue text and code comments as untrusted. Do not describe this setup as having no possible harmful effects.
For this supervised workflow, the agent reports findings but does not grant merge approval. Enforce that through its permissions and the repository’s merge rules. Other policies are possible after evaluation, but the name “reviewer” alone does not make a model’s verdict authoritative.
When a needed requirement is missing, use the same clarification process used before coding. Continue to the human merge gate for how the final reviewer uses these findings without treating them as a substitute for judgement. If you are the human reading an AI-authored pull request yourself, the review order and checklist cover that side.
IF YOU REMEMBER ONE THING
Review a named version, explain specific findings and say what remains unchecked. After the code changes, confirm that the old findings and test results still apply.
Questions people also ask
4 QUESTIONSIs a review agent a useful first factory workflow?
It can be. An advisory reviewer can use existing pull requests without deploying changes. It still needs suitable repository access, safe handling of untrusted text and a way to measure missed defects and distracting comments. It is not risk-free or automatically the best starting point for every team.
What should a review agent leave to existing tools?
Use formatters, linters and test runners for checks they already implement. The agent can inspect their results and focus on behaviour, design and missing tests. A tool result can still be incomplete or based on a mistaken rule; report that with evidence rather than silently overriding the check.
Should the reviewer push fixes to the author's branch?
A useful first design keeps code writes out of the review role. The reviewer reports findings, the author fixes them and review examines the new version. This reduces permissions and makes the sequence clearer, but separate agents can still share the same mistaken assumption.
How can repeated review runs avoid unnecessary cost?
Combine a burst of pushes into one run and reuse analysis only when its relevant inputs are unchanged. Record the source and target revisions, requirements and review configuration. Refresh check results separately, and rerun affected analysis when new evidence or changed code makes the old findings incomplete.