最佳实践

编写审查指导

审查指令和 AGENTS.md 最适合写成新队友也能遵循的简短、具体的规则。如何在两者之间选择，请参阅规则放在哪里。

从真实的审查出发

在动笔之前，先让 HeyDeer 审查几个 PR。针对反复出现的遗漏或不想要的评论添加规则，每次只加几条，然后阅读接下来的审查，查看效果。

编写简短、具体的规则

将规则归入几个标题下，例如“优先事项”“不必理会”和“约定”。
每个要点写一条规则，并写明它涉及的路径、函数和库。
理由不明显时，请加以说明。
排除范围要窄：写“不要评论 scripts/one-off/ 中的文件”，而不是“不要评论脚本”，后者也会掩盖真正的问题。
展示几行来自你代码库的错误代码和正确代码。
内容应远低于 12,000 个字符的上限。指令变多时，请将约定移到 AGENTS.md，将硬性要求移到仓库检查。

不应包含的内容

不要包含	原因	替代做法
格式规则，例如缩进或导入顺序	格式化工具或 linter 能精确地强制执行这些规则。	在 CI 中运行这些工具。
“更仔细一些”“不要遗漏任何问题”	它们没有给 HeyDeer 任何具体可执行的内容。	写明重要的风险，或使用深度审查或更宽泛的反馈范围。
角色设定，例如“你是一名资深安全工程师”	角色并不能说明要关注什么。	写下这个人会应用的规则。
“如果……就阻止合并”“批准小型 PR”	指令影响的是审查内容，而不是 HeyDeer 在 GitHub 上的操作。	结合分支规则使用“发现问题时将检查标记为失败”，并使用自动批准。
“运行测试”“先构建项目”	HeyDeer 阅读代码，从不运行代码、测试或构建。	要求 HeyDeer 做它通过阅读就能验证的事。
链接，例如“遵循我们 wiki 上的规范”	HeyDeer 无法打开网页链接。	复制重要的规则、将文档保存在仓库中，或连接 MCP 服务器。
“用日语撰写发现的问题”	语言是一项设置，同时也作用于摘要和标题。	设置审查语言。

修改前后对比

修改前：

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.

修改后：

## 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);
  ```

改写后，角色设定和 wiki 链接变成了具体的规则。其余内容移到了上表所列的位置。