AI-generated code review
How to review AI-generated code without wasting reviewer time
Before judging the implementation, establish whether the agent’s change is ready to be reviewed at all.
Review AI-generated code in two stages: first verify scope, attribution, checks, sensitive surfaces, and approvals; then perform ordinary semantic code review. If the pre-review evidence is incomplete, block the change before spending reviewer time.
The pre-review checklist
- Confirm the intended change. Can the reviewer state the human-approved objective without relying on the agent’s retrospective summary?
- Establish attribution. Separate files changed during the observed agent session from pre-existing dirty work.
- Inspect sensitive surfaces. Identify auth, secrets, CI, infrastructure, deployment, customer data, payments, and external mutations.
- Verify the verification. Record the exact commands that ran and whether each one passed. “Tests passed” is not sufficient evidence.
- Check approval evidence. Sensitive work should name the approving human or return an explicit approval-required decision.
- Make gaps visible. Missing evidence must remain a blocking fact, not be rewritten as confidence.
- Decide readiness. Begin review, block for evidence, or request approval—with one actionable reason.
Why CI alone is not enough
CI is necessary, but it only evaluates configured checks against the submitted state. It does not necessarily know the agent’s approved scope, the cleanliness of the starting repository, why a sensitive file changed, whether a required local command was skipped, or whether the person requesting review had authority to approve the work.
The pre-review gate connects these facts to one workflow decision. CI remains responsible for builds, tests, static analysis, and other automated checks. Human reviewers remain responsible for semantics, architecture, maintainability, and product intent.
Questions reviewers should answer before reading the diff
- What was the agent asked and authorized to change?
- Which files are attributable to this run?
- Did the change touch a sensitive boundary?
- Which exact checks passed, failed, or did not run?
- Is human or security approval required?
- What remains unproven even if the gate passes?
- Can the decision be reconstructed later without raw agent chat?
Three possible review-readiness decisions
| Decision | When to use it | Reviewer action |
|---|---|---|
| Review may begin | Required evidence exists and no blocking policy gap is present. | Perform normal semantic review. |
| Do not review yet | Verification failed, attribution is unclear, or required evidence is missing. | Return the exact remediation. |
| Approval required | A sensitive surface or authority boundary needs a named human decision. | Route to the correct owner. |
What a useful receipt contains
A Run Control Receipt should lead with the decision and next action. Technical evidence can follow: observed files, policy context, verification commands, archive references, and explicit remaining gaps. The receipt should never imply that a passing gate proves the generated code is correct.
A low-risk adoption path
Choose one repository with active AI-agent work and a reviewer who already experiences ambiguity. Define sensitive surfaces and verification commands before the pilot. For two weeks, require a passing receipt before meaningful AI-agent changes enter review.
Track whether blocks prevented unready work, caught missing approval, clarified attribution, or improved reconstruction. Also record ceremony: confusing failures, repeated information, ignored receipts, and setup cost. Continue only if the team wants to keep enforcing the gate.
Understand the control model
Read What is AI-agent change control? for the boundary, evidence model, and distinction from correctness or compliance.