Module 2: Automated Code Review on PRs

Overview

Module 1 put Claude Code inside GitHub Actions: a workflow runs on every PR, executes the agent, and produces some output. But that output is generic — a general analysis that lands as a comment or artifact. Now you raise the bar: you're going to set up Claude Code as a code review bot that comments inline on specific files in the PR, catches potential bugs with judgment, suggests concrete improvements, and validates the team's conventions.

This is the module that produces the most visible result of the whole guide. When you finish, every PR from your team will have automatic comments from an agent that understands the project's context, not just the syntax. It's the killer application of Claude Code in CI/CD: a reviewer that never gets tired, has no ego, and knows the team's conventions.

By the end of the 6 capsules, you'll have a working code review bot that comments inline on PRs, operates in suggest-only mode (it doesn't block merges until the team trusts it), handles large PRs with smart chunking, and applies the conventions specific to your codebase.

Where We Are in the Guide

Phase 1: Pre-Merge Automation (Modules 1-2)
├── Module 1: Claude Code in GitHub Actions ✅
└── Module 2: Automated Code Review on PRs ← YOU ARE HERE
    → Inline comments, context, suggest-only, conventions

Phase 2: Cross-Platform and Deployment (Modules 3-4)
├── Module 3: GitLab CI/CD and Headless SDK
└── Module 4: Deployment Automation

Phase 3: Resilience and Project (Modules 5-6)
├── Module 5: Security Scanning and Rollback
└── Module 6: Integrative Project — Complete Pipeline

This is Module 2 of 6. Module 1 gave you a working workflow that runs Claude Code; this module specializes it for code review and gives it the output any developer can see and use.

Code Review with Context, Not Linting

There's a central distinction that separates this module from a traditional linter:

LINTER (eslint, pylint, ruff):
→ Checks syntax and style rules
→ "Missing space after the comma"
→ "Unused variable"
→ Universal rules, with no project context
→ Useful but limited: it catches form, not substance

CLAUDE CODE AS A REVIEWER (this module):
→ Reads the diff and understands what changed
→ Reasons about the context: does this change break something?
→ "This new function doesn't handle the empty-input case,
   and according to UserService.create_user this is a valid input"
→ "The name createOrder is inconsistent — the rest of the
   module uses snake_case"
→ Rules with project context: it catches form AND substance

The linter says "this violates rule X". Claude Code says "this is going to break this specific case in your project". The difference is context.

A Real Task: Before and After

To anchor the module, consider a typical scenario for a team of 5 developers:

Team task: Every PR must go through code review before merge. The human reviewers are overloaded — there are PRs waiting 2-3 days for review.

Approach A: Human review only

Day 1, 09:00 → Developer opens PR with 200 modified lines
Day 1, 11:00 → Human reviewer assigned, but busy with something else
Day 2, 14:00 → Reviewer takes the PR. Spends 45 min understanding the change.
              Finds 3 issues:
              - Name inconsistent with the rest of the project
              - Missing input validation
              - An unparameterized query
              Comments on each one
Day 3, 10:00 → Developer applies fixes
Day 3, 14:00 → Re-review (another 30 min)
Day 3, 16:00 → Approve, merge

TOTAL HUMAN TIME: ~2.5 hours of reviewer
REAL TIME: 3 days from opening to merge

Approach B: Bot + Human review (this module)

Day 1, 09:00 → Developer opens PR with 200 modified lines
Day 1, 09:01 → Claude Code bot triggers automatically
Day 1, 09:03 → Bot leaves 3 inline comments:
              - Line 45: "The name createOrder doesn't follow
                the module's snake_case"
              - Line 67: "This function doesn't validate the
                empty-input case, see UserService.create_user
                as a reference"
              - Line 89: "This query uses string concatenation,
                vulnerable to SQL injection. Suggestion: use a
                parameterized query"
Day 1, 09:30 → Developer applies the 3 fixes (the issues the
              bot caught are obvious once pointed out)
Day 1, 10:00 → Bot re-triggers, all issues resolved
Day 1, 14:00 → Human reviewer takes the PR. Since the obvious
              issues are already resolved, they focus on what
              requires judgment: architecture, clarity of the
              solution, domain edge cases
Day 1, 14:20 → Approve (20 min of human reviewer)
Day 1, 14:25 → Merge

TOTAL HUMAN TIME: ~20 minutes of reviewer
REAL TIME: ~5 hours from opening to merge

Same PR. Same issues. Radically different result.

The difference isn't that the bot replaces the human — it's that the bot filters the obvious so the human focuses on what requires judgment. Human reviewer time: from 2.5h to 20 min. Total PR time: from 3 days to 5 hours.

Prerequisites

Required knowledge:

✅ Module 1 completed (working YAML workflow, secrets configured)
✅ Familiarity with GitHub PRs (how to open them, what a diff is, what an inline comment is)
✅ Write access to a repository where you can configure webhooks

NOT required:

❌ You don't need to have configured a GitHub bot before
❌ You don't need to know the GitHub REST/GraphQL API in depth

Module Roadmap

Capsule 01 — Module introduction (this capsule)

Code review with context vs a linter. The before/after scenario.

Capsule 02 — PR triggers and diff extraction

How to configure the workflow to run on specific PR events (opened, synchronize, ready_for_review). How to extract the diff and pass it to Claude Code efficiently.

Capsule 03 — Inline comments via the GitHub API

The difference between a general PR comment and an inline comment on a specific line. How to use the GitHub API (REST and GraphQL) to create inline comments. Handling tokens and permissions.

Capsule 04 — Review summary and suggest-only mode

How to generate a summary of the findings at the end of the review. Configuring the bot in suggest-only mode (it doesn't block merges) until the team gains confidence.

Capsule 05 — Customizing your team's conventions

How to pass the bot the conventions specific to your project: naming, file structure, accepted patterns. CLAUDE.md as the source of truth for conventions.

Capsule 06 — Handling large PRs

What to do when a PR has 50+ files or thousands of lines. Chunking strategies, prioritizing relevant files, and how to balance coverage vs cost.

Progression map

Capsule 01 (this)  → Why code review with context
Capsule 02         → Triggers + diff extraction
Capsule 03         → Inline comments (what the team sees)
Capsule 04         → Summary + suggest-only mode
Capsule 05         → Customization by conventions
Capsule 06         → Large PRs without blowing up costs

Difficulty: ⭐⭐ ────────────────▶ ⭐⭐⭐⭐

What You'll Achieve in This Module

By completing the 6 capsules, you'll be able to:

Configure PR triggers that fire the bot only when it's relevant
Extract and process diffs of PRs without overloading the context window
Generate inline comments on specific lines using the GitHub API
Produce review summaries that condense the findings into one view
Operate the bot in suggest-only mode to gradually gain the team's trust
Customize conventions specific to your project via CLAUDE.md
Handle large PRs with smart chunking without blowing up costs

The before and after

BEFORE the module:
→ "The bot leaves a generic comment at the end of the PR"
→ "It blocks merges from the first review (frustrating)"
→ "It applies generic rules, not the team's"
→ "For large PRs, it fails or spends too much"

AFTER the module:
→ Inline comments on the exact line of the problem
→ Suggest-only mode until the team trusts it
→ Applies conventions specific to the project
→ Handles large PRs with efficient chunking

Pitfalls to Avoid While Taking This Module

Five predictable misunderstandings worth anticipating.

1. "The bot should block merges from day 1"

No. A bot that blocks merges before the team trusts it generates frustration and workarounds. People start marking the bot as "ignore" or making commits with [skip ci]. Capsule 04 develops suggest-only mode as a starting point — the bot comments, it doesn't block — and how to evolve toward selective blocking (only on critical issues like SQL injection) once the team already trusts the output.

2. "A general comment at the end of the PR is enough"

No. Developers scan PRs line by line. A comment at the end that says "I found 3 problems, see lines 45, 67 and 89" forces the developer to jump between the comment and the code. Inline comments on the exact line are seen and acted on immediately. Capsule 03 teaches you to generate them with the GitHub API.

3. "Generic conventions are enough"

No. If the bot applies generic conventions ("use snake_case in Python"), the team will perceive it as noise — because every team has nuances: "snake_case except for the handlers that come from legacy", "TypeScript but with camelCase for variables and PascalCase for types", etc. Capsule 05 shows you how to customize via CLAUDE.md so the conventions are the team's, not generic.

4. "A 50-file PR I process all at once"

No. Passing 50 files to the model in a single prompt:

Exceeds the useful context window (quality degradation — Module 6 of Guide 8)
Costs a lot of money (token-heavy)
Generates generic comments because the model can't pay attention to everything

Capsule 06 gives you chunking strategies: by file, by feature, with prioritization of relevant files (the ones that changed the most, the ones that touch critical code).

5. "Inline comments work the same as normal comments"

No. Creating inline comments via the API requires specifying path, line, commit_id, and sometimes start_line for multi-line. Errors are common: line out of range, binary file, merge conflicts. Capsule 03 teaches you the API details and how to handle errors.

Diagnosis: What's Your Starting Point?

Five questions to calibrate before you start.

Question 1: Have you used a code review bot before (Codecov, SonarQube, Snyk, etc.)? What was your experience?

If the experience was positive: this module gives you something deeper: review with project context, not just universal rules.

If it was negative (noise, false positives): capsule 04 (suggest-only) and 05 (conventions) are specifically for avoiding those problems.

Question 2: Do you know the difference between a general PR comment and an inline comment?

If yes: capsule 03 formalizes the implementation with the API.

If no: an inline comment goes on a specific line of a specific file (you see it next to the code). A general comment shows up at the end of the PR. Inline = more actionable.

Question 3: Does your project have a CLAUDE.md or conventions document for AI tools?

If yes: capsule 05 shows you how to connect it with the bot.

If no: the bot will apply generic conventions. Consider creating a minimal CLAUDE.md before capsule 05 (Module 6 of Guide 8 teaches you).

Question 4: What would happen if the bot started blocking merges from day one?

If you said "the team would get frustrated": you have the right mental model. Capsule 04 (suggest-only mode) is the answer.

If you said "it would be fine, that's how they learn": pitfall #1 applies to you. Bots that block without trust get disabled.

Question 5: Have you seen a PR with 50+ files? How would your bot handle it?

If you have an answer: capsule 06 validates or refines your approach.

If you haven't thought about it: large PRs are where most bots fail (on cost or quality). Capsule 06 gives you strategies.

If you hesitated on 3 or more: this module is a priority. If you answered all of them with judgment, use it focused on capsule 06 (large PRs), which almost nobody masters at the start.

Connection with the Final Project

In Module 6 (Integrative Project), the code review bot is one of the most visible steps of the complete pipeline. It's the feature the team sees on every PR — the agent's automatic comments. Without this module working, the integrative pipeline is left with a critical step empty.

How to Work Through This Module

Capsule 02 is the most mechanical. Read it with a PR open in your test repo so you can do each step.
Capsule 03 is where the module becomes visible. Inline comments show up in the PR — that's the immediate feedback.
Capsule 04 is the most strategic. How the bot fits into the team's culture matters more than the technical implementation.
Capsule 05 transforms the bot from generic to specific. Without the team's conventions, the bot loses value fast.
Capsule 06 is the one that scales the bot to reality. Large PRs are where most bots break.

Estimated time:

Capsule 01 (this)  →  10 min reading
Capsule 02         →  20 min + practice
Capsule 03         →  25 min + practice with the API
Capsule 04         →  15 min + configuration
Capsule 05         →  20 min + writing CLAUDE.md
Capsule 06         →  20 min + chunking strategies

Total: ~1.75-2 hours

Evidence of Success

Before advancing to Module 3 (GitLab CI/CD and Headless SDK), you should be able to:

✅ Trigger the bot automatically on PR events (opened, synchronize)
✅ Extract the diff of the PR and pass it to the model efficiently
✅ Generate inline comments on specific lines using the GitHub API
✅ Produce a review summary at the end of the review with the main findings
✅ Operate in suggest-only mode without blocking merges on the first setup
✅ Customize conventions of the project using CLAUDE.md
✅ Handle a large PR (30+ files) with chunking without blowing up costs

If any of these isn't met by the end, go back to the corresponding capsule. Module 3 (cross-platform portability) assumes you already have a working bot on GitHub to port it to GitLab.

Summary

This module gives you the most visible result of the whole guide: automatic comments on every PR
Code review with context, not a linter — Claude Code understands what the code does, not just whether it follows rules
Inline comments are the difference between "feedback that's acted on" and "feedback that's ignored"
Suggest-only mode is the right starting point — blocking without trust generates workarounds
Team-specific conventions transform the bot from generic to invaluable
Smart chunking handles large PRs without blowing up costs
The difference between the "3 days with 2.5h of human reviewer" and "5 hours with 20 min" in the opening scenario is exactly this module

Next capsule: 02 — PR triggers and diff extraction. We start with the first technical step: configuring the correct workflow triggers and extracting the PR's diff efficiently so Claude Code can reason about it.

Additional Resources

GitHub Pull Request API — REST API reference for PRs
GitHub PR Review Comments API — Specifically for inline comments
GitHub Actions: pull_request events — Available triggers
Octokit — Official library for the GitHub API in JS/TS
PyGithub — Library for the GitHub API in Python
Anthropic API for Code Review — Official use cases

← PreviousCosts and Rate Limiting Next →PR Triggers and Diff Extraction

Module 2: Automated Code Review on PRs

Module 2: Automated Code Review on PRs

Overview

Where We Are in the Guide

Code Review with Context, Not Linting

A Real Task: Before and After

Approach A: Human review only

Approach B: Bot + Human review (this module)

Prerequisites

Required knowledge:

Recommended:

NOT required:

Module Roadmap

Capsule 01 — Module introduction (this capsule)

Capsule 02 — PR triggers and diff extraction

Capsule 03 — Inline comments via the GitHub API

Capsule 04 — Review summary and suggest-only mode

Capsule 05 — Customizing your team's conventions

Capsule 06 — Handling large PRs

Progression map

What You'll Achieve in This Module

The before and after

Pitfalls to Avoid While Taking This Module

1. "The bot should block merges from day 1"

2. "A general comment at the end of the PR is enough"

3. "Generic conventions are enough"

4. "A 50-file PR I process all at once"

5. "Inline comments work the same as normal comments"

Diagnosis: What's Your Starting Point?

Connection with the Final Project

How to Work Through This Module

Estimated time:

Evidence of Success

Summary

Additional Resources