🔍 Review Beyond the Diff
A review agent can explore related files, verify contracts, analyze tests, find duplications, identify risks, compare against repository standards, review architecture, look for security flaws, assess performance, and check compatibility. The diff is the starting point, not the limit.
🎯 What the code review should evaluate
🆕 New here?
Diff is the set of lines added and removed by a change. Semantic duplication is when two parts of the system do the same thing, written in different ways — invisible to text search, but discoverable by an agent that reads the repository. Scope compliance is checking whether the change did only what was requested.
Context
The entire repo, if needed
Contract
Consumers must not break
Duplication
Semantic, not textual
Scope
Did it do only what was requested?
👥 Separate implementer and reviewer
The reviewing agent shouldn’t rely entirely on the implementing agent’s conclusions. Separating them reduces the risk that both repeat the same incorrect assumption — and that’s the difference between a real review and a second rubber stamp.
How to read: on the left, the arrow loops back to the same agent — it reviews while carrying the reasoning that produced the error. On the right, the reviewer receives only specification + diff, without the author's history: that’s what makes it possible to disagree.
🧪 Copyable exercise — independent reviewer
Objective: run a real review on one of your changes. Open a new session from the agent (clean context, without the implementation history) and paste:
Você é o revisor independente. Não implementou nada disto e não deve confiar em nenhuma afirmação de quem implementou. Especificação da tarefa: <cole a spec> Diff a revisar: <cole a saída de: git diff origin/main...HEAD> Revise nesta ordem e leia os arquivos relacionados antes de concluir: 1. a mudança cumpre a spec? o que ficou faltando? 2. algo FORA do escopo foi alterado? 3. algum contrato/comportamento existente muda para quem consome? 4. o tratamento de erro cobre timeout, duplicidade e permissão negada? 5. existe duplicação semântica com algo que já existe no repositório? 6. os testes provam o comportamento novo ou só executam o código? Formato da resposta: lista de achados, cada um com [severidade: bloqueante | importante | menor] · arquivo:linha · por que é problema · como verificar. No máximo 7 achados — priorize. Se não houver bloqueante, diga isso explicitamente.
How to verify: take each "blocking" finding and try to reproduce it. If two out of three don't hold up, your reviewer is generating noise—tighten the prompt (fewer findings, require more evidence) before plugging this into the team workflow.
Clean context
Always start a new session
Spec + diff
Not the author’s reasoning
Severity
A finding without it is noise
Findings limit
Drives prioritization
🏛️ Conduct an architectural review
It’s the kind of defect no test catches: the change works perfectly and is still wrong—because it crosses a boundary, duplicates a capability, or creates coupling that will accrue interest later.
✓ Questions that reveal the real problem
- ✓Should this layer know about that one?
- ✓Is there already something in the repository that does this?
- ✓How many modules need to change together because of this?
- ✓Does this abstraction have more than one use case today?
✗ Signs of architectural violations
- ✗Import crossing a domain boundary
- ✗Business rule inside the controller/handler
- ✗Third implementation of the same thing, under a different name
- ✗A new module that only one place uses and nobody asked for
💡 Practical tip
If an architectural rule comes up three times in review, it should become a test: a dependency check that fails the build when someone imports across the boundary. That’s the topic of module 3.3—textual rules become gates.
Boundary
Import is evidence
Coupling
Count who changes together
Abstraction
Needs 2+ uses
3x rule
Becomes a test
🔐 Cover Security, Performance, and Maintainability
A generic reviewer finds style issues. A reviewer with one lens per pass find what hurts. Run the same change three times, each with a different focus.
Security lens
Unvalidated input, injection, missing authorization, secrets in code, sensitive data in logs, overly broad permissions, dependency with a known CVE.
Performance lens
Query inside a loop (N+1), missing index, loading an entire collection into memory, external call without a timeout, retry without increasing delays.
Maintainability lens
A name that doesn’t say what it does, too many nested conditionals, scattered configuration, a test that checks the implementation instead of the behavior, documentation that was already out of date when it was written.
A focus
By handoff
Secret
Block, don’t suggest
N+1
Classic and costly
Maintenance
Cost that shows up later
🚧 Understand the Limits of Automated Review
The automated reviewer doesn’t know the business intent, what was agreed in the meeting, or the historical reason for a hack. And it has a bad habit: generate volume. Thirty nitpicky comments per PR teach the team to ignore reviews—including good ones.
⚠️ Attention
During the automated review, precision matters more than breadth. A reviewer who gets three things right is better than one who points out thirty, five of which are real. The cost of a false positive is not the time it takes to read—it is lost trust.
How to calibrate noise
- • Limit the number of findings per review (5 to 7).
- • Require a severity level and "how to verify" for each finding.
- • Prohibit style comments — that’s the linter’s job, automatic and silent.
- • Measure: out of every ten findings, how many led to a change? If fewer than half, tighten the prompt.
Precision
Beyond scope
Style
It’s linting, not review
False positive
It costs trust
Measure
Finding → change
🧑⚖️ Preserve the Role of Human Review
AI filters, explores, and prepares. The decision remains human — not as a formality, but because intent, priority, and risk acceptance are not properties of code; they're choices made by whoever is accountable for the system.
👤 What only a human can decide
- •Whether the problem you solved was actually the right problem.
- •Whether the residual risk is acceptable for this business, at this time.
- •Whether it’s worth paying down debt now or logging it and moving on.
- •Who answers if something goes wrong.
Quick check: which setup produces the most reliable review?
Intent
Only a human knows
Risk
Accepting is a decision
Small PR
Makes review possible
Responsibility
Can’t be delegated
📌 Module Summary
Next Module:
3.3 - Quality Gates: turning written rules into mandatory checks.