code-review.md +168 −0 created
1> ## Documentation Index
2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
3> Use this file to discover all available pages before exploring further.
4
5# Code Review
6
7> Set up automated PR reviews that catch logic errors, security vulnerabilities, and regressions using multi-agent analysis of your full codebase
8
9<Note>
10 Code Review is in research preview, available for [Teams and Enterprise](https://claude.ai/admin-settings/claude-code) subscriptions. It is not available for organizations with [Zero Data Retention](/en/zero-data-retention) enabled.
11</Note>
12
13Code Review analyzes your GitHub pull requests and posts findings as inline comments on the lines of code where it found issues. A fleet of specialized agents examine the code changes in the context of your full codebase, looking for logic errors, security vulnerabilities, broken edge cases, and subtle regressions.
14
15Findings are tagged by severity and don't approve or block your PR, so existing review workflows stay intact. You can tune what Claude flags by adding a `CLAUDE.md` or `REVIEW.md` file to your repository.
16
17To run Claude in your own CI infrastructure instead of this managed service, see [GitHub Actions](/en/github-actions) or [GitLab CI/CD](/en/gitlab-ci-cd).
18
19This page covers:
20
21* [How reviews work](#how-reviews-work)
22* [Setup](#set-up-code-review)
23* [Customizing reviews](#customize-reviews) with `CLAUDE.md` and `REVIEW.md`
24* [Pricing](#pricing)
25
26## How reviews work
27
28Once an admin [enables Code Review](#set-up-code-review) for your organization, reviews run automatically when a pull request opens or updates. Multiple agents analyze the diff and surrounding code in parallel on Anthropic infrastructure. Each agent looks for a different class of issue, then a verification step checks candidates against actual code behavior to filter out false positives. The results are deduplicated, ranked by severity, and posted as inline comments on the specific lines where issues were found. If no issues are found, Claude posts a short confirmation comment on the PR.
29
30Reviews scale in cost with PR size and complexity, completing in 20 minutes on average. Admins can monitor review activity and spend via the [analytics dashboard](#view-usage).
31
32### Severity levels
33
34Each finding is tagged with a severity level:
35
36| Marker | Severity | Meaning |
37| :----- | :----------- | :------------------------------------------------------------------ |
38| 🔴 | Normal | A bug that should be fixed before merging |
39| 🟡 | Nit | A minor issue, worth fixing but not blocking |
40| 🟣 | Pre-existing | A bug that exists in the codebase but was not introduced by this PR |
41
42Findings include a collapsible extended reasoning section you can expand to understand why Claude flagged the issue and how it verified the problem.
43
44### What Code Review checks
45
46By default, Code Review focuses on correctness: bugs that would break production, not formatting preferences or missing test coverage. You can expand what it checks by [adding guidance files](#customize-reviews) to your repository.
47
48## Set up Code Review
49
50An admin enables Code Review once for the organization and selects which repositories to include.
51
52<Steps>
53 <Step title="Open Claude Code admin settings">
54 Go to [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code) and find the Code Review section. You need admin access to your Claude organization and permission to install GitHub Apps in your GitHub organization.
55 </Step>
56
57 <Step title="Start setup">
58 Click **Setup**. This begins the GitHub App installation flow.
59 </Step>
60
61 <Step title="Install the Claude GitHub App">
62 Follow the prompts to install the Claude GitHub App to your GitHub organization. The app requests these repository permissions:
63
64 * **Contents**: read and write
65 * **Issues**: read and write
66 * **Pull requests**: read and write
67
68 Code Review uses read access to contents and write access to pull requests. The broader permission set also supports [GitHub Actions](/en/github-actions) if you enable that later.
69 </Step>
70
71 <Step title="Select repositories">
72 Choose which repositories to enable for Code Review. If you don't see a repository, make sure you gave the Claude GitHub App access to it during installation. You can add more repositories later.
73 </Step>
74
75 <Step title="Set review triggers per repo">
76 After setup completes, the Code Review section shows your repositories in a table. For each repository, use the dropdown to choose when reviews run:
77
78 * **After PR creation only**: review runs once when a PR is opened or marked ready for review
79 * **After every push to PR branch**: review runs on every push, catching new issues as the PR evolves and auto-resolving threads when you fix flagged issues
80
81 Reviewing on every push runs more reviews and costs more. Start with PR creation only and switch to on-push for repos where you want continuous coverage and automatic thread cleanup.
82 </Step>
83</Steps>
84
85The repositories table also shows the average cost per review for each repo based on recent activity. Use the row actions menu to turn Code Review on or off per repository, or to remove a repository entirely.
86
87To verify setup, open a test PR. A check run named **Claude Code Review** appears within a few minutes. If it doesn't, confirm the repository is listed in your admin settings and the Claude GitHub App has access to it.
88
89## Customize reviews
90
91Code Review reads two files from your repository to guide what it flags. Both are additive on top of the default correctness checks:
92
93* **`CLAUDE.md`**: shared project instructions that Claude Code uses for all tasks, not just reviews. Use it when guidance also applies to interactive Claude Code sessions.
94* **`REVIEW.md`**: review-only guidance, read exclusively during code reviews. Use it for rules that are strictly about what to flag or skip during review and would clutter your general `CLAUDE.md`.
95
96### CLAUDE.md
97
98Code Review reads your repository's `CLAUDE.md` files and treats newly-introduced violations as nit-level findings. This works bidirectionally: if your PR changes code in a way that makes a `CLAUDE.md` statement outdated, Claude flags that the docs need updating too.
99
100Claude reads `CLAUDE.md` files at every level of your directory hierarchy, so rules in a subdirectory's `CLAUDE.md` apply only to files under that path. See the [memory documentation](/en/memory) for more on how `CLAUDE.md` works.
101
102For review-specific guidance that you don't want applied to general Claude Code sessions, use [`REVIEW.md`](#reviewmd) instead.
103
104### REVIEW\.md
105
106Add a `REVIEW.md` file to your repository root for review-specific rules. Use it to encode:
107
108* Company or team style guidelines: "prefer early returns over nested conditionals"
109* Language- or framework-specific conventions not covered by linters
110* Things Claude should always flag: "any new API route must have an integration test"
111* Things Claude should skip: "don't comment on formatting in generated code under `/gen/`"
112
113Example `REVIEW.md`:
114
115```markdown theme={null}
116# Code Review Guidelines
117
118## Always check
119- New API endpoints have corresponding integration tests
120- Database migrations are backward-compatible
121- Error messages don't leak internal details to users
122
123## Style
124- Prefer `match` statements over chained `isinstance` checks
125- Use structured logging, not f-string interpolation in log calls
126
127## Skip
128- Generated files under `src/gen/`
129- Formatting-only changes in `*.lock` files
130```
131
132Claude auto-discovers `REVIEW.md` at the repository root. No configuration needed.
133
134## View usage
135
136Go to [claude.ai/analytics/code-review](https://claude.ai/analytics/code-review) to see Code Review activity across your organization. The dashboard shows:
137
138| Section | What it shows |
139| :------------------- | :--------------------------------------------------------------------------------------- |
140| PRs reviewed | Daily count of pull requests reviewed over the selected time range |
141| Cost weekly | Weekly spend on Code Review |
142| Feedback | Count of review comments that were auto-resolved because a developer addressed the issue |
143| Repository breakdown | Per-repo counts of PRs reviewed and comments resolved |
144
145The repositories table in admin settings also shows average cost per review for each repo.
146
147## Pricing
148
149Code Review is billed based on token usage. Reviews average \$15-25, scaling with PR size, codebase complexity, and how many issues require verification.
150
151The review trigger you choose affects total cost:
152
153* **After PR creation only**: runs once per PR
154* **After every push**: runs on each commit, multiplying cost by the number of pushes
155
156Costs appear on your Anthropic bill regardless of whether your organization uses AWS Bedrock or Google Vertex AI for other Claude Code features. To set a monthly spend cap for Code Review, go to [claude.ai/admin-settings/usage](https://claude.ai/admin-settings/usage) and configure the limit for the Claude Code Review service.
157
158Monitor spend via the weekly cost chart in [analytics](#view-usage) or the per-repo average cost column in admin settings.
159
160## Related resources
161
162Code Review is designed to work alongside the rest of Claude Code. If you want to run reviews locally before opening a PR, need a self-hosted setup, or want to go deeper on how `CLAUDE.md` shapes Claude's behavior across tools, these pages are good next stops:
163
164* [Plugins](/en/discover-plugins): browse the plugin marketplace, including a `code-review` plugin for running on-demand reviews locally before pushing
165* [GitHub Actions](/en/github-actions): run Claude in your own GitHub Actions workflows for custom automation beyond code review
166* [GitLab CI/CD](/en/gitlab-ci-cd): self-hosted Claude integration for GitLab pipelines
167* [Memory](/en/memory): how `CLAUDE.md` files work across Claude Code
168* [Analytics](/en/analytics): track Claude Code usage beyond code review