Teach HeyDeer your codebase

What HeyDeer reads

A review reads the pull request’s changes in the context of the whole repository, together with the PR discussion and the guidance you give HeyDeer. This page shows where each kind of guidance belongs, and which of it a pull request can change.

The code and discussion

HeyDeer reviews what the pull request changes, and can read and search any file at the PR head and the commit history. A finding can point to code outside the diff that the change breaks.

It also reads the PR title, description and discussion.

With Read related issues and PRs on, the default, HeyDeer can read issues and pull requests in the same repository when they explain the change, such as an issue the PR fixes. Change it in Review rules → How to review; see Settings reference.

Where each kind of guidance belongs

You don’t need any guidance to start: HeyDeer reviews against the whole repository from the first review. Add guidance for the gaps your first reviews show.

Write only what is specific to your codebase. HeyDeer already knows common engineering practice, and every review looks for bugs and security issues, so guidance that restates them adds nothing.

In your repository

AGENTS.mdConventions for the whole repository

src/payments/AGENTS.mdConventions for one directory

REVIEW.mdWhat to check and leave alone in reviews

.agents/

checks/api-workspace-scope.mdA requirement for the files it covers

skills/api-auth/SKILL.mdA procedure that checks can use

.gitattributesMarks generated files to skip

In HeyDeer

Review instructionsPriorities, what to leave alone, and how to word feedback

ConnectorsContext from outside the repository

What you want to tell HeyDeer	Put it in
How your code works and the conventions it follows. Coding agents follow them too.	AGENTS.md
What reviews should look for, leave alone, and how serious an issue is	REVIEW.md
A requirement HeyDeer must verify in every pull request that changes certain files	`.agents/checks/`
A procedure several checks share	`.agents/skills/`
Review guidance a pull request mustn’t change, or that applies to every repository	Review instructions
Context outside the repository, such as tickets or internal docs	Connectors

A check or REVIEW.md

Reviews follow AGENTS.md and REVIEW.md while they examine the whole change. Each matching check also gets a reviewer of its own that verifies only that requirement, so a check is more thorough but uses more credits.

Make a check of a requirement that is costly to miss and easy to overlook, such as access control on your API routes. Put the rest in REVIEW.md. See Write an effective check.

When guidance conflicts

Review instructions take precedence over REVIEW.md, AGENTS.md, CLAUDE.md and skills, and repository instructions take precedence over workspace instructions. Neither instructions nor anything in the repository can stop a matching repository check from running.

If HeyDeer seems to ignore your guidance, see Troubleshooting.

What a pull request can change

HeyDeer reads AGENTS.md, CLAUDE.md, REVIEW.md, repository checks and skills from the pull request’s head commit. A pull request that edits them is reviewed with its own version, so it can change the guidance it’s reviewed against. HeyDeer never approves such a pull request automatically.

Review instructions and connectors are saved in HeyDeer, so a pull request can’t change them. Put guidance a pull request must not be able to change in review instructions.

HeyDeer reads .gitattributes from the base branch, so a pull request can’t mark its own files as generated to keep them out of the review. For where each configuration lives and who can change it, see Settings reference.

Generated files

Mark generated files, such as generated clients, linguist-generated in .gitattributes. HeyDeer skips them in reviews and repository checks, and reads the attribute from the base branch.

Lock files that the base branch already has are skipped without an attribute. To review one, mark it -linguist-generated. HeyDeer treats these file names as lock files in any folder: package-lock.json, npm-shrinkwrap.json, yarn.lock, pnpm-lock.yaml, bun.lock, bun.lockb, deno.lock, Cargo.lock, go.sum, Gemfile.lock, composer.lock, poetry.lock, Pipfile.lock, uv.lock, pdm.lock, pubspec.lock, Podfile.lock, Package.resolved, mix.lock, packages.lock.json, gradle.lockfile, flake.lock, MODULE.bazel.lock, .terraform.lock.hcl

# .gitattributes
src/generated/** linguist-generated
# Review this lock file anyway
Cargo.lock -linguist-generated

When every changed file is skipped, the HeyDeer Review check shows No reviewable files and no credits are used.

What HeyDeer leaves out

Besides generated files, HeyDeer doesn’t read:

Issues and pull requests in other repositories.
Files that AGENTS.md or CLAUDE.md imports. See AGENTS.md.
Agent configuration in the repository, such as .claude/settings.json, .mcp.json or hooks. To give reviews outside context, use connectors.
Output from your code. HeyDeer reads code and tests but doesn’t build or run them.

HeyDeer keeps discussion context within about 180 KB and 200 conversations on code. It leaves out older reviews and resolved conversations first, then other discussion if needed. A large discussion does not prevent a review.

For the size limits of AGENTS.md, repository checks, skills, review instructions and connectors, see Settings reference.