README.md

Simple PR Review Workflow - Claude Code Integration

A straightforward code review workflow that leverages Claude Code's built-in GitHub integration to provide comprehensive pull request reviews with minimal complexity.

Overview

This workflow uses Claude Code's powerful built-in capabilities to analyze GitHub pull requests and generate detailed, actionable code reviews. Instead of complex multi-agent orchestration, it relies on Claude Code's natural understanding to provide comprehensive analysis covering:

• Code Quality & Best Practices - Structure, readability, design patterns
• Security Analysis - Vulnerability detection, authentication issues, data exposure
• Performance Considerations - Algorithmic efficiency, memory usage, scalability
• Documentation & Testing - Comment coverage, test quality, API documentation
• Overall Assessment - Summary findings and clear recommendations

Features

• ✅ Simple & Fast - Single command execution, results in seconds
• ✅ Comprehensive Analysis - Covers all aspects of code review automatically
• ✅ Claude Code Integration - Uses built-in GitHub access and intelligence
• ✅ Clean Output - Timestamped markdown files
• ✅ Flexible Usage - Supports custom instructions and different models
• ✅ No Complex Setup - Minimal dependencies, no API keys required

Installation

1. Install Claude Code CLI:

curl -fsSL https://claude.ai/install.sh | sh

2. Sign in to Claude Code:

claude auth

3. Install minimal dependencies (optional):

pip install -r requirements.txt  # Only needed for Python imports

Note: No additional API keys or complex configuration required. Claude Code handles GitHub authentication automatically.

Usage

Command Line Interface

# Basic PR review
python workflows/code_review/pr_reviewer.py 123

# Review PR in specific repository
python workflows/code_review/pr_reviewer.py 123 \
  --repository owner/repo

# Use different Claude model
python workflows/code_review/pr_reviewer.py 123 \
  --model opus

# Add custom review instructions
python workflows/code_review/pr_reviewer.py 123 \
  --instructions "Focus on security and performance"

# Enable verbose logging
python workflows/code_review/pr_reviewer.py 123 --verbose

Python API

from workflows.code_review.pr_reviewer import SimplePRReviewer

# Initialize reviewer
reviewer = SimplePRReviewer(model="sonnet")

# Perform review
review_content = reviewer.review_pr(
    pr_number=123,
    repository="owner/repo",  # optional
    custom_instructions="Focus on security"  # optional
)

# Save results
markdown_file = reviewer.save_review(
    pr_number=123,
    repository="owner/repo",
    review_content=review_content
)

print(f"Review saved to: {markdown_file}")

Workflow Process

1. Single Command Execution - Run the reviewer with PR number
2. Claude Code Analysis - Leverages built-in GitHub integration for comprehensive review
3. Intelligent Assessment - Natural language understanding covers all review aspects
4. File Generation - Creates timestamped markdown output file
5. Results Display - Shows file locations and quick preview

Output Files

The workflow generates a single markdown file per review:

pr_review_owner_repo_#123_20240106_143022.md    # Human-readable review

Example Output Structure

# Code Review: PR #123

**Repository:** owner/repo
**Review Date:** 2024-01-06 14:30:22
**Claude Model:** sonnet

---

## Code Quality Assessment
**Overall Score:** 8.2/10
**Recommendation:** APPROVE WITH SUGGESTIONS

### Strengths
- Well-structured architecture with clear separation of concerns
- Good use of type hints and error handling
- Follows Python best practices

### Issues Found
1. **Security - Medium**: Potential SQL injection vulnerability in user_service.py:45
2. **Performance - Low**: Inefficient string concatenation in report_generator.py:123

### Recommendations
- Use parameterized queries for database operations
- Consider using f-strings for better performance
- Add unit tests for the new authentication logic

---
*Generated by Claude Code Simple PR Reviewer*

Command Line Arguments

Argument	Required	Description	Example
pr_number	Yes	Pull request number to review	123
--repository	No	Repository in format owner/repo	--repository anthropics/claude-code
--model	No	Claude model to use (default: sonnet)	--model opus
--instructions	No	Additional review instructions	--instructions "Focus on security"
--verbose	No	Enable verbose logging	--verbose

Supported Models

• sonnet (default) - Fast, comprehensive analysis
• opus - Most thorough analysis for complex PRs

Performance Characteristics

PR Size	Lines Changed	Review Time	Typical Use Case
Small	<100	5-15s	Bug fixes, small features
Medium	100-500	15-30s	Feature additions, refactoring
Large	500-1000	30-60s	Major features, architectural changes
XL	>1000	1-2min	Large refactors, new modules

Error Handling

The workflow includes robust error handling for:

• Claude Code Failures - Detailed error messages with troubleshooting tips
• GitHub Access Issues - Clear instructions for authentication
• Timeout Handling - 10-minute timeout for large PRs
• Invalid Arguments - Helpful usage information

Troubleshooting

Common Issues

1. Claude Code Not Installed

   # Install Claude Code
   curl -fsSL https://claude.ai/install.sh | sh
   
   # Verify installation
   claude --version

2. Authentication Issues

   # Sign in to Claude Code
   claude auth
   
   # Verify GitHub access
   claude "List my recent GitHub repositories"

3. Permission Errors

   • Ensure you have access to the repository
   • Check that Claude Code has GitHub permissions
   • Verify the PR number exists

4. Timeout Issues

   # Use faster model for large PRs
   python pr_reviewer.py 123 --model haiku

Debug Mode

# Enable detailed logging
python pr_reviewer.py 123 --verbose

# Test with simple command
claude "Review PR #123 in this repository"

License

This workflow is part of the agent-flows project and follows the same licensing terms.