Skip to content

code-review-customize.md

Latest commit

 

History

History
233 lines (152 loc) · 16.2 KB

code-review-customize.md

File metadata and controls

233 lines (152 loc) · 16.2 KB
Raw

Documentation Index

Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt Use this file to discover all available pages before exploring further.

Customize Code Review

Tune what Code Review flags on your pull requests with REVIEW.md and CLAUDE.md: recalibrate severity, skip paths, add checks, and see which copy applies.

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.

Note

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. You can also add a REVIEW.md in a subdirectory to add checks for changes under that path, 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.

Note

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.

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 REVIEW.md stays in REVIEW.md as plain text, and the check run doesn't report it as a skipped include.
  • One level: list every file in the root REVIEW.md. An @ line in an included file or in a subdirectory REVIEW.md stays as plain text (skill files differ), and a Markdown link to another file isn't an include.
  • Limits: include at most eight different files, and keep REVIEW.md and the files it includes under 150,000 bytes combined. A file that would reach the byte limit is skipped whole, not cut short. The check run reports how many include lines it skipped for either limit.
  • Links: keep Markdown links at 64 or fewer across REVIEW.md and the files it includes. Links to http, https, or mailto addresses and to # anchors don't count, and neither do links in a skill file. Past that limit, the review skips your whole root REVIEW.md, not only the included files. The check run then says the instructions weren't applied.
  • Merged copy: merge the included file into the branch REVIEW.md is read from. The review reads both from the same commit, never from the pull request's own changes.

Include a skill file

To have reviews follow guidance you keep in a skill, include the skill's SKILL.md in your root REVIEW.md. Code Review doesn't run skills.

Add @ and the path to SKILL.md, in the form .claude/skills/<folder>/SKILL.md, on a line of its own:

# Review instructions

Report at most five Nits per review.

@.claude/skills/api-review/SKILL.md

Treat any change under `migrations/` as Important.

Protect the branch that REVIEW.md is read from, because Code Review includes a skill file only when it reads REVIEW.md from a protected branch. The skill file counts toward the limits of eight files and 150,000 bytes, and has its own limit of 30,000 bytes.

Write a skill line that Code Review includes

Use a folder name without spaces. A line with a space in its path stays in REVIEW.md as plain text, and the check run doesn't report it as a skipped include.

If the @ line for a skill breaks one of the rules below, Code Review doesn't include the skill from that line:

  • Path: write the path as .claude/skills/<folder>/SKILL.md from the repository root, with the skill's folder directly under skills/. Unlike a file name at the root, a path of this form that matches no file is skipped and counted.
  • Source: copy guidance from any other file under .claude/, or from a bundled, personal, or plugin skill, into a file beside REVIEW.md. You can't include those directly.
  • File: commit SKILL.md as a regular text file. Code Review doesn't follow a symbolic link, whether the link is the file or a folder in its path.
  • Size: keep SKILL.md at 30,000 bytes or less, frontmatter included
  • Count: write at most eight skill lines. A repeated line counts again toward the eight.
  • Blocks in REVIEW.md: keep the @ line out of code fences. Close every HTML comment and every <pre>, <script>, <style>, or <textarea> block above it.

When Code Review skips a skill line for breaking the File, Size, Count, or Blocks rule, the check run's message about skipped include lines counts it. The message appears only when the review applies REVIEW.md from a protected branch.

Check what a review gets from a skill

When the skill is included, a review gets the body of SKILL.md and nothing else from the skill, so check the skill against the list below.

  • Frontmatter: repeat in the body anything a review needs from the frontmatter, for example the conditions that description gives for using the skill
  • Injected commands: write out what a ! command would supply. Code Review doesn't run the command, and replaces the whole line or block that holds it with a placeholder.
  • Substitutions: replace $ARGUMENTS and other substitutions with fixed text, because a review passes no arguments and leaves them as written
  • Supporting files: copy what a review needs into SKILL.md, because Code Review doesn't load scripts, linked files, or @file references
  • Exclusions and Nit caps: write instructions that exclude findings or cap Nits in REVIEW.md or a file beside it, not in the skill. Code Review doesn't accept a skill's text as the reason for either.
  • Links to repository files: state in words what a link or @file reference points to. The review sees the path as plain text or as a placeholder.

If you edit the skill's ! commands, $ARGUMENTS, or links, you also change how it works in Claude Code. If your team relies on those, copy the guidance into a file beside REVIEW.md and include that file in place of the skill.

Characters that Code Review changes in skill text

Code Review changes some characters in the skill's text, so your code samples reach a review in the form below.

In SKILL.md:       Use `items[0]`, never `List<String>`.
The review reads:  Use ˋitems(0)ˋ, never ˋList< String>ˋ.

In SKILL.md:       Run `ps | grep api` and ask @alice.
The review reads:  Run ˋps ¦ grep apiˋ and ask @ alice.

Where a rule depends on one of those characters, state it in words too.

Which branch REVIEW.md is read from

Code Review reads REVIEW.md from the pull request's base branch or from the default branch, never from the pull request's own changes. To change review behavior, merge the REVIEW.md change first.

Keep REVIEW.md on your default branch and protect that branch. When a review reads the copy on a protected default branch, the first row of the table below, it honors these instructions from the root file:

  • Lowering a finding's severity
  • Excluding paths, files, or classes of issue
  • Capping nit comments

Write exclusions and Nit caps in REVIEW.md or a file beside it, not in an included skill.

What counts as branch protection

Code Review counts these settings as protection:

  • Default branch: a classic branch protection rule or a ruleset
  • Any other branch: a ruleset only

A ruleset counts when it restricts updates or requires pull requests with at least one approval. If it requires pull requests, it must also dismiss that approval on a new push or require the approval to come after the last push.

What a review reads for each branch setup

Find your repository's situation in the first column of the table below.

Branch protection Copy read Files read
The default branch is protected, and the pull request targets it or targets a branch no ruleset protects Default branch Root file, the files it includes, and subdirectory files
The pull request targets another branch that a ruleset protects That base branch Root file, the files it includes, and subdirectory files
The default branch isn't protected, and the base branch has no protection rule of either kind Default branch Root file
Code Review can't confirm the protection settings. This includes an unprotected default branch with a base branch that has only a classic rule None None

If the check run mentions REVIEW.md, see The check run mentions REVIEW.md.

Related resources