An AI reviewer can spend a surprising amount of time on the wrong things. It suggests a rename while missing a database query that crosses customer boundaries. The author makes the rename, requests another review and gets a different set of suggestions.
Claude Code's REVIEW.md gives teams a place to explain what deserves attention in their repository. It is a Markdown file for review-specific instructions: which failures matter, what evidence a finding needs and which comments the team wants to avoid.
There is an important setup detail. REVIEW.md configures Anthropic's managed Code Review service for GitHub pull requests. The local /code-review command follows CLAUDE.md and does not read REVIEW.md. Choose the review path before deciding where to put your rules.
What REVIEW.md does
Anthropic's customisation documentation describes REVIEW.md as guidance for the agents finding and verifying issues, and for the step that settles severity and writes the review summary.
By default, Code Review concentrates on correctness bugs. Your file can adjust that focus for the repository. A billing service might need special attention to duplicate charges. A documentation repository needs checks for instructions that no longer work. Those failures deserve different review rules.
Useful instructions can:
- Define which problems deserve an Important finding.
- Limit low-value comments or exclude generated files.
- Require evidence for a claim about broken behaviour.
- Add checks for rules specific to the repository.
The file is freeform Markdown. It changes what a review finds and reports; it does not provide a new review output format. Keep it short enough that code owners can inspect each rule and explain why it belongs there.
REVIEW.md, CLAUDE.md and local review
CLAUDE.md holds project-wide guidance, such as the architecture and conventions that apply while writing code. REVIEW.md holds instructions specifically for reviewing changes.
The distinction matters when developers use both the CLI and the hosted service:
| Review path | Where it runs | Instruction files |
|---|---|---|
| Managed Code Review on a GitHub pull request | Anthropic infrastructure | CLAUDE.md and REVIEW.md |
Local /code-review in a Claude Code session | Your Claude Code session | CLAUDE.md, not REVIEW.md |
The managed service is available to qualifying Team and Enterprise organisations after an Owner enables it and connects the repositories. The local command works on any plan and uses the session's normal plan usage or API billing.
Put an invariant that should guide both writing and reviewing in CLAUDE.md. For example, if every customer-data query must be scoped to the current organisation, the coding agent needs that instruction before it writes the query. Reserve REVIEW.md for review behaviour such as severity calibration and limits on nits.
A starter REVIEW.md for a shared business app
Imagine a service that stores records for several organisations and processes payment events. Its code owners could start with the following file. This is an illustrative policy to adapt, not a tested configuration for your application.
# Review guidance
## Priorities
Treat cross-organisation data exposure, duplicate payment effects,
and migrations that prevent rollback as Important.
For a behaviour finding, cite the relevant file and line and explain
which input or execution path causes the failure. If the evidence
is incomplete, state what is missing.
## Checks specific to this service
- Check that reads and writes use the authenticated organisation ID.
- Check that replaying a payment event cannot apply its effect twice.
- Check that a migration remains compatible with the previous app
version during deployment and rollback.
## Keep comments useful
Report no more than two naming or style nits.
Skip generated client files under src/generated/.
Do not repeat formatting findings already enforced by CI.
Each check names a failure someone can investigate. Compare that with "follow best practices", which leaves the reviewer to invent the standard.
Do not exclude a path simply because it is inconvenient to review. Before skipping generated files, decide how your team checks the generator and its inputs. Likewise, suppressing duplicate formatting comments makes sense only when CI really enforces the formatting rule.
Treat these instructions as guidance to an AI reviewer. They cannot guarantee that it finds every violation. Access controls, transaction safeguards and migration tests still need enforcement in the application and delivery pipeline.
Merge the rules before expecting them to apply
Start with a root-level REVIEW.md and merge it into the appropriate trusted branch. Code Review reads its instructions from the base or default branch, never from the pull request's own changes. A PR adding new review rules should not expect those rules to govern its own review.
Protect your default branch. Anthropic documents branch-dependent behaviour for instructions that reduce scrutiny, including lowering severity, excluding findings and capping nits. Subdirectory rules and included files also depend on the branch protection setup. Check the branch-selection table before relying on a more elaborate layout.
Once the service is enabled, someone with write access to the repository can request a review by commenting @claude review on the pull request. Your organisation's settings determine when reviews run automatically and whether they use Quick, Standard or Deep review.
Adding the Markdown file alone does not enable the service, install its GitHub app or change the review level.
Keep review inside a wider verification process
In its account of the Claude Code team's review process, Anthropic describes checks before a pull request, automated bug and security reviews, required CI, human approval scaled by risk, and a merge queue followed by gradual release. Fast rollback supports the process when something still gets through.
A smaller team can adopt the same separation of responsibilities without copying Anthropic's internal tooling:
- Give the coding agent commands that verify its work. Require the actual test and build output.
- Run review against a defined change, with repository-specific rules and evidence for findings.
- Keep deterministic checks in CI. A prose review cannot replace a failing typecheck or test.
- Require the appropriate person to assess sensitive changes and decide whether the work should ship.
- Record how to reverse the change and who owns failures after release.
There is a difference between Anthropic's internal merge policy and its public service. The managed Code Review service never approves or blocks a pull request, and its check run does not conclude as a failure. Your repository's merge requirements must enforce your policy separately.
The service also examines code without building or running it. A clean review is not evidence that the app starts, the migration succeeds or the mobile layout works.
Stop fix-and-review loops from consuming the task
Anthropic reports an internal pull request that went through more than fifty rounds of automated review and fixes overnight. Much of what the reviewer kept finding had already existed at its first pass.
The team's response included a round cap, narrower re-review after the first few passes and avoiding repeated findings. After three rounds, its reviewer asks the author to reconsider the approach. That is a description of an internal workflow, not a promise that adding REVIEW.md enables an automatic three-round limit in your repository.
For your own workflow, define a stopping condition outside the instruction file. You could allow an initial review and a bounded fix pass, then route unresolved or disputed findings to the responsible engineer. Preserve the original findings so a later pass can distinguish a fixed issue from a repeated comment.
When the same valid finding returns across several tasks, repair the cause. Add a deterministic check where possible, improve the coding instructions or change the underlying API. When findings are repeatedly wrong, tighten the evidence requirement and test the revised rules against changes whose outcomes you know.
Try one repository before expanding
Choose a repository with a clear owner and a few known past bugs. Write a short set of review rules, then test whether the reviewer catches those failures without producing misleading findings on clean changes.
Track useful findings and missed bugs alongside the number of review rounds and the time people spend resolving them. More comments alone do not establish a better review. Keep someone accountable for the rules, the merge decision and the result after deployment.
Use Claude Code within your KyoubeAI workflow
KyoubeAI is a versatile AI operating system for organisations where people and AI employees share tasks, company data and apps. It supports the Claude Code CLI, so you can use Claude Code as an agent's harness within a shared company workflow.
If you want to capitalise on REVIEW.md, pair that workflow with Anthropic's managed Code Review service on an eligible, connected GitHub repository. Keep shared coding and local-review rules in CLAUDE.md, and put the service's review-specific instructions in REVIEW.md. KyoubeAI's CLI support does not itself include or activate Anthropic's hosted review service.
Start with KyoubeAI, assign one bounded repository task and keep the verification results with it. For the role and access setup, read how to implement AI in an organisation.