Review instructions

Add instructions

1. Open Workspace settings → Review instructions. For one repository, open Repositories → (a repository) → Review instructions.
2. Write plain text or Markdown, up to 12,000 characters.
3. Select Save workspace instructions or Save repository instructions.

• Workspace instructions apply to every repository. Repository instructions are added to them, and win where the two conflict.
• On a repository’s page, Preview combined instructions shows both in order.
• Changes apply to reviews requested after you save.
• Only workspace admins can edit instructions.
• Don’t put passwords, tokens, or other secrets in instructions.

What belongs in instructions

Instructions hold guidance that only matters when HeyDeer reviews: what to prioritize, what to leave alone, the terms your team uses, and how to word feedback.

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.

To keep such guidance in the repository, beside the code it’s about, use REVIEW.md. A pull request can change REVIEW.md, so keep what it mustn’t change in instructions.

Instructions take precedence over REVIEW.md, AGENTS.md and skills, but they can’t stop a repository check from running. See When guidance conflicts.

Write effective instructions

Let HeyDeer review a few pull requests before you write anything. Add an instruction for a miss or an unwanted comment that recurs, a few at a time, and read the next reviews to see the effect.

• Group instructions under a few headings, such as Priorities, Leave alone, Terms, and Feedback.
• Write one instruction per bullet, and name the paths, functions, and libraries it is about.
• Add the reason when it is not obvious.
• Keep exclusions narrow: “Don’t comment on files in scripts/one-off/”, not “Don’t comment on scripts”, which also hides real bugs.
• Use settings for how HeyDeer reports: Review language, Feedback scope and Automatic approval.

## Priorities

- Code under src/payments/ is high risk. Look hardest at retries,
  refunds and anything that could charge a customer twice.

## Leave alone

- Files under scripts/one-off/. They run once by hand and are deleted.
- Formatting. The formatter runs in CI.

## Terms

- A "workspace" is a customer account, not a folder on disk.

## Feedback

- Name the input that triggers a bug, and suggest the smallest fix.

If an instruction seems ignored, see Troubleshooting.