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
Start from your reviews: add a line for a miss or an unwanted finding that recurs. Write only what is specific to your repository, because HeyDeer already applies common review practice.
- What to check that HeyDeer can’t know from the code, such as which log fields count as personal data.
- What to leave alone, such as issues your CI already reports. Keep exclusions narrow and name the paths they cover. Where a path needs some review, raise the bar instead of excluding it.
- How serious a kind of issue is for your team, using HeyDeer’s severities: Critical, High, Medium and Low.
- What evidence a kind of finding needs, when that kind keeps turning out wrong.
REVIEW.md
# Review instructions
## Always check
- Log lines don't include email addresses, account IDs or
request bodies.
- New endpoints in src/api/public/ are listed in openapi.yaml.
## Leave alone
- Formatting and lint issues. CI enforces them.
- Code in tests/fixtures/ that breaks production rules on purpose.
- In scripts/, report only Critical and High issues.
## Severity
- A migration that isn't backward compatible is High.
- Naming and refactoring suggestions are Low.
## Evidence
- A claim that a function can return null cites the line that
returns it, not the function's name.Put coding conventions in AGENTS.md, so coding agents follow them too. Make a requirement that is costly to miss a repository check, which gets a reviewer of its own. See A check or REVIEW.md.
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.