# Production-Grade AI Code Review Agent

> An evidence-based code review agent for real PRs: security, correctness, concurrency, performance — with file:line findings, risk scores, and a human-escalation gate.

- **Category:** Software Engineering
- **Difficulty:** Advanced
- **Setup time:** 45 min
- **Stacks:** Claude, LangGraph, OpenAI
- **Version:** 2.0.0 (updated 2026-06-20)
- **Source:** https://agent-kits.com/kit/code-review-assistant

## Overview

Reviews the real diff: fetches the PR, scopes to changed hunks plus necessary context, and skips generated, vendored, and lockfile noise.

Security-first and evidence-based: every finding cites file:line, names a category and severity, explains impact, and proposes a fix — no vague nitpicks, no fabricated issues.

Defensive by policy: it never auto-approves changes to auth, crypto, payments, migrations, or infra; those are flagged and escalated to a human reviewer.

Cost-aware and CI-ready: model tiering, scoped context, and a hard file/line budget keep it cheap enough to run on every PR as a GitHub Action or CLI.

## When to use it

- You want a fast, consistent first-pass review on every pull request before a human looks.
- Your team cares about catching security and correctness regressions (injection, authz, race conditions, breaking API changes) early.
- You want review comments that are specific and actionable (file:line + fix), not generic 'consider refactoring' noise.
- You run CI and can add a GitHub Action or a pre-merge check that posts inline comments and a verdict.
- You want automation that knows its limits and routes risky changes to humans instead of rubber-stamping them.

## When not to use it

- You expect it to fully replace human review and merge unilaterally — it is a force multiplier and a gate, not the final authority on risky code.
- Your changes are dominated by binary assets or generated code where a diff review adds little.
- You cannot provide repository read access or run it in CI, which it needs for grounded, in-context review.
- You want it to execute untrusted PR code without a sandbox — that is disabled by default for good reason.

## Architecture

- **Diff acquisition & scoping** — Fetches the PR diff and the list of changed files, then filters out generated/vendored/minified/lockfile paths. Splits the remaining changes into hunks and enforces a file/line budget so cost stays bounded.
- **Context assembly** — For each changed hunk, pulls just enough surrounding code and the definitions of referenced symbols via codebase search — not whole files — so the model reviews with real context without blowing the token budget.
- **Static analysis pass** — Runs the repo's linter, type checker, and a SAST tool over the changed files. Deterministic findings are fed to the model as evidence so it can corroborate or prioritize, and so it never re-flags style the linter owns.
- **Reasoning & review engine** — The strong model reviews in the security-first priority order, applies the severity rubric, and emits grounded, file:line comments with fixes. Uncertain items become questions, not assertions.
- **Policy & escalation gate** — A deterministic gate inspects changed paths against protected areas (auth, crypto, payments, migrations, infra) and a secret-scanner. It forces escalate=true and caps the verdict for those, independent of the model's recommendation.
- **Publishing layer** — Posts inline comments and a summary verdict to the PR, sets a status check (pass/neutral/fail), and adds labels (e.g. security, needs-human). Idempotent: re-runs update prior bot comments instead of duplicating.
- **Observability & tuning** — Logs findings, verdicts, and whether humans agreed (resolved vs. dismissed). False-positive and dismissal rates drive prompt and threshold tuning over time.

## Files in this bundle

- `system-prompt.md` — the agent's system prompt
- `tools.json` — tool/function definitions the agent expects
- `workflow.md` — step-by-step run loop
- `.env.example` — environment variables to fill in
- `kit.json` — full structured metadata
- `starters/` — minimal starter snippets
- `LICENSE` — Apache-2.0 (code, configuration, and schema)
- `LICENSE-CONTENT` — CC BY 4.0 (specification text and documentation)
- `NOTICE` — attribution and trademark notice
- `run.py` — **runnable demo**: real agent loop with mock tools (`pip install anthropic`, set `ANTHROPIC_API_KEY`, `python run.py`)
- `agentaz.json` / `agentaz.schema.json` — AgentAz™ governance spec + schema

## Implementation notes

- Enforce the escalation gate deterministically from changed paths (auth, crypto, payments, migrations, infra) and a secret scanner — never let the model alone decide that a protected change is safe to approve.
- Feed real static-analysis/SAST output into the prompt as evidence. It grounds findings, prevents the model from re-flagging style the linter owns, and sharply reduces false positives.
- Scope hard: review changed hunks plus minimal symbol context, skip generated/vendored/lockfiles, and cap files/lines. For oversized PRs, review the riskiest files and recommend splitting rather than reviewing everything shallowly.
- Start non-blocking. Post comments and a neutral check first; only enable fail_on (BLOCKER/CRITICAL) once your dismissal/false-positive rate is low enough to trust as a gate.
- Make re-runs idempotent — update the bot's previous comments instead of stacking duplicates on every push.
- Track which findings humans resolve vs. dismiss. Dismissal rate per category is your tuning signal for thresholds and the ignore list.
- The actual reasoning-heavy review is what the strong model is for; a cheaper model can scope the diff and summarize static-analysis output.

## Variations

- **Basic — Inline PR comments:** Runs on each PR, posts grounded inline comments and a summary as a non-blocking check. Static analysis optional. The simplest way to add a consistent first-pass reviewer.
- **Advanced — Gating review with static analysis:** Integrates the repo's linter/type-checker/SAST as evidence, enforces the protected-path escalation gate, and fails the check on BLOCKER/CRITICAL findings so risky PRs cannot merge without changes.
- **Enterprise — Governed org-wide reviewer:** Adds per-repo policies and CODEOWNERS-aware routing, sandboxed test execution, secret-scanning enforcement, full audit logs of findings and human outcomes, and a tuning loop that adjusts thresholds from dismissal rates across the org.

## FAQ

**Does it replace human reviewers?**

No — it is a high-quality first pass and a safety gate. It handles the consistent, tireless checks (security patterns, N+1s, missing tests, breaking changes) and explicitly escalates anything touching auth, crypto, payments, migrations, or infra to a human.

**How does it avoid noisy, useless comments?**

It is told to prefer signal over noise: it won't comment on what your formatter/linter already enforces, it groups trivial nits, and every real finding must cite file:line with concrete impact and a fix. Static-analysis evidence further cuts false positives.

**How does it not hallucinate vulnerabilities?**

Findings must be grounded in the actual diff with a specific location; uncertain items are raised as questions rather than assertions. It reviews only the code it can see and reports what it skipped.

**What stops it from approving something dangerous?**

A deterministic policy gate. Changes to protected paths or any detected secret force escalate=true and cap the verdict at request_changes/block, independent of the model's recommendation.

**Will it run my untrusted PR code?**

Not by default. Test execution is off unless you explicitly enable a sandbox. It relies on provided static-analysis and test results rather than executing arbitrary PR code.

**How do I keep CI cost reasonable?**

It scopes to changed hunks with minimal context, skips generated/vendored/lockfiles, caps files and lines, and uses model tiering — so a typical PR review is small and cheap enough to run on every push.


---

© 2026 AgentKits · www.agent-kits.com

**Open source.** Code, configuration, and the AgentAz™ schema are licensed under
**Apache-2.0**; specification text and documentation under **CC BY 4.0** (with
attribution to AgentKits, link to https://www.agent-kits.com). See LICENSE, LICENSE-CONTENT,
and NOTICE in this bundle. "AgentAz" and "AgentKits" are trademarks of AgentKits.

**Flagship reference blueprint.** View the source, AgentAz™ spec, and frozen v1.0 schema
in the public registry: https://github.com/agent-kits/agentaz
Original: https://agent-kits.com/kit/code-review-assistant
