Before you start
- Know where instructions live:
reviews.path_instructionsin 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.- YAML V2
- Document
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 inlinepath_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 narrowerpaths.
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?
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.
@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.The path glob doesn't match the file
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.Path filters exclude the file
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.A closer document with the same ID replaces yours
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.CodeRabbit reads a different revision
CodeRabbit reads a different revision
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.
The configuration file was dropped
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.
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.