Best practices

Writing review guidance

Review instructions and AGENTS.md work best as short, specific rules a new teammate could follow. To choose between them, see Where each rule belongs.

Start from real reviews

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

Write short, specific rules

Group rules under a few headings, such as Priorities, Leave alone, and Conventions.
Write one rule 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 problems.
Show a few lines of incorrect and correct code from your codebase.
Aim well below the 12,000-character limit. When instructions grow, move conventions to AGENTS.md and hard requirements to repository checks.

What not to include

Don’t include	Why	Instead
Formatting rules, such as indentation or import order	A formatter or linter enforces them exactly.	Run those tools in CI.
“Be more thorough”, “Don’t miss anything”	They give HeyDeer nothing specific to act on.	Name the risks that matter, or use Deep depth or a broader Feedback scope.
Persona framing, such as “You are a senior security engineer”	A role does not say what to look for.	Write the rules that person would apply.
“Block the merge if…”, “Approve small PRs”	Instructions shape the review, not what HeyDeer does on GitHub.	Use Fail the check when issues are found with a branch rule, and Automatic approval.
“Run the tests”, “Build the project first”	HeyDeer reads code. It never runs code, tests, or builds.	Ask for what HeyDeer can verify by reading.
Links, such as “Follow the standards on our wiki”	HeyDeer cannot open web links.	Copy the rules that matter, keep the document in the repository, or connect an MCP server.
“Write your findings in Japanese”	Language is a setting that also covers summaries and headings.	Set Review language.

Before and after

Before:

You are a world-class senior engineer. Be extremely thorough and
never miss a bug. Follow our standards at
https://wiki.example.com/engineering/standards. Use 2-space
indentation. Write all comments in Japanese. Run the tests before
you review, and block the PR if anything is wrong.

After:

## Priorities

- Code under src/payments/ is high risk. Every call to chargeCard()
  passes an idempotency key derived from the order ID, so a retried
  request cannot charge twice.
- Retries use retry() from src/lib/retry.ts, which adds backoff.
  Replace hand-written retry loops with it.

## Leave alone

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

## Conventions

- Return client errors through AppError with a stable code.

  Incorrect:

  ```ts
  return Response.json({ error: err.message }, { status: 500 });
  ```

  Correct:

  ```ts
  throw new AppError('INVOICE_NOT_FOUND', 404);
  ```

The rewrite turns the persona and the wiki link into specific rules. Everything else moves to the places in the table above.