🤖 AI Code Reviewer

AI-powered GitHub Pull Request code review tool that helps developers improve review efficiency and quality through intelligent analysis.

🎓 学习项目（portfolio / learning project） —— CLI 工具链核心已完成（PR 拉取 → 分块 → LLM 审查 → 三格式报告）；Roadmap 中的「内联 PR 评论」「GitHub Actions 集成」为规划项，尚未实现。

Features

📋 PR Change Summary — Understand what a PR does at a glance
🔍 Risk Code Identification — Detect security issues, bugs, performance problems, and maintainability concerns
💡 Review Suggestions — Get actionable, specific recommendations with code examples
🎯 Severity & Confidence Scoring — Prioritize findings by impact and reliability
📊 Multiple Output Formats — Terminal, Markdown, JSON
⚡ Smart Chunking — Handles large PRs by intelligently splitting diffs

Quick Start

1. Install

pip install -r requirements.txt
pip install -e .

2. Configure

Set required API keys:

export ANTHROPIC_API_KEY="sk-ant-..."
export GITHUB_TOKEN="ghp_..."

Create your GitHub token at https://github.com/settings/tokens (needs repo or public_repo scope).

3. Run

# Basic usage
ai-review https://github.com/owner/repo/pull/123

# Short format
ai-review owner/repo#123

# Deep review with Opus model for critical PRs
ai-review owner/repo#123 --depth deep --model opus

# Quick first pass
ai-review owner/repo#123 --depth quick --model haiku

# Generate markdown report
ai-review owner/repo#123 --format markdown -o review-report.md

# Machine-readable JSON output
ai-review owner/repo#123 --format json -o review.json

Usage

usage: ai-review [-h] [--model {haiku,sonnet,opus}] [--depth {quick,standard,deep}]
                 [--output FILE] [--format {terminal,markdown,json}]
                 [--no-color] [--verbose] [--version]
                 PR_URL

Options

Option	Description
`--model`, `-m`	AI model: `haiku` (fast), `sonnet` (balanced, default), `opus` (thorough)
`--depth`, `-d`	Review depth: `quick` (summary+critical), `standard` (default), `deep` (exhaustive)
`--output`, `-o`	Save report to file
`--format`, `-f`	Output format: `terminal`, `markdown`, `json`
`--verbose`, `-v`	Show detailed progress
`--no-security`	Skip security analysis
`--no-bugs`	Skip bug analysis
`--no-performance`	Skip performance analysis

Output Example

╔══════════════════════════════════════════════════════════════════════╗
║  🤖 AI Code Review Report                                           ║
║  PR #42: Add user authentication middleware                         ║
║  by johndoe  |  12 files  |  +245/-89                              ║
╚══════════════════════════════════════════════════════════════════════╝

📋 PR Summary
──────────────────────────────────────────────────
This PR introduces JWT-based authentication middleware...

🔍 Risk Analysis
──────────────────────────────────────────────────
  Found: 🔴 1 Critical, 🟡 3 Medium, 🟢 2 Low

  #1 🔴 CRITICAL 🔒 security
     Issue: JWT secret is hardcoded in config.py
     File: src/config.py
     Line: 15
     Fix: Move JWT_SECRET to environment variable...
     Confidence: high

💡 Review Suggestions
──────────────────────────────────────────────────
  #1 [MEDIUM] best-practice
     Title: Add rate limiting to auth endpoint
     ...

Design Document

1. Model Selection Strategy

Default: Claude Sonnet 5 (`claude-sonnet-5`)

Sonnet is the default choice because it offers the best quality/speed/cost balance for code review:

Code Understanding: Sonnet demonstrates strong comprehension of code semantics, control flow, and common patterns across major languages (Python, JavaScript, TypeScript, Go, Java, Rust, etc.)
Speed: Sub-second to few-second response times for typical diff chunks, enabling interactive review workflows
Context Window: 200K tokens — sufficient for processing multiple files with full diff context
Cost Efficiency: ~3x cheaper than Opus while maintaining high accuracy for the majority of review tasks

Optional: Claude Opus 5 (`claude-opus-5`)

Available via --model opus for critical review scenarios:

Security audits of authentication/authorization code
Financial transaction or data integrity logic
Infrastructure-as-code changes (Terraform, CloudFormation)
PRs exceeding 50 files or 2000+ lines changed

Opus provides deeper reasoning and fewer false negatives on subtle issues, at the cost of higher latency and token consumption.

Optional: Claude Haiku 4.5 (`claude-haiku-4-5-20251001`)

Available via --model haiku for quick triage:

First-pass filtering before human review
Small, focused PRs (< 5 files)
CI/CD pipeline integration where speed matters more than depth

Model Selection Decision Matrix

Scenario	Recommended Model	Rationale
Routine feature PR	Sonnet	Best quality/speed ratio
Security-sensitive change	Opus	Lower false negative rate
CI auto-review	Haiku	Speed + cost for bulk
Large refactor (50+ files)	Opus	Better large-context reasoning
First-pass triage	Haiku	Fast filtering, escalate to human

2. Context Acquisition Strategy

Multi-Layered Approach

The system uses a layered context strategy to maximize analysis quality while respecting model context limits:

Layer 1: PR Metadata (always included)
├── Title, description, author, branch info
├── File list with change statistics (+N/-N per file)
└── Labels, state, timestamps
      │
Layer 2: File-Level Diffs (primary analysis input)
├── Unified diff format with N lines of context
├── Grouped by semantic proximity (same module/directory)
└── Max ~25K tokens per chunk (configurable)
      │
Layer 3: Base Branch Context (on-demand)
├── Full file content fetched when diff alone is ambiguous
├── Used for understanding surrounding function/class context
└── Only fetched for files flagged as high-risk
      │
Layer 4: Cross-File References (future)
├── Import graph analysis
├── Call-site analysis for changed functions
└── Test coverage mapping

Chunking Algorithm

File Boundary Preservation: Chunks always split at file boundaries (never mid-diff)
Size-Constrained Grouping: Each chunk contains at most max_files_per_chunk (default: 5) files, staying under max_diff_size_bytes (default: 100KB ≈ 25K tokens)
Context Carry-Forward: PR metadata is repeated in each chunk's prompt for consistent analysis
Overflow Handling: Single files exceeding the size limit are analyzed independently with a "file too large" marker

Prompt Engineering for Context Efficiency

Structured Output Instructions: The model is guided to produce parseable markdown-structured output, avoiding verbose free-form responses
Negative Instructions: Explicit "do NOT fabricate" and confidence-rating requirements reduce hallucination
Progressive Disclosure: Phase 1 (summary) uses broad context → Phase 2 (risks) focuses on specific files → Phase 3 (suggestions) targets most-changed files

3. False Positive & False Negative Control

False Positive Reduction

Technique	Implementation
Confidence scoring	Every finding tagged `high`/`medium`/`low` confidence
Explicit anti-fabrication	System prompt instructs: "Only report REAL issues you can substantiate"
Severity triage	Critical/Medium/Low with color coding for visual filtering
Code snippet evidence	Findings include relevant code excerpts for human verification
Negative reinforcement	Model told "If code looks correct, say so rather than inventing issues"

False Negative Reduction

Technique	Implementation
Multi-phase analysis	Summary → Risk scan → Suggestions (each phase catches different issue types)
Diverse category coverage	Security, bugs, performance, maintainability each have dedicated prompt focus
Depth levels	`--depth deep` enables style and best-practice checks that standard mode skips
Model tiering	`--model opus` provides stronger reasoning for subtle issues
Context richness	Base-branch file content available for ambiguous diffs

Validation Strategy

The tool is designed to augment, not replace human review:

All findings include confidence levels so reviewers can prioritize
Code snippets enable quick human verification without context switching
The summary phase provides independent overview that can catch analysis errors

4. Response Speed & User Experience

Performance Design

Parallel-ready Architecture: The three analysis phases are independent and can be parallelized in future versions
Streaming output: Terminal output prints progressively as each phase completes
Configurable depth: Quick mode skips detailed suggestions for sub-second summary
Smart API retry: Exponential backoff with up to 3 retries for transient API failures

UX Decisions

Multiple PR URL formats: Accept full URLs, short owner/repo#N format, and owner/repo/pull/N
Progress indicators: Each phase announces itself with clear labels (📋 Phase 1/3, 🔍 Phase 2/3, 💡 Phase 3/3)
Color-coded severity: 🔴 Critical / 🟡 Medium / 🟢 Low for instant visual triage
Flexible output: Terminal for interactive use, Markdown for PR comments, JSON for CI integration

5. Future Extension Directions

Short-term (Next Iteration)

Inline PR Comments: Automatically post findings as GitHub PR review comments via API
Diff-to-File Mapping: Resolve diff line numbers to actual file line numbers for clickable references
Custom Rule Engine: Allow teams to define project-specific review rules and patterns
Review History: Track findings across PRs to identify recurring issues and team patterns
Caching Layer: Cache AI responses for identical diffs to reduce API costs

Medium-term

Test Coverage Analysis: Cross-reference changed code with test coverage data
Dependency Impact Analysis: Trace imports and call sites for breaking change detection
Language-Specific Detectors: Specialized analysis paths for Python, JS/TS, Go, Rust, Java
Learning from Feedback: Accept "useful/not-useful" ratings to tune future analysis
CI/CD Native Integration: GitHub Actions, GitLab CI, Jenkins plugins

Long-term Vision

Cross-PR Impact Analysis: Detect conflicts and semantic merge issues across open PRs
Architecture Drift Detection: Track whether changes align with documented architecture decisions
Team-Aware Reviews: Learn team conventions and coding standards over time
Multi-Reviewer Simulation: Use multiple AI perspectives (security engineer, performance engineer, etc.) for adversarial review

Architecture

ai-reviewer/
├── __init__.py          # Package metadata
├── cli.py               # CLI argument parsing and orchestration
├── config.py            # Configuration, prompts, model definitions
├── github_client.py     # GitHub REST API integration
├── analyzer.py          # AI analysis engine (Claude API + chunking)
└── reporter.py          # Multi-format report generation

Data Flow

User Input (PR URL)
       │
       ▼
┌─────────────────┐
│  CLI Parser      │  Parse args, build config
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  GitHub Client   │  Fetch PR metadata + file diffs
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Diff Chunker    │  Split into LLM-friendly chunks
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  AI Analyzer     │  Phase 1: Summary
│  (Claude API)    │  Phase 2: Risk Analysis
│                  │  Phase 3: Review Suggestions
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Reporter        │  Format & display results
└─────────────────┘

License

MIT

Name		Name	Last commit message	Last commit date
ai_reviewer		ai_reviewer
.env.example		.env.example
.gitignore		.gitignore
README.md		README.md
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt
题目要求.txt		题目要求.txt

Latest commit

History

Folders and files

Repository files navigation