Anatomy of AI Code Review Workflows

Beyond /review: gates, subagents, hooks, and PR-quality system.

Code Review

Beyond /review — the full PR-quality system: gates, subagents, hooks, and metrics. AI + automation + humans, layered to catch issues early, enforce quality, and ship with confidence.

TL;DR

A great review isn't a single /review call — it's a layered quality system.
Six layers: Pre-PR · CI · AI Static Analysis · Human Review · Merge Guardrails · Post-Merge.
Use subagents in parallel (@code-reviewer, @security-auditor, @test-writer, @docs-writer) and merge their outputs into one consolidated review.
Hooks shift left: pre-commit, pre-push, pre-merge — each one is a cheap insurance policy.
Measure what matters: cycle time, acceptance rate, defect escape rate, AI suggestion adoption.

Why this matters

A PR is the last cheap moment to catch a defect. Once it's in main, every bug costs 10–100× more. The job of an AI code review workflow isn't to replace humans — it's to make every gate fast, consistent, and unmissable so humans spend their time on judgment, not nits.

Bottom line: Quality is never an accident. It's the result of intelligent effort — codified once, automated forever.

The Big Picture

Think in layers: Prevent → Detect → Explain → Validate → Approve → Learn.

💡 Tip: Shift left as much as possible. Catch issues before human review.

Quality Gates Overview

Gate	When	Who/What	Purpose	Fail action
💻 Pre-PR (Local)	Before push	Hooks + local scripts	Catch issues fast (lint, test, secrets)	Block commit / push
🛠️ CI / Build	On PR push	CI pipeline	Build, test, typecheck, security scans	Block PR
🤖 AI Static Analysis	On PR	AI subagents	Deep code analysis, patterns, risks	Add review comments
👥 Human Review	On PR	Peer reviewer	Context, intent, design, trade-offs	Request changes
🔒 Merge Guardrails	Pre-merge	Checks + Hooks	Final sanity before merge	Block merge
🚀 Post-Merge	After merge	CI + monitoring	Deploy, smoke tests, alerting	Rollback / alert

💡 Tip: Each gate has a specific job. Don't overload a single gate.

Recommended Gate Configuration

✅ Pre-PR (Local) — Pre-commit hooks: lint, format, tests, secret scan
✅ CI / Build — Typecheck, unit tests, coverage, build
✅ AI Static Analysis — @code-reviewer + @security-auditor
✅ Human Review — Context, product fit, design, readability
✅ Merge Guardrails — Status checks, approvals, branch protection
✅ Post-Merge — Deploy checks, smoke tests, alerting

💡 Tip: Configure branch protection to enforce the gates — not just describe them.

End-to-End PR Workflow (detailed)

#	Step	Key actions	Output
1	Developer creates branch	`git checkout -b feat/awesome`; small, intent-clear commits	Clean commits
2	Pre-PR (local) — shift left	Pre-commit hooks: lint, format, tests, secrets; fix locally	Clean local state
3	Push & open PR	Push branch; open PR with good title & description; add screenshots if needed	PR opened with context
4	CI / automated gates	Build, typecheck, unit tests, coverage, security scans (SAST, deps); optional: e2e, perf, accessibility	Green/Red status checks
5	AI analysis (subagents)	`@code-reviewer` (quality, bugs, improvements), `@security-auditor` (vulns, secrets), `@test-writer` (missing tests, edge cases), `@docs-writer` (doc changes)	AI review comments
6	Human review	Peer reviews context & intent, design, trade-offs, readability; iterates with author	Approved or changes requested
7	Merge guardrails	Branch protection: required checks, approvals (1–2 reviewers), no stale branches	Ready to merge
8	Post-merge	Deploy / preview checks; smoke & integration tests; monitor and alert on failures	Healthy production

💡 Tip: Automate what you can. Escalate to humans where consolidated judgment is needed.

Subagents in the Code Review Workflow

Run subagents in parallel. Merge their outputs into one consolidated review.

Subagent	Focus	Key tools	Output
🤖 `@code-reviewer`	Code quality, bugs & edge cases, readability, performance	Read, Grep, Bash	Review report
🛡️ `@security-auditor`	Vulnerabilities, secrets, auth & access, dependencies	Read, Bash, Web	Risk report
🧪 `@test-writer`	Missing tests, edge cases, coverage gaps, test quality	Read, Bash	Tests + plan
📚 `@docs-writer`	API changes, README updates, changelogs, examples	Read, Edit	Docs diff

Example fan-out

💡 Tip: Each agent has a clear scope. Keep prompts focused; merge outputs into one PR comment to reduce noise.

Hooks That Power the Flows

Event	Runs	Example use	Fail action
Pre-commit	Before commit	Lint, format, tests, secret scan	Block commit
Pre-push	Before push	Run fast tests, typecheck	Block push
Post-push	After push	Notify PR, run extra checks	Non-blocking
Pre-PR	On PR open	Label PR, size check, template check	Add comment
Post-PR	On PR update	Run AI agents, update review	Add comment
Pre-merge	Before merge	Final checks, approve gates	Block merge
Post-merge	After merge	Deploy, smoke tests, monitoring	Alert / rollback

💡 Tip: Keep hooks fast (< 5s) and idempotent.

Sample `.claude/settings.json` hook block

{
  "hooks": {
    "PreToolUse": [
      { "matcher": "*", "hooks": [{ "type": "command", "command": "./scripts/pre-tool.sh" }] }
    ],
    "PostToolUse": [
      { "matcher": "Write|Edit",
        "hooks": [
          { "type": "command", "command": "npm run lint" },
          { "type": "command", "command": "npm test --silent" }
        ] }
    ],
    "PreCommit": [
      { "matcher": "*",
        "hooks": [
          { "type": "command", "command": "./scripts/secret-scan.sh" },
          { "type": "command", "command": "./scripts/format-check.sh" }
        ] }
    ]
  }
}

Code Review Report Template

A consistent format = faster reviews + better decisions.

## Summary
Short summary of the PR.

## Risks & Issues

### 🔴 Critical
- SQL injection risk in `src/users.ts:42`

### 🟡 Medium
- Missing null check in `src/auth.ts:91`

### 🟢 Low
- Unused variable in `src/utils.ts:23`

## Missing Tests
- Login with invalid credentials
- Rate limiting on /login

## Suggestions (file:line)
- Parameterize queries in `src/users.ts:42`
- Add guard clause for null user in `src/auth.ts:91`
- Remove unused variable in `src/utils.ts:23`

Review checklist (used by every reviewer)

✅ Security & secrets
✅ Correctness
✅ Edge cases
✅ Performance
✅ Tests & coverage
✅ Docs & changelog
✅ Readability
✅ Conventions

Decision

✅ Approve
✏️ Request changes
⛔ Block

💡 Tip: Codify the format inside agents/code-reviewer.yml so every AI review looks the same.

Branch Protection & Required Checks

.github/branch-protection.yml:

main:
  required_status_checks:
    strict: true
    contexts:
      - build
      - test
      - lint
      - code-reviewer
  required_pull_request_reviews:
    required_approving_review_count: 1
    require_code_owner_reviews: true
  enforce_admins: true
  restrictions: {}

Checklist:

✅ All status checks green
✅ At least 1 approval
✅ No stale reviews
✅ No force push
✅ Linear history
✅ Signed commits (optional)

💡 Tip: Automate enforcement. Don't rely on memory.

PR Template (starter)

.github/pull_request_template.md:

## Summary
What and why?
-

## Testing
- [ ] Unit tests
- [ ] Integration tests
- [ ] Manual tests

## Screenshots / Demos (if UI)

## Checklist
- [ ] Code reviewed
- [ ] Tests added/updated
- [ ] Docs updated (if needed)
- [ ] Changelog updated
- [ ] No secrets

## Related Issue
Closes #123

💡 Tip: A good template = fewer back-and-forths.

Metrics That Matter

Track these weekly to optimize the system, not just individuals.

Metric	Target	Why
⏱️ PR cycle time	< 24 h	Speed of delivery
✅ PR acceptance rate	> 85%	Quality of work
🛡️ Defect escape rate	< 5%	Real-world quality
🗣️ Review turnaround	< 6 h	Team responsiveness
🤖 AI suggestion adoption	> 60%	AI effectiveness
🔁 Rework rate	< 15%	Process health
📈 Coverage	≥ 80%	Test confidence

💡 Tip: Review metrics weekly. Optimize the system, not just the people.

Step-by-Step Setup

1. Set up branch protection

Apply .github/branch-protection.yml (above) to main and release/*.

2. Ship the AI review subagents

agents/code-reviewer.yml
agents/security-auditor.yml
agents/test-writer.yml
agents/docs-writer.yml

3. Add a `/review` slash command (fan-out)

.claude/commands/review.md:

---
description: Full PR review — fan-out to all reviewer subagents
usage: /review [--base <branch>] [--scope <path>]
arguments:
  - name: base
    default: main
permissions:
  allow: ["Read", "Bash(git *)", "Bash(npm test)", "WebSearch"]
  deny:  ["Write", "Bash(rm -rf *)"]
---

# Instructions
Run the following subagents in parallel against the diff vs `{{base}}`:
1. `@code-reviewer`     — quality, correctness, edge cases
2. `@security-auditor`  — vulnerabilities, secrets
3. `@test-writer`       — missing tests, coverage gaps
4. `@docs-writer`       — docs & changelog impact

Merge their outputs into the Code Review Report Template:
- Summary
- Risks & Issues (Critical / Medium / Low)
- Missing Tests
- Suggestions (file:line)
- Decision

4. Configure pre-PR (local) hooks

hooks/pre-commit.sh:

#!/usr/bin/env bash
set -e
./scripts/secret-scan.sh
npm run lint -- --quiet
npx prettier --check .
npm test --silent

Wire it into .claude/settings.json and package.json prepare.

5. Add CI gates

.github/workflows/ci.yml (sketch):

name: CI
on: [pull_request]
jobs:
  build-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm run lint
      - run: npm run typecheck
      - run: npm test -- --coverage
      - uses: github/codeql-action/analyze@v3

6. Add a GitHub Action that runs the AI fan-out on PRs

.github/workflows/ai-review.yml (sketch):

name: AI Review
on: [pull_request]
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: claude /review --base origin/${{ github.base_ref }}
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

7. Monitor & alert

Send post-merge metrics + failures to your existing dashboards (Datadog, Grafana, Slack).

8. Review weekly

Hold a 30-min "PR-quality retro" each week. Improve one thing.

Variants for Different Team Settings

👤 Solo developer

Pre-commit + /review only.
Skip multi-reviewer requirement.
Auto-approve docs-only PRs.

👥 Small team (2–10)

Required: 1 human reviewer + AI fan-out.
Pre-commit + CI + /review PR comment.
Weekly PR-quality retro.

🏢 Enterprise / regulated

Required: 2 reviewers (1 owner), AI fan-out, security scans, compliance check.
Mandatory: signed commits, SBOM, change ticket linkage.
Post-merge: canary, smoke tests, audit log.
Block on any 🔴 critical AI finding until acknowledged.

🌍 Open-source / community

Maintainers' bot runs /review automatically on new PRs.
Provide a contributor guide with PR template + DoD.
Triage label workflow + AI suggestion to assign reviewer.

Bottom line: Same gates, escalating strictness.

Common Patterns & Recipes

Pattern 1 — Parallel fan-out, single consolidated comment

Pattern 2 — Risk-tiered routing

If diff_lines > 500 OR touches src/auth/** :
    add reviewer @security-team
    require 2 approvals

Pattern 3 — Auto-fix small nits

"PostToolUse": [
  { "matcher": "Write|Edit",
    "hooks": [{ "type": "command", "command": "npx prettier --write ." }] }
]

Pattern 4 — Severity-based block

🔴 Critical → block merge until acknowledged
🟡 Medium → require explanation
🟢 Low → suggestion only

Pattern 5 — Self-review pre-push

Before pushing, /review --base main on YOUR local branch.
Fix what AI flags. Then push.

Pattern 6 — Reviewer "explainer" mode

For files you don't own, ask /explain <file> first.
Then review with context.

Pattern 7 — Post-merge regression watch

# scripts/post-merge.sh
npm run smoke || ./scripts/notify-slack.sh "🔴 Post-merge smoke failed"

Best Practices ✅

🛡️ Shift left — prevent issues at commit, not at merge.
⚡ Automate everything that has a clear rule.
🤝 Keep humans for judgment — design, trade-offs, intent.
🤖 Run AI subagents in parallel — and merge into one comment.
📐 Standard report format — same shape every time.
⏱️ Keep hooks fast (< 5s).
📈 Measure & iterate weekly.
🎯 Optimize the system, not the individual.

Anti-Patterns to Avoid ❌

🚫 Huge PRs (> 500 lines).
🚫 No tests / low coverage.
🚫 Skipping code review.
🚫 AI-only approval for risky changes.
🚫 No context in PR (bad title, no description).
🚫 Vague commit messages ("fix stuff").
🚫 Ignoring CI failures.
🚫 Secrets in code or logs.

⚠️ Bad habits here cost real money and real trust.

Troubleshooting

Symptom	Cause	Fix
Reviews take days	No SLA, no rotation	Set a 24-h review SLA + reviewer rotation
AI comments are noise	Vague subagent prompts	Tighten `system_prompt` + few-shots
Critical bugs slip through	No `@security-auditor`	Add it to the fan-out
Reviewers fatigue	Huge PRs	Cap PR size; require small batches
Same nits every PR	Not auto-fixing	Add auto-format hook on save
Tests skipped	No coverage gate	Block merge below threshold
Post-merge failures	No smoke tests	Add post-merge smoke + alert
Metrics flat	Not reviewing weekly	Add 30-min PR-quality retro

Quick-Start Checklist

✅ Branch protection on main
✅ Pre-commit hooks (lint, format, tests, secret scan)
✅ CI: typecheck, tests, coverage, security
✅ /review fan-out (4 subagents)
✅ Standard PR + review report templates
✅ Weekly PR-quality retro
✅ Dashboards for the 7 metrics

🧠 Mantra: Prevent early · Automate smartly · Augment humans · Measure everything.

Starter Configs

`agents/code-reviewer.yml`

name: code-reviewer
description: Reviews PRs for quality, correctness, and readability.
model: claude-sonnet-4
tools: [Read, Bash, Grep]
permissions:
  allow: ["Read", "Bash(npm test)"]
  deny:  ["WriteOutsideWorkspace"]
system_prompt: |
  You are a strict senior reviewer. Follow CLAUDE.md.
  Output the Code Review Report Template exactly.
  Be concrete: every issue has a file:line and a fix.
triggers: ["review", "pr", "audit", "quality"]
timeout_ms: 120000
max_tokens: 8000

`agents/security-auditor.yml`

name: security-auditor
description: Finds vulnerabilities, secrets, auth/access issues.
model: claude-sonnet-4
tools: [Read, Bash, WebSearch]
permissions:
  allow: ["Read", "WebSearch"]
  deny:  ["Write", "Bash(rm -rf *)"]
system_prompt: |
  You are a security engineer. Focus on:
  - OWASP Top 10
  - Secrets in code/logs
  - Authn/Authz issues
  - Risky dependencies
  Output severity (Critical/Medium/Low) + file:line + suggested fix.
triggers: ["security", "vulnerability", "secret", "audit"]

`agents/test-writer.yml`

name: test-writer
description: Finds missing tests and writes them.
model: claude-sonnet-4
tools: [Read, Bash, Edit]
permissions: { allow: ["Read", "Edit", "Bash(npm test)"] }
system_prompt: |
  Identify missing tests and edge cases.
  Propose specific tests (Given/When/Then).
  Where useful, draft them inline.
triggers: ["test", "coverage", "missing tests"]

`agents/docs-writer.yml`

name: docs-writer
description: Suggests docs/changelog updates required by this PR.
model: claude-haiku-4
tools: [Read, Edit]
permissions: { allow: ["Read", "Edit"] }
system_prompt: |
  Identify API or behavior changes that need:
  - README updates
  - API doc updates
  - Changelog entries
  Output a docs diff plan.
triggers: ["docs", "readme", "changelog"]

Glossary

Gate — A check that must pass before code can progress.
Shift left — Move quality checks earlier in the dev process.
Branch protection — Repo rules that prevent unsafe merges.
SAST — Static Application Security Testing.
SBOM — Software Bill of Materials.
Defect escape rate — % of bugs that reach production despite reviews.
AI suggestion adoption — % of AI proposals accepted by reviewers.
Cycle time — Time from PR open → merge.
Severity tiers — Critical / Medium / Low classification.

🪙 Golden Rules

🛡️ Small PRs.
🧹 Clean main.
🧪 Tests first.
🔒 No secrets.
🚀 Ship safe.

Remember: "Quality is never an accident. It is always the result of intelligent effort." — John Ruskin

TL;DR​

Why this matters​

The Big Picture​

Quality Gates Overview​

Recommended Gate Configuration​

End-to-End PR Workflow (detailed)​

Subagents in the Code Review Workflow​

Example fan-out​

Hooks That Power the Flows​

Sample .claude/settings.json hook block​

Code Review Report Template​

Review checklist (used by every reviewer)​

Decision​

Branch Protection & Required Checks​

PR Template (starter)​

Metrics That Matter​

Step-by-Step Setup​

1. Set up branch protection​

2. Ship the AI review subagents​

3. Add a /review slash command (fan-out)​

4. Configure pre-PR (local) hooks​

5. Add CI gates​

6. Add a GitHub Action that runs the AI fan-out on PRs​

7. Monitor & alert​

8. Review weekly​

Variants for Different Team Settings​

👤 Solo developer​

👥 Small team (2–10)​

🏢 Enterprise / regulated​

🌍 Open-source / community​

Common Patterns & Recipes​

Pattern 1 — Parallel fan-out, single consolidated comment​

Pattern 2 — Risk-tiered routing​

Pattern 3 — Auto-fix small nits​

Pattern 4 — Severity-based block​

Pattern 5 — Self-review pre-push​

Pattern 6 — Reviewer "explainer" mode​

Pattern 7 — Post-merge regression watch​

Best Practices ✅​

Anti-Patterns to Avoid ❌​

Troubleshooting​

Quick-Start Checklist​

Starter Configs​

agents/code-reviewer.yml​

agents/security-auditor.yml​

agents/test-writer.yml​

agents/docs-writer.yml​

Glossary​

Further Reading​

🪙 Golden Rules​