Best practices
Where each rule belongs
Choose the place for a rule by what it is for and by who should be able to change it.
Choose a place
| What you want to tell HeyDeer | Put it in | Where HeyDeer reads it |
|---|---|---|
| Team conventions and project context: structure, naming, which helpers to use | AGENTS.md | The pull request. A nested file applies to its directory. |
| A rule every pull request touching certain files must meet | .agents/checks/ | The base branch |
| A method or domain knowledge that several checks share | .agents/skills/ | The pull request |
| Review priorities, what to leave alone, and tone for every repository | Organization instructions | Organization settings → Review instructions |
| The same for one repository | Repository instructions | Repositories → (a repository) → Review instructions |
| Context outside the repository, such as tickets or internal docs | MCP servers | Organization settings → MCP servers, or a repository’s MCP servers |
| Which pull requests are reviewed automatically | Automatic review filters | Review rules |
| How many findings are posted | Feedback scope | Review rules |
| The language HeyDeer writes in | Review language | Review rules |
Review instructions take precedence over AGENTS.md when the two conflict.
Base branch or pull request
Checks come from the base branch, so a pull request cannot weaken a check that its own changes would break. A new check applies to pull requests reviewed after it merges.
AGENTS.md and skills come from the pull request, so they always match the code under review, and anyone who opens a pull request can edit them. Put rules that must hold whatever a pull request says into a check or review instructions.