code-review

name	code-review
description	Automated PR and code reviewer guidelines

Code Reviewer

Overview

Code Review Plugin

Automated code review for pull requests using multiple specialized agents with confidence-based scoring to filter false positives.

Overview

The Code Review Plugin automates pull request review by launching multiple agents in parallel to independently audit changes from different perspectives. It uses confidence scoring to filter out false positives, ensuring only high-quality, actionable feedback is posted.

Commands

code-review

Performs automated code review on a pull request using multiple specialized agents.

What it does:

1. Checks if review is needed (skips closed, draft, trivial, or already-reviewed PRs)
2. Gathers relevant CLAUDE.md guideline files from the repository
3. Summarizes the pull request changes
4. Launches 4 parallel agents to independently review:
   • Agents #1 & #2: Audit for CLAUDE.md compliance
   • Agent #3: Scan for obvious bugs in changes
   • Agent #4: Analyze git blame/history for context-based issues
5. Scores each issue 0-100 for confidence level
6. Filters out issues below 80 confidence threshold
7. Outputs review (to terminal by default, or as PR comment with --comment flag)

Usage:

/code-review [--comment]

Options:

• --comment: Post the review as a comment on the pull request (default: outputs to terminal only)

Example workflow:

# On a PR branch, run locally (outputs to terminal):
/code-review

# Post review as PR comment:
/code-review --comment

# Claude will:
# - Launch 4 review agents in parallel
# - Score each issue for confidence
# - Output issues ≥80 confidence (to terminal or PR depending on flag)
# - Skip if no high-confidence issues found

Features:

• Multiple independent agents for comprehensive review
• Confidence-based scoring reduces false positives (threshold: 80)
• CLAUDE.md compliance checking with explicit guideline verification
• Bug detection focused on changes (not pre-existing issues)
• Historical context analysis via git blame
• Automatic skipping of closed, draft, or already-reviewed PRs
• Links directly to code with full SHA and line ranges

Review comment format:

## Code review

Found 3 issues:

1. Missing error handling for OAuth callback (CLAUDE.md says "Always handle OAuth errors")

https://github.com/owner/repo/blob/abc123.../src/auth.ts#L67-L72

2. Memory leak: OAuth state not cleaned up (bug due to missing cleanup in finally block)

https://github.com/owner/repo/blob/abc123.../src/auth.ts#L88-L95

3. Inconsistent naming pattern (src/conventions/CLAUDE.md says "Use camelCase for functions")

https://github.com/owner/repo/blob/abc123.../src/utils.ts#L23-L28

Confidence scoring:

• 0: Not confident, false positive
• 25: Somewhat confident, might be real
• 50: Moderately confident, real but minor
• 75: Highly confident, real and important
• 100: Absolutely certain, definitely real

False positives filtered:

• Pre-existing issues not introduced in PR
• Code that looks like a bug but isn't
• Pedantic nitpicks
• Issues linters will catch
• General quality issues (unless in CLAUDE.md)
• Issues with lint ignore comments

Installation

This plugin is included in the coding assistant repository. The command is automatically available when using coding assistant.

Best Practices

Using code-review

• Maintain clear CLAUDE.md files for better compliance checking
• Trust the 80+ confidence threshold - false positives are filtered
• Run on all non-trivial pull requests
• Review agent findings as a starting point for human review
• Update CLAUDE.md based on recurring review patterns

When to use

• All pull requests with meaningful changes
• PRs touching critical code paths
• PRs from multiple contributors
• PRs where guideline compliance matters

When not to use

• Closed or draft PRs (automatically skipped anyway)
• Trivial automated PRs (automatically skipped)
• Urgent hotfixes requiring immediate merge
• PRs already reviewed (automatically skipped)

Workflow Integration

Standard PR review workflow:

# Create PR with changes
# Run local review (outputs to terminal)
/code-review

# Review the automated feedback
# Make any necessary fixes

# Optionally post as PR comment
/code-review --comment

# Merge when ready

As part of CI/CD:

# Trigger on PR creation or update
# Use --comment flag to post review comments
/code-review --comment
# Skip if review already exists

Requirements

• Git repository with GitHub integration
• GitHub CLI (gh) installed and authenticated
• CLAUDE.md files (optional but recommended for guideline checking)

Troubleshooting

Review takes too long

Issue: Agents are slow on large PRs

Solution:

• Normal for large changes - agents run in parallel
• 4 independent agents ensure thoroughness
• Consider splitting large PRs into smaller ones

Too many false positives

Issue: Review flags issues that aren't real

Solution:

• Default threshold is 80 (already filters most false positives)
• Make CLAUDE.md more specific about what matters
• Consider if the flagged issue is actually valid

No review comment posted

Issue: code-review runs but no comment appears

Solution: Check if:

• PR is closed (reviews skipped)
• PR is draft (reviews skipped)
• PR is trivial/automated (reviews skipped)
• PR already has review (reviews skipped)
• No issues scored ≥80 (no comment needed)

Link formatting broken

Issue: Code links don't render correctly in GitHub

Solution: Links must follow this exact format:

https://github.com/owner/repo/blob/[full-sha]/path/file.ext#L[start]-L[end]

• Must use full SHA (not abbreviated)
• Must use #L notation
• Must include line range with at least 1 line of context

GitHub CLI not working

Issue: gh commands fail

Solution:

• Install GitHub CLI: brew install gh (macOS) or see GitHub CLI installation
• Authenticate: gh auth login
• Verify repository has GitHub remote

Tips

• Write specific CLAUDE.md files: Clear guidelines = better reviews
• Include context in PRs: Helps agents understand intent
• Use confidence scores: Issues ≥80 are usually correct
• Iterate on guidelines: Update CLAUDE.md based on patterns
• Review automatically: Set up as part of PR workflow
• Trust the filtering: Threshold prevents noise

Configuration

Adjusting confidence threshold

The default threshold is 80. To adjust, modify the command file at commands/code-review.md:

Filter out any issues with a score less than 80.

Change 80 to your preferred threshold (0-100).

Customizing review focus

Edit commands/code-review.md to add or modify agent tasks:

• Add security-focused agents
• Add performance analysis agents
• Add accessibility checking agents
• Add documentation quality checks

Technical Details

Agent architecture

• 2x CLAUDE.md compliance agents: Redundancy for guideline checks
• 1x bug detector: Focused on obvious bugs in changes only
• 1x history analyzer: Context from git blame and history
• Nx confidence scorers: One per issue for independent scoring

Scoring system

• Each issue independently scored 0-100
• Scoring considers evidence strength and verification
• Threshold (default 80) filters low-confidence issues
• For CLAUDE.md issues: verifies guideline explicitly mentions it

GitHub integration

Uses gh CLI for:

• Viewing PR details and diffs
• Fetching repository data
• Reading git blame and history
• Posting review comments

Author

Boris Cherny ([e-mail])

Version

1.0.0

Commands / Workflows

Command: code-review

Description: Code review a pull request

Provide a code review for the given pull request.

Agent assumptions (applies to all agents and subagents):

• All tools are functional and will work without error. Do not test tools or make exploratory calls. Make sure this is clear to every subagent that is launched.
• Only call a tool if it is required to complete the task. Every tool call should have a clear purpose.

To do this, follow these steps precisely:

1. Launch a fast lightweight agent to check if any of the following are true:

   • The pull request is closed
   • The pull request is a draft
   • The pull request does not need code review (e.g. automated PR, trivial change that is obviously correct)
   • Claude has already commented on this PR (check gh pr view <PR> --comments for comments left by claude)

   If any condition is true, stop and do not proceed.

Note: Still review Claude generated PR's.

2. Launch a fast lightweight agent to return a list of file paths (not their contents) for all relevant CLAUDE.md files including:

   • The root CLAUDE.md file, if it exists
   • Any CLAUDE.md files in directories containing files modified by the pull request

3. Launch a standard agent to view the pull request and return a summary of the changes

4. Launch 4 agents in parallel to independently review the changes. Each agent should return the list of issues, where each issue includes a description and the reason it was flagged (e.g. "CLAUDE.md adherence", "bug"). The agents should do the following:

   Agents 1 + 2: CLAUDE.md compliance standard agents Audit changes for CLAUDE.md compliance in parallel. Note: When evaluating CLAUDE.md compliance for a file, you should only consider CLAUDE.md files that share a file path with the file or parents.

   Agent 3: high-capability agent (parallel subagent with agent 4) Scan for obvious bugs. Focus only on the diff itself without reading extra context. Flag only significant bugs; ignore nitpicks and likely false positives. Do not flag issues that you cannot validate without looking at context outside of the git diff.

   Agent 4: high-capability agent (parallel subagent with agent 3) Look for problems that exist in the introduced code. This could be security issues, incorrect logic, etc. Only look for issues that fall within the changed code.

   CRITICAL: We only want HIGH SIGNAL issues. Flag issues where:

   • The code will fail to compile or parse (syntax errors, type errors, missing imports, unresolved references)
   • The code will definitely produce wrong results regardless of inputs (clear logic errors)
   • Clear, unambiguous CLAUDE.md violations where you can quote the exact rule being broken

   Do NOT flag:

   • Code style or quality concerns
   • Potential issues that depend on specific inputs or state
   • Subjective suggestions or improvements

   If you are not certain an issue is real, do not flag it. False positives erode trust and waste reviewer time.

   In addition to the above, each subagent should be told the PR title and description. This will help provide context regarding the author's intent.

5. For each issue found in the previous step by agents 3 and 4, launch parallel subagents to validate the issue. These subagents should get the PR title and description along with a description of the issue. The agent's job is to review the issue to validate that the stated issue is truly an issue with high confidence. For example, if an issue such as "variable is not defined" was flagged, the subagent's job would be to validate that is actually true in the code. Another example would be CLAUDE.md issues. The agent should validate that the CLAUDE.md rule that was violated is scoped for this file and is actually violated. Use high-capability subagents for bugs and logic issues, and standard agents for CLAUDE.md violations.

Use this list when evaluating issues in Steps 4 and 5 (these are false positives, do NOT flag):

• Pre-existing issues
• Something that appears to be a bug but is actually correct
• Pedantic nitpicks that a senior engineer would not flag
• Issues that a linter will catch (do not run the linter to verify)
• General code quality concerns (e.g., lack of test coverage, general security issues) unless explicitly required in CLAUDE.md
• Issues mentioned in CLAUDE.md but explicitly silenced in the code (e.g., via a lint ignore comment)

Notes:

• Use gh CLI to interact with GitHub (e.g., fetch pull requests, create comments). Do not use web fetch.
• Create a todo list before starting.
• You must cite and link each issue in inline comments (e.g., if referring to a CLAUDE.md, include a link to it).
• If no issues are found and --comment argument is provided, post a comment with the following format:

---

Code review

No issues found. Checked for bugs and CLAUDE.md compliance.

---

• When linking to code in inline comments, follow the following format precisely, otherwise the Markdown preview won't render correctly: https://github.com/anthropics/coding-assistant/blob/c21d3c10bc8e898b7ac1a2d745bdc9bc4e423afe/package.json#L10-L15
  • Requires full git sha
  • You must provide the full sha. Commands like https://github.com/owner/repo/blob/$(git rev-parse HEAD)/foo/bar will not work, since your comment will be directly rendered in Markdown.
  • Repo name must match the repo you're code reviewing

  • sign after the file name

  • Line range format is L[start]-L[end]
  • Provide at least 1 line of context before and after, centered on the line you are commenting about (eg. if you are commenting about lines 5-6, you should link to L4-7)

---

🔒 Pre-Execution Verification Gate

Before executing commands or submitting reviews, you MUST output a structured XML <verification_gate> block evaluating the following checks:

• conventions: All changes align with target guidelines. (PASS/FAIL)
• correctness: Verify code correctness and lack of logical bugs. (PASS/FAIL)

Example output format:

<verification_gate>
  <conventions>PASS</conventions>
  <correctness>PASS</correctness>
</verification_gate>

Do not proceed until you have output this verification gate.