仓库检查

自动编写检查

在网页端的开始使用中选择设置仓库检查。HeyDeer 会阅读仓库及其过往 PR，然后创建一个添加检查的 PR。此操作不消耗积分。

如果想让你自己的编程智能体来编写，把这段提示词交给它：

Add HeyDeer repository checks to this repository following the guide below, and open a pull request with them. If it needs no new check, explain why instead.

# Write repository checks

A check is a Markdown file in `.agents/checks/` that states a requirement. Each check adds a reviewer of its own to every pull request that changes the files it covers, on top of a general review that already looks for common bugs and security issues. Add one only for a requirement that is specific to this codebase, costly to miss and easy to overlook.

1. Learn what the team cares about: the code, AGENTS.md or CLAUDE.md, REVIEW.md, the checks already in `.agents/checks/`, and as much of the merged pull requests and their review discussions as you need to see what reviewers keep asking for and where bugs were fixed.
2. Choose the requirements, usually one or two, leaving out what existing checks cover. Give each check one requirement or a few closely related ones, and keep one requirement in one check.
3. Write each check as `.agents/checks/<name>.md`, its name starting with a letter or digit and using only letters, digits, `.`, `_` and `-`, excluding every case variant of `README.md`:
   - Start with YAML frontmatter whose `files` lists glob patterns, relative to the repository root, for the files where the requirement can break. A pattern without a slash matches in any folder, a `!` prefix excludes, and the last matching pattern decides; exclusions need an including pattern. Compare the patterns with `git ls-files` so they match those files and little else. Add `skills` only to name repository skills the check needs.
     ```
     ---
     files:
       - "src/api/**/*.ts"
       - "!**/*.test.ts"
     ---
     ```
   - Below it, state the requirement as a condition on the code: what breaks it, what satisfies it and why it matters, with a short incorrect and correct example from this codebase. Most checks fit on a screen; a file can be up to 16000 bytes.
   - Write it in the language of the repository's own Markdown, such as its README and AGENTS.md, even when you write the pull request in another language.
4. In the pull request, say what each check covers and why it is worth a reviewer. Link the discussions that led to a check when there are any.

添加检查

1. 在 .agents/checks/ 中创建一个 Markdown 文件，例如 api-workspace-scope.md。
2. 文件开头写 frontmatter，在 files 下列出检查覆盖的文件。
3. 在 frontmatter 下方写出这项要求：什么会违反它，什么能满足它，以及它为什么重要。
4. 在 PR 中提交该文件。HeyDeer 从 PR 中读取检查，因此新检查会用于该 PR 自身的审查。参见 PR 可以更改哪些内容。

.agents/checks/api-workspace-scope.md

---
files:
  - "src/api/**/*.ts"
  - "!**/*.test.ts"
---
# API handlers scope queries to the caller's workspace

Every query in an API handler that reads or writes a table with a
`workspace_id` column must filter on the workspace returned by
`requireWorkspace()`. Without that filter, one customer can read
or change another customer's data.

Fail when a handler queries such a table without that filter.
Pass when every such query filters on the workspace, or when the
handler only touches tables without a `workspace_id` column.

Incorrect:

```ts
const invoice = await db.query.invoices.findFirst({
  where: eq(invoices.id, id),
});
```

Correct:

```ts
const { workspaceId } = await requireWorkspace(req);
const invoice = await db.query.invoices.findFirst({
  where: and(eq(invoices.id, id), eq(invoices.workspaceId, workspaceId)),
});
```

• 该文件夹中直接存放、且 frontmatter 含有 files 的每个 .md 文件都是一个检查。HeyDeer 会忽略该文件夹中的其他文件，例如 README.md 和为其他审查工具编写的检查。
• 文件名以字母或数字开头，只能包含字母、数字、.、_ 和 -。

编写有效的检查

每个匹配的检查都有自己的审查员，所以检查很彻底，但也会用掉更多积分。检查只留给漏掉代价高、又容易被忽略的要求，其余的放在 REVIEW.md 或 AGENTS.md 中。

• 写你的代码库特有的内容。每次审查本来就会查找常见的缺陷和安全问题，所以像“查询必须安全”这样的检查只会增加成本，不会多发现问题。
• 每个检查只写一项要求，或几项密切相关的要求。把不相关的要求捆在一起的检查，每项都只能查得更浅。
• 不要把一项要求拆到多个检查中，并把 files 限定在可能违反这项要求的地方，让检查只在需要时运行。
• 把要求写成针对代码的条件：什么会违反它，什么能满足它，以及为什么重要，HeyDeer 才能判断你没预料到的情况。附上来自你代码库的简短错误示例和正确示例。
• 好的检查大多一屏就能写完。如果多个检查需要相同的背景知识，就把它移到技能中。
• 在违反该要求的 PR 上测试新检查，并确认有发现的问题注明了你的检查。

结果如何显示

代码违反检查时，HeyDeer 会在 GitHub 和 HeyDeer 中报告一个发现的问题，并在 仓库检查: 后注明检查的文件名。没有发现问题的检查不会在审查中添加任何内容。

这些发现的问题与其他问题一样，计入 HeyDeer Review 检查和自动批准的判断。HeyDeer Review 检查的摘要还会统计失败的仓库检查数量。

如果 HeyDeer 无法完成某个检查，HeyDeer Review 检查会显示“审查未完成”并失败；请重新发起审查。

Frontmatter 参考

Frontmatter 是两行 --- 之间的 YAML，包含以下键。

HeyDeer 会忽略其他键，例如其他审查工具读取的键。

如果检查无效（例如模式列表中只有排除模式），HeyDeer 会跳过该检查，并在审查说明中列出它。审查仍会进行，但 HeyDeer 不会自动批准。

检查覆盖哪些文件

至少有一个改动文件匹配时，检查才会生效，HeyDeer 会让它重点关注这些文件。

• 使用 files: ["**"] 覆盖所有改动文件。
• 模式相对于仓库根目录，支持 *、** 和 {a,b}。不含斜杠的模式（例如 *.sql）可匹配任意文件夹中的文件。
• 模式按顺序应用，由最后一个匹配文件的模式决定，因此后面的模式可以重新包含之前被排除的文件。
• 生成文件永远不会匹配。

如果检查似乎被忽略，参见故障排除。

限制

每个工作区在任意 30 天内最多可以启动 30 个检查生成任务，按其所有仓库合计，失败或被取消的任务也计入。

检查文件最大为 16,000 字节。

每次审查按文件名顺序最多运行 10 个匹配的检查。HeyDeer 会把其余检查列在审查说明下，HeyDeer Review 检查会显示“审查未完成”，HeyDeer 也不会自动批准这次审查。

缩小或合并检查，减少匹配的数量。如需决定哪些检查先运行，可以给文件名加上数字前缀，例如 10-auth.md。

检查无效时

没有 frontmatter 或 files 键的文件会被忽略。无效的 YAML、超出大小限制的 frontmatter、空的 files 模式以及只有排除项的模式会被跳过并报告。

对于匹配变更文件的检查，HeyDeer 还会验证文件名、文件大小和技能名称。无效的检查会被跳过，并列在审查说明中。审查会继续，但 HeyDeer 不会自动批准。

在 PR 中修复该检查，然后评论 @heydeer review。