Wirksame Prüfungen schreiben

Eine entscheidbare Regel pro Prüfung

Legen Sie jede eigenständige Regel in eine eigene Datei. Befunde werden mit dem Dateinamen der Prüfung gekennzeichnet, und jede Datei hat ihre eigenen Muster.

Formulieren Sie die Regel als Bedingung an den Code: was gegen sie verstößt und was sie erfüllt.

Mit Dateimustern eingrenzen

Fügen Sie files-Muster hinzu, damit die Prüfung nur dort gilt, wo die Regel relevant ist; ohne Muster gilt sie für jeden Pull Request. Schließen Sie Tests oder Fixtures mit ! aus, und setzen Sie jedes Muster im YAML in Anführungszeichen.

Begründung und Beispiele angeben

Erklären Sie, warum die Regel wichtig ist, damit HeyDeer auch Fälle beurteilen kann, die nicht vorhergesehen wurden. Beschreiben Sie korrekten Code ebenso wie Verstöße, mit einem kurzen falschen und richtigen Beispiel aus Ihrer Codebasis.

Prüfungen kurz und geordnet halten

Die meisten guten Prüfungen passen auf einen Bildschirm. Wenn mehrere Prüfungen denselben Hintergrund benötigen, verschieben Sie ihn in einen Skill.

Jede Prüfung wendet höchstens 10 passende Repository-Prüfungen an, in der Reihenfolge der Dateinamen. Stellen Sie den wichtigsten daher Zahlen voran, etwa 10-auth.md. Setzen Sie bei einer einfachen Repository-Prüfung skip_extra_reviewers: true; tiefgehende Prüfungen behandeln sie dann wie „Standard“. Siehe Bis zu 10 Repository-Prüfungen pro Prüfung.

An einem echten Pull Request testen

1. Mergen Sie die Prüfung. HeyDeer liest Repository-Prüfungen aus dem Basis-Branch.
2. Öffnen Sie einen Pull Request, der gegen die Regel verstößt, und vergewissern Sie sich, dass ein Befund Ihre Prüfung nennt. Vergewissern Sie sich außerdem, dass Code, der die Regel befolgt, keinen Befund erhält.
3. Wenn die Prüfung korrekten Code bemängelt, schärfen Sie die Regel oder die Muster nach. Wenn sie einen Fall übersieht, fügen Sie diesen Fall als falsches Beispiel hinzu.

Anti-Patterns

Vorher und nachher

Vorher:

---
files: "src/**"
---
Follow API best practices. Make sure endpoints are secure, fast,
and well tested, and that naming is consistent. Run the test suite
and fail if anything breaks.

Nachher, als .agents/checks/20-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)),
});
```

Die Überarbeitung behält ein einziges Anliegen bei, beschränkt es auf API-Handler, sagt, was fehlschlägt und was besteht, und erklärt das Risiko. Die anderen Anliegen werden zu eigenen Prüfungen oder wandern in Tools und AGENTS.md.