> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coderabbit.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Write review instructions that work

> Write path instructions and .coderabbit/ instructions that CodeRabbit applies consistently, test them on a pull request, and debug one that isn't applied.

When CodeRabbit misses a rule your team cares about, the cause is usually the instruction text: it is vague, not limited to a path, or in conflict with another rule. Guidelines written for human reviewers often depend on judgment that a language model can't infer. This guide shows how to write rules that are specific enough to check, and how to find out why one isn't applied.

## Before you start

* Know where instructions live: `reviews.path_instructions` in [YAML V2](https://docs.coderabbit.ai/configuration/file.md), or Markdown files in `.coderabbit/instructions/` (see [Instruction and check documents](https://docs.coderabbit.ai/configuration/documents.md)). In V3, documents are the only place.
* Observe a few reviews first. Add an instruction when something is missed consistently, or when one part of the codebase needs different handling.
* Choose the right tool. Use instructions for rules scoped to files in review, [code guidelines](https://docs.coderabbit.ai/knowledge-base/code-guidelines.md) for existing standards files such as `AGENTS.md`, and [custom checks](https://docs.coderabbit.ai/pr-reviews/custom-checks.md) for pass or fail conditions.

## Scope every rule

Name the path, layer or file type the rule applies to. A rule without a scope is incomplete and applies inconsistently.

> [tab] YAML V2
>
> ```yaml theme={null}
> reviews:
>   path_instructions:
>     - path: "src/services/**"
>       instructions: "Services must receive their dependencies through the constructor."
> ```

> [tab] Document
>
> Available on GitHub Cloud with CodeRabbit Cloud. See [Instruction and check documents](https://docs.coderabbit.ai/configuration/documents.md#availability).
>
> ```markdown .coderabbit/instructions/services.md theme={null}
> ---
> id: services
> paths:
>   - "src/services/**"
> ---
>
> Services must receive their dependencies through the constructor.
> ```

In `path_instructions`, `path` is a glob from the repository root. In a document, `paths` is relative to the directory that contains `.coderabbit/`.

## Make each rule specific and checkable

Replace subjective words, such as clean, simple, maintainable, proper, meaningful or large, with conditions a reader can observe.

| Instead of | Write |
| - | - |
| Keep functions small. | Functions must not exceed 40 lines of executable code, excluding comments. |
| Follow best practices for error handling. | Wrap every async external API call in try/catch and log the error with `logger.error()` before raising the error again. |
| Use meaningful variable names. | Variable names have at least 3 characters. Single letters are allowed only in loops of 5 lines or fewer. |

## Remove contradictions

When two rules compete, CodeRabbit can't reliably decide which one wins. Resolve the priority yourself: delete one rule, or narrow each rule's scope so they stop overlapping. Check documents and inline entries together, because a document and an inline `path_instructions` entry both apply in V2.

## Leave style to linters

Style and formatting belong to linters and formatting tools. Write an instruction that tells CodeRabbit to skip them, so reviews focus on design, logic and performance. See [Reduce review noise](https://docs.coderabbit.ai/configuration/guides/reduce-noise.md).

## Stay under the length limit

Each instruction body is limited to 20,000 characters. A check document body is limited to 10,000. Split a long rule set into several documents with different IDs and narrower `paths`.

## Check each instruction

Before you commit a rule, ask:

* Would two engineers read it the same way?
* Can you detect a violation in a diff?
* Is its scope defined?
* Is it consistent with your other rules?
* Does it avoid vague words?

If any answer is no, rewrite the rule.

## Test an instruction on a pull request

**1. Run the rule on one pull request**

Comment with the rule in a one-run override. Include `inheritance: true`, or the override replaces your resolved configuration and omitted keys take schema defaults.

````text theme={null}
@coderabbitai review --with-config
```yaml
inheritance: true
reviews:
  path_instructions:
    - path: "src/services/**"
      instructions: "Services must receive their dependencies through the constructor."
```
````

**2. Read the review**

Check whether CodeRabbit flags a change that breaks the rule and leaves a compliant change alone.

**3. Commit the rule**

Add it to your configuration file or a document when the result looks right.

On a draft pull request on GitHub, `@coderabbitai review --preview-config` reads your configuration that is not yet merged instead. See [Validate and test a configuration change](https://docs.coderabbit.ai/configuration/guides/validate-and-test.md).

## Debug an instruction that isn't applied

Start with the cause that costs least to check.

> [accordion] The path glob doesn't match the file
>
> Compare the glob with the file's repository-relative path. In a document, remember that `paths` start at the directory that contains `.coderabbit/`, so `src/**` in `services/api/.coderabbit/` means `services/api/src/**`. An invalid glob is skipped, and CodeRabbit logs `Invalid path pattern`.

> [accordion] Path filters exclude the file
>
> A file that `reviews.path_filters` excludes isn't reviewed, so no instruction applies to it. Check the filters and the default exclusions. See [Choose which files are reviewed](https://docs.coderabbit.ai/pr-reviews/which-files.md).

> [accordion] A closer document with the same ID replaces yours
>
> For the same kind and ID, the closest directory replaces its parent, even when the nested document has `enabled: false` or narrower `paths`. Search for another file with the same `id` in a subdirectory, or give the rules different IDs.

> [accordion] CodeRabbit reads a different revision
>
> CodeRabbit reads the configuration and documents from the branch your [configuration branch policy](https://docs.coderabbit.ai/configuration/branch.md) allows. An instruction on a pull request branch isn't used for a fork pull request, or under **Default branch** unless the pull request is trusted and **Allow configuration changes from trusted PRs** is on. Merge the change, or check **Run configuration** in **Review info**.

> [accordion] The configuration file was dropped
>
> Invalid YAML or a wrong value type makes CodeRabbit ignore the repository file. The review still runs on the next layers, and the summary starts with a parsing-error warning. Fix the file, then see [Fix settings that aren't applied](https://docs.coderabbit.ai/configuration/guides/troubleshoot.md).

## Check the result

Open the next few pull requests that touch the scoped paths. Confirm that CodeRabbit applies the rule to violations and doesn't raise it elsewhere. Post `@coderabbitai configuration` to see the instructions CodeRabbit resolved. See [Check which configuration a review used](https://docs.coderabbit.ai/configuration/guides/check-effective-configuration.md).

## What's next

> [card] [Teach CodeRabbit your review rules](https://docs.coderabbit.ai/pr-reviews/review-instructions.md)
>
> Choose between path instructions, documents, code guidelines and custom checks.

> [card] [.coderabbit/ documents](https://docs.coderabbit.ai/configuration/documents.md)
>
> Store instructions as Markdown files scoped to a package.

> [card] [Reduce review noise](https://docs.coderabbit.ai/configuration/guides/reduce-noise.md)
>
> Lower comment volume with profiles, filters and a skip-style instruction.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.