Skip to main content
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, or Markdown files in .coderabbit/instructions/ (see Instruction and check documents). 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 for existing standards files such as AGENTS.md, and custom checks 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.
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.

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.

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.
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.

Debug an instruction that isn’t applied

Start with the cause that costs least to check.
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.
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.
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.
CodeRabbit reads the configuration and documents from the branch your configuration branch policy 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.
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.

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.

What’s next

Teach CodeRabbit your review rules

Choose between path instructions, documents, code guidelines and custom checks.

.coderabbit/ documents

Store instructions as Markdown files scoped to a package.

Reduce review noise

Lower comment volume with profiles, filters and a skip-style instruction.