Code review

Who is this for

You submit Pull Requests (PRs)
You review PRs
You are concerned about costs due to AI usage
You want (your team) to use AI intelligently

How this is structured

Not all answers are provided upfront. My goal was to use something like the socratic method to help you arrive at the answer
Navigate “Down” & then “Right”
Anytime you see this image, you can choose to press the “Right Arrow” to skip details.

Would you like to know more?

How agentic code review works

Anthropic chosen as example. System prompts read on 10-Oct-2026

flowchart LR
  A[Gather<br/>the diff] --> B[Start n<br/>sub-agents]
  B --> S["`Sub-agents report (upto & first) k findings`"]
  S --> C[Collate<br/>and dedupe]
  C --> R[Report<br/>x findings]
  NOTE["'n' (angles), 'k' (cap per angle) & 'x' (cap on final report) are decided upfront based on the effort level"]:::note
  B -.- NOTE
  S -.- NOTE
  R -.- NOTE
  classDef note fill:#ffc,stroke:#aa0,stroke-dasharray:3

Would you like to know more?

Step 1: gather the diff

Run git diff @{upstream}...HEAD (or git diff main...HEAD / git diff HEAD~1 if there’s no upstream) to get the unified diff under review. If there are uncommitted changes, or the range diff is empty, also run git diff HEAD and include the working-tree changes in scope — the review often runs before the commit. If a PR number, branch name, or file path was passed as an argument, review that target instead. Treat this diff as the review scope.

System prompt

Step 2: pick N angles

flowchart LR
  F[Start] --> A[A: line by line]
  F --> B[B: removed behavior]
  F --> C[C: cross-file]
  F --> D[D: language traps]
  F --> E[E: wrappers]
  F --> G[F: Efficiency]
  A --> R[Findings]
  B --> R
  C --> R
  D --> R
  E --> R
  G --> R

block-beta
  columns 3
  L["Low<br/><br/>0 angles"]
  M["Medium & high<br/><br/>8 angles"]
  X[">= Extra-high<br/><br/>10 angles"]
  style L fill:#dfd,stroke:#0a0
  style M fill:#ffd,stroke:#a80
  style X fill:#fdd,stroke:#c00

Step 3: collate and dedupe

System prompt

flowchart LR
  A -.- NOTE
  NOTE["`'k' (cap per angle) decided upfront based on the effort level. `"]:::note
  NOTE2["`Medium & High: 6. Extra-high & Max: 8`" ]:::note
  NOTE3["`Agent can stop after first k are found &/or not report any others it finds`" ]:::note
  NOTE -.- NOTE2
  NOTE2 -.- NOTE3
  A[All angles:<br/>up to k each] --> P[Pool] --> D[Merge same defect,<br/>same location, same reason] --> S[Sort by<br/>severity]

  classDef note fill:#ffc,stroke:#aa0,stroke-dasharray:3

Step 4: report x findings

findings is at most ${MAX_FINDINGS} entries ranked most-severe first; each entry has file, line, summary, short_summary, failure_scenario, and category. If more than ${MAX_FINDINGS} survive, keep the ${MAX_FINDINGS} most severe. If nothing survives verification, call it with an empty array. Do not also print the findings as text.

System prompt

flowchart LR
  F[Found<br/>n findings] --> C[Collate<br/>and dedupe] --> K[Keep the most<br/>severe, up to the cap set for effort threshold] --> R[Reported<br/>x findings]
  NOTE[Even if more than x issues have been found & though the effort to find them is already spent, these additional issues are dropped,<br/>not shown]:::note
  R -.- NOTE
  classDef note fill:#ffc,stroke:#aa0,stroke-dasharray:3

Questions

mindmap
  root((Agentic <br/> review))
    What information does the agent have? What does it NOT have?
    :::step1
    What would the agent do well? What would it NOT do well?
    :::step2
    What agentic review operations would be expensive?
    :::step3
    Can we help agents do a better job?
    :::step4
    How would you design your own custom review process? What would it focus on?
    :::step5
    Are manual reviews needed? If yes, what should the manual review focus on?
    :::step6

Deep Dive

mindmap
  root((Agentic <br/> review))
    What information does the agent have? What does it NOT have?
    :::focus
    What would the agent do well? What would it NOT do well?
    What agentic review operations would be expensive?
    Can we help agents do a better job?
    How would you design your own custom review process? What would it focus on?
    Are manual reviews needed? If yes, what should the manual review focus on?

The AI agent was NOT told anything about the defect or requirement.
It is basing its review purely on the diff
It does not attempt to understand your Architecture/Design^*
It does not attempt to understand your project conventions^**

^* unless given enough tokens, context & explicit instructions
^** they do allow you to specify them in a file & will read them if provided

Deep Dive

mindmap
  root((Agentic <br/> review))
    What information does the agent have? What does it NOT have?
    What would the agent do well? What would it NOT do well?
    :::focus
    Is the agent doing things it need not do?
    What agentic review operations would be expensive?
    Can we help agents do a better job?
    How would you design your own custom review process? What would it focus on?
    Are manual reviews needed? If yes, what should the manual review focus on?

AI agents are a good example of SISO
Anthropic’s code-review assumes your code functions & tries to find bugs in that code^*

^* unless given enough tokens, context & explicit instructions

Would you like to know more?

Example 1: Dependent Dropdowns

  flowchart LR
    A[Countries<br/>Dropdown] --> |fetched using| B["query"]
    C[States<br/>Dropdown] --> |fetched using| D["query"]
    A --> |affects| C

    NOTE["Query responses are cached"]:::note
    D -.- NOTE
    B -.- NOTE
    classDef note fill:#ffc,stroke:#aa0,stroke-dasharray:3

Bug Reported: “States” dropdown is not getting refreshed when country changes.

  flowchart LR
    A[Countries<br/>Dropdown] --> |fetched using| B["query"]
    C[States<br/>Dropdown] --> |fetched using| D["query"]
    A --> |affects| C

    NOTE["Query responses are cached"]:::note
    D -.- NOTE
    B -.- NOTE
    classDef note fill:#ffc,stroke:#aa0,stroke-dasharray:3

Developer: Removes caching

Example 2: Component placement

  flowchart TB
    A[Application A] --> |uses| B["Platform"]
    C[Application B] --> |uses| B

Requirement: Add a new presentation-only component used by A.

  flowchart TB
    A[Application A] --> |uses| B["Platform"]
    C[Application B] --> |uses| B

Developer: Adds component directly to A

Example 3: config-driven usecases & feature flags

  flowchart TB
    J[JSON config] --> U[UI]
    U --> L[List]
    U --> C[Create]
    U --> E[Update]
    U --> D[Delete]
    F[Feature flags]

Requirement: Add new behavior to a config-driven usecase

  flowchart TB
    J[JSON config] --> U[UI]
    U --> L[List]
    U --> C[Create]
    U --> E[Update]
    U --> D[Delete]
    F[Feature flags]

Developer adds a feature flag

Deep Dive

mindmap
  root((Agentic <br/> review))
    What information does the agent have? What does it NOT have?
    What would the agent do well? What would it NOT do well?
    What agentic review operations would be expensive?
    :::focus
    Can we help agents do a better job?
    How would you design your own custom review process? What would it focus on?
    Are manual reviews needed? If yes, what should the manual review focus on?

File reads
Tracing paths (callers/callee)
Reading output of commands
The output of the review

Remediation

Reduce file reads
Tailor commands so that they produce succinct output & let AI know to use them
Use tools like JFrog’s boost which trim unnecessary tool output
Create context-specific documentation AI agents can read on demand (example: compass)
Consider tools, MCPs like codegraph

Deep Dive

mindmap
  root((Agentic <br/> review))
    What information does the agent have? What does it NOT have?
    What would the agent do well? What would it NOT do well?
    What agentic review operations would be expensive?
    Can we help agents do a better job?
    :::focus
    How would you design your own custom review process? What would it focus on?
    Are manual reviews needed? If yes, what should the manual review focus on?

Keep PRs small. Even a ‘high’ effort code-review will be ineffective for a large PR
Research other skills like this one by Addy Osmani. Use the one that is most appropriate for the situation

Deep Dive

mindmap
  root((Agentic <br/> review))
    What information does the agent have? What does it NOT have?
    What would the agent do well? What would it NOT do well?
    What agentic review operations would be expensive?
    Can we help agents do a better job?
    How would you design your own custom review process? What would it focus on?
    :::focus
    Are manual reviews needed? If yes, what should the manual review focus on?

sequenceDiagram
  box rgb(200,240,200) Scripts
    participant O as Script: Orchestrator
    participant S1 as Script: diff
    participant S2 as Script: determine sub-agents
  end
  box rgb(250,200,200) Agents
    participant A1 as Sub-agent via CLI: Tests
    participant A2 as Sub-agent via CLI: Code
  end
  box rgb(200,240,200) Script
    participant S3 as Script: Concatenate
    participant S4 as Script: Report Pass/Fail
  end

  O->>S1: get diff
  S1-->>O: diff split by file type
  O->>A1: tests diff + checklist
  O->>A2: code diff + checklist
  A1-->>O: findings
  A2-->>O: findings
  O->>S3: concatenate
  S4-->>O: Pass / Fail

  Note over A1,A2: reuses a common prompt,`<br/>`wrapped by ccusage

Would you like to know more?

Iteration 1

Goal: Apply project-specific guidelines

flowchart LR
  A[Agent] --> D[Run diff] --> F[Find files] --> C[Apply principles<br/>and checklists]
  NOTE["One agent does everything"]:::note
  A -.- NOTE

  NOTE2["One large checklist"]:::note
  C -.- NOTE2
  classDef note fill:#ffc,stroke:#aa0,stroke-dasharray:3
  style A fill:#fdd,stroke:#0a0

Problems
- Agent is doing many unrelated & mechanical tasks. Context grows quickly
- Just reading the rules & checklist exhausts the available tokens

Iteration 2

Goals
- Make the operation less expensive & more deterministic.
- Reduce context bloat

flowchart TB
  O[Agent: Orchestrator] --> S[Script: diff]
  O --> T[Sub-agent: Tests]
  O --> C[Sub-agent: Code]
  NOTE["split diff & separate by file type"]:::note
  S -.- NOTE
  NOTE2["checklist for tests"]:::note
  T -.- NOTE2
  NOTE3["checklist for code"]:::note
  C -.- NOTE3
  O --> D[Sub-agent: Collate & Report Pass/Fail]
  NOTE4["template for output"]:::note
  D -.- NOTE4 

  classDef note fill:#ffc,stroke:#aa0,stroke-dasharray:3
  style O fill:#fdd,stroke:#0a0
  style S fill:#dfd,stroke:#0a0
  style T fill:#fdd,stroke:#0a0
  style C fill:#fdd,stroke:#0a0
  style D fill:#fdd,stroke:#0a0

Problems
- Orchestrator is opaque (Which sub-agent is driving up costs?)
- Orchestrator is still doing a lot of heavy lifting
- Still not deterministic enough

Iteration 3

sequenceDiagram
  box rgb(200,240,200) Scripts
    participant O as Script: Orchestrator
    participant S1 as Script: diff
    participant S2 as Script: determine sub-agents
  end
  box rgb(250,200,200) Agents
    participant A1 as Sub-agent via CLI: Tests
    participant A2 as Sub-agent via CLI: Code
  end
  box rgb(200,240,200) Script
    participant S3 as Script: Concatenate
    participant S4 as Script: Report Pass/Fail
  end

  O->>S1: get diff
  S1-->>O: diff split by file type
  O->>A1: tests diff + checklist
  O->>A2: code diff + checklist
  A1-->>O: findings
  A2-->>O: findings
  O->>S3: concatenate
  S4-->>O: Pass / Fail

  Note over A1,A2: reuses a common prompt,`<br/>`wrapped by ccusage

Salient features
- Using ccusage, we know exactly how much each stage costs.
- Because it is measured, code review can be aborted if costs go beyond a threshold
- The common prompt ensures each agent call benefits from prompt caching

Problems
- Agents reading verbose checklists are driving up costs

Iteration 4

Goal:
- Reduce how many checklists an agent reads
- Reduce how much an agent reads when it is consulting checklists
We already have an established pattern in ‘Skills’ i.e a short description, body on demand

flowchart TB
  U[Verbose 'always read' Checklists] -.->|broken into| I["Index-like"]
  U -.->|& into| S["`Situational checklists


  (_apply only when a criteria is met_)`"]
  I -.->|only if unclear| D[Detail document<br/>per item]

Planned

flowchart LR
  C[Claude CLI call] --> P["Proxy (using Jev)"]
  P -->|simple code| L[Cheap model,<br/>low effort]
  P -->|complex code| H[Strong model,<br/>high effort]

Deep Dive

mindmap
  root((Agentic <br/> review))
    What information does the agent have? What does it NOT have?
    What would the agent do well? What would it NOT do well?
    What agentic review operations would be expensive?
    Can we help agents do a better job?
    How would you design your own custom review process? What would it focus on?
    Are manual reviews still needed? If yes, what should the manual review focus on?
    :::focus

You still own the deliverable.
Use your discretion to decide if you are OK delivering without a manual review
Focus on the big picture
Review with the goal of optimising the review process itself.

Monitor & improve

flowchart LR
  A[Agent findings] --> D[One document]
  M[Manual findings] --> D
  D --> Q{Automatable?}
  Q -->|one file| E[ESLint rule]
  Q -->|several files| S[Script]
  Q -->|no| C[Checklist item]
  NOTE["Each step down costs more AI or human judgment"]:::note
  NOTE -.- C
  classDef note fill:#ffc,stroke:#aa0,stroke-dasharray:3

Wrap up

Be the driver. Don’t delegate thinking to AI. (IF you don’t know, first use AI to learn)
You own the deliverable
First principles (example: TDD, Small PRs) apply more than ever
AI WILL speed you up. But remember SISO: if you are making the wrong decisions, they’ll also compound faster
Read the prompts. Use the right tool for the job