REVIEW.md
Put guidance that only matters in code review in REVIEW.md: what to check, what to leave alone and how serious an issue is. Other code reviewers, such as Claude Code Review, read the same file, so you can keep yours.
What to write
- What to check in every pull request, such as how database queries are scoped.
- What to leave alone, such as issues your CI already reports. Keep exclusions narrow and name the paths they cover.
- How serious a kind of issue is for your team, using HeyDeer’s severities: Critical, High, Medium and Low.
REVIEW.md
# Review instructions
## Always check
- Database queries in src/api/ are scoped to the caller's
workspace.
- Log lines don't include email addresses or request bodies.
## Leave alone
- Formatting and lint issues. CI enforces them.
- Code in tests/fixtures/ that breaks production rules on purpose.
## Severity
- A migration that isn't backward compatible is High.
- Naming and refactoring suggestions are Low.Put coding conventions in AGENTS.md, so coding agents follow them too. Put a requirement HeyDeer must verify in every matching pull request in a repository check.
Root and nested files
Add REVIEW.md to the repository root. A directory that needs its own guidance can have its own file, such as src/payments/REVIEW.md.
A REVIEW.md applies to changes in its directory and below. A deeper file adds to the ones above it, and wins where they conflict.
| Changed file | Files that apply, in order |
|---|---|
src/api/invoices.ts | REVIEW.md |
src/payments/refund.ts | REVIEW.md, src/payments/REVIEW.md |
What settings decide
REVIEW.md changes what HeyDeer looks for and how serious an issue is, not how HeyDeer reports. Use settings for that: Review language, Feedback scope and Automatic approval. For example, to post fewer Low findings, choose the Concise feedback scope.
REVIEW.md doesn’t apply to repository checks: a matching check always runs, and only the check decides what violates it.
To skip generated files, mark them in .gitattributes instead, so they stay out of the review. See Generated files.
Pull requests that edit REVIEW.md
HeyDeer reads REVIEW.md from the pull request, so a pull request that edits it is reviewed with its own version, and HeyDeer never approves it automatically. Put guidance a pull request must not be able to change in review instructions.
Coming from Claude Code Review
Your REVIEW.md works as it is. These differences remain:
- HeyDeer reads REVIEW.md from the pull request, where Claude Code Review reads it from the base branch.
- Important corresponds to Medium severity or above, and Nit to Low.
- A limit on the number of Nits doesn’t apply. Choose the Concise feedback scope instead.
- HeyDeer doesn’t follow includes such as
@review-security.md. Move their guidance into REVIEW.md.