Customize Code Review - Claude Code Docs
Documentation Index Fetch the complete documentation index at: /docs/llms.txt Use this file to discover all available pages before exploring further. Skip to main content Assistant Responses are generated using AI and may contain mistakes. You can change what Code Review flags on your repository by committing instructions to it. This is how you cut nit volume, stop comments on generated files, or add a rule your team cares about.
Put them in one of two files: CLAUDE.md : project instructions that Claude Code reads for every task, reviews included. Code Review reads them as project context and flags changes that violate them. REVIEW.md : instructions for reviews alone. Use it to say what your team wants flagged, at what severity, and what to skip. Add REVIEW.md at your repository root and merge it. Then protect your default branch . To change how thorough reviews are or when they run, ask an Owner to change the review level or the Review runs setting .
Use CLAUDE.md for project-wide rules Code Review reads your repository’s CLAUDE.md files as project context. A change that violates one of their rules becomes a finding at whichever severity level fits the issue. A review reads the CLAUDE.md at your repository root and the CLAUDE.md files in the parent directories of each changed file. A subdirectory’s CLAUDE.md is read when the pull request changes a file under that path.
Use REVIEW.md for review-only rules REVIEW.md is a file at your repository root that tailors Code Review to your repository. On a protected branch , you can also add a REVIEW.md in most subdirectories to add checks for changes under that subdirectory, on top of the root file. The agents that find issues and the agents that verify them receive its contents as your repository’s review instructions, alongside Code Review’s default review guidance.
The step that writes the final review consults it before settling severity and writing the summary. This example layout has a root file and one subdirectory file: your-repo/ ├── REVIEW.md # Root file ├── services/ │ └── billing/ │ └── REVIEW.md # Adds checks for changes under services/billing/ └── src/ Before you rely on a subdirectory file, protect your default branch and check what a review reads for your branch setup .
The Code Review service and the local /code-review command are two separate tools, and they read different files. The service reads both CLAUDE.md and REVIEW.md . The /code-review command, which you run inside a Claude Code session on your own machine, reads your CLAUDE.md files and not REVIEW.md . Put guidance you want applied in both places in CLAUDE.md , and keep REVIEW.md for rules specific to pull request review.
When a subdirectory REVIEW.md doesn’t apply Code Review doesn’t apply a REVIEW.md in or below a subdirectory with one of these names, whatever the subdirectory holds. A subdirectory name matches only as a whole, in any letter case and at any depth, so Tests matches and integration-tests doesn’t: Tests : test , tests , __tests__ , testdata , fixtures , __fixtures__ , golden , corpus , snapshots , __snapshots__ Examples : example , examples , sample , samples , demo , demos Generated code : generated Third-party code : vendor , third_party , third-party , thirdparty , node_modules , bower_components , external , extern , deps , godeps , pods , carthage , site-packages , contrib Put checks for those subdirectories in the root REVIEW.md , or in a parent subdirectory’s REVIEW.md when neither that parent nor anything above it is on the list.
The remaining subdirectory REVIEW.md files on the paths a pull request changes share a limit of 150,000 bytes, not counting the root file. If the check run reports that some of them didn’t fit, shorten the files to fit that limit. Example REVIEW.md This REVIEW.md recalibrates severity for a backend service, caps nits, skips generated files, and adds repo-specific checks. # Review instructions ## What Important means here Reserve Important for findings that would break behavior, leak data, or block a rollback: incorrect logic, unscoped database queries, PII in logs or error messages, and migrations that aren't backward compatible.
Style, naming, and refactoring suggestions are Nit at most. ## Cap the nits Report at most five Nits per review. ## Do not report - Anything CI already enforces: lint, formatting, type errors - Generated files under `src/gen/` and any `*.lock` file - Test-only code that intentionally violates production rules ## Always check - New API routes have an integration test - Log lines don't include email addresses, user IDs, or request bodies - Database queries are scoped to the caller's tenant Choose what to write in REVIEW.md REVIEW.md is freeform Markdown that changes what a review finds and reports.
It doesn’t change the format of the review. Find the problem you’re seeing, then add an instruction like the one shown. The example uses the first four. The wrong things are marked Important : redefine what 🔴 Important means for your repository. The default calibration targets production code, and a docs repository, a config repository, or a prototype might want a much narrower definition. State which classes of finding are Important and which are Nit at most.
You can also escalate, for example treating any CLAUDE.md violation as Important. Too many nits : cap how many 🟡 Nit comments a single review posts. A cap like “report at most five nits” keeps reviews actionable. Comments on generated files or on what CI already checks : list paths and finding categories where Claude should skip findings. Common candidates are generated code, lockfiles, and vendored dependencies, along with anything your CI already enforces like linting or spellcheck.
For paths that warrant some review but not full scrutiny, set a higher bar instead: “in scripts/ , only report if near-certain and severe.” A team rule isn’t being checked : add rules you want flagged on every pull request, like “new API routes must have an integration test.” Findings that turn out to be wrong : require evidence before a class of finding is posted. For example, “behavior claims need a file:line citation in the source, not an inference from naming” cuts false positives that would otherwise cost the author a round trip.
Some of these instructions need the root file on a protected default branch . Keep REVIEW.md to instructions that change review behavior, and leave general project context in CLAUDE.md . Include other files in REVIEW.md You can split review instructions across several files and pull them into your root REVIEW.md . Use this when REVIEW.md grows long or when you already keep review rules in another file. To include a file, add a line to the root REVIEW.md with only @ and the file name on it.
Code Review puts the file’s contents in place of that line, so they apply as part of REVIEW.md . In this example, the root file gives one instruction of its own and then includes two rule files: # Review instructions Report at most five Nits per review. @review-security.md @review-api.md Save the included files at the repository root, beside REVIEW.md : your-repo/ ├── REVIEW.md ├── review-security.md └── review-api.md Code Review includes the files when it reads REVIEW.md from a protected branch, so check which branch a review reads for your repository : Protected branch : Code Review puts the included file in place of its @ line Unprotected default branch : the @ line stays in REVIEW.md as plain text.
If the pull request changes the file the line names, the line is left out. When a review doesn’t apply an included file, check each of these: Location : move the file to the repository root. Except for a skill file , a path into a subdirectory such as @docs/review-rules.md isn’t included. Name : match the file name exactly, including case, and use a name without spaces. A line whose name matches no file beside
The rest of this page is on the live site.