Repository-Prüfungen

Prüfungen schreiben lassen

Wähle im Dashboard unter Erste Schritte die Option Repository-Prüfungen einrichten. HeyDeer liest das Repository und seine bisherigen Pull Requests und öffnet dann einen Pull Request, der Prüfungen hinzufügt. Dafür werden keine Credits verbraucht.

Wenn dein eigener Coding-Agent sie schreiben soll, gib ihm diesen Prompt:

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.

Eine Repository-Prüfung hinzufügen

1. Lege eine Markdown-Datei in .agents/checks/ an, etwa api-workspace-scope.md.
2. Beginne sie mit Frontmatter, das unter files die Dateien aufführt, die die Repository-Prüfung abdeckt.
3. Schreibe unter das Frontmatter die Anforderung: was gegen sie verstößt, was sie erfüllt und warum sie wichtig ist.
4. Committe sie in einem Pull Request. HeyDeer liest Repository-Prüfungen aus dem Pull Request, sodass die neue Repository-Prüfung schon bei der Prüfung dieses Pull Requests greift. Siehe Was ein Pull Request ändern kann.

.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)),
});
```

• Jede .md-Datei direkt in diesem Ordner, deren Frontmatter files enthält, ist eine Repository-Prüfung. Andere Dateien im Ordner, etwa README.md und Prüfungen anderer Werkzeuge zur Codeprüfung, ignoriert HeyDeer.
• Dateinamen beginnen mit einem Buchstaben oder einer Ziffer und enthalten nur Buchstaben, Ziffern, ., _ und -.

Eine wirksame Repository-Prüfung schreiben

Jede passende Repository-Prüfung bekommt einen eigenen Prüfer. Sie ist daher gründlich, verbraucht aber mehr Credits. Nutze Repository-Prüfungen für Anforderungen, deren Übersehen teuer ist und die leicht übersehen werden, und schreib den Rest in REVIEW.md oder AGENTS.md.

• Schreib, was für deine Codebasis spezifisch ist. Jede Prüfung sucht bereits nach gängigen Fehlern und Sicherheitsproblemen. Eine Repository-Prüfung wie „Abfragen müssen sicher sein“ kostet daher mehr, ohne mehr zu finden.
• Gib jeder Repository-Prüfung eine Anforderung oder wenige eng verwandte. Eine Repository-Prüfung, die nicht zusammenhängende Anforderungen bündelt, prüft jede davon weniger gründlich.
• Verteile eine Anforderung nicht auf mehrere Repository-Prüfungen, und beschränke files auf die Stellen, an denen die Anforderung verletzt werden kann, damit die Prüfung nur läuft, wo es darauf ankommt.
• Formuliere die Anforderung als Bedingung an den Code: was sie verletzt, was sie erfüllt und warum sie wichtig ist, damit HeyDeer auch Fälle beurteilen kann, die du nicht vorhergesehen hast. Füge ein kurzes falsches und ein richtiges Beispiel aus deiner Codebasis hinzu.
• Die meisten guten Repository-Prüfungen passen auf einen Bildschirm. Wenn mehrere davon dieselben Hintergrundinformationen benötigen, lagere diese in einen Skill aus.
• Teste eine neue Repository-Prüfung an einem Pull Request, der gegen die Anforderung verstößt, und vergewissere dich, dass ein Befund sie nennt.

Wie Ergebnisse angezeigt werden

Wenn Code gegen eine Repository-Prüfung verstößt, meldet HeyDeer auf GitHub und in HeyDeer einen Befund, der nach Repository-Prüfung: ihren Dateinamen nennt. Eine Repository-Prüfung ohne Befunde taucht im Prüfergebnis nicht auf.

Diese Befunde zählen wie alle anderen für den Check HeyDeer Review und die automatische Genehmigung. Die Zusammenfassung des Checks HeyDeer Review zählt außerdem die fehlgeschlagenen Repository-Prüfungen.

Wenn HeyDeer eine Repository-Prüfung nicht abschließen kann, zeigt der Check HeyDeer Review „Prüfung unvollständig“ und schlägt fehl; fordere eine weitere Prüfung an.

Frontmatter-Referenz

Das Frontmatter ist YAML zwischen zwei ----Zeilen, mit den unten aufgeführten Schlüsseln.

Andere Schlüssel, etwa solche für andere Werkzeuge zur Codeprüfung, ignoriert HeyDeer.

Ist eine Repository-Prüfung ungültig, etwa weil ihre Muster nur Ausschlüsse enthalten, überspringt HeyDeer sie und nennt sie unter Hinweise zur Prüfung. Die Prüfung läuft trotzdem, aber HeyDeer genehmigt sie nicht automatisch.

Welche Dateien eine Repository-Prüfung abdeckt

Eine Repository-Prüfung greift, wenn mindestens eine geänderte Datei zu ihr passt, und HeyDeer konzentriert sie auf diese Dateien.

• Verwende files: ["**"], um alle geänderten Dateien abzudecken.
• Muster sind relativ zum Stammverzeichnis des Repositorys und unterstützen *, ** und {a,b}. Ein Muster ohne Schrägstrich, etwa *.sql, passt in jedem Ordner.
• Muster werden der Reihe nach angewendet, und das letzte passende Muster entscheidet über eine Datei. So kann ein späteres Muster Dateien wieder einschließen, die ein früherer Ausschluss entfernt hat.
• Generierte Dateien passen nie.

Wenn eine Repository-Prüfung ignoriert zu werden scheint, siehe Fehlerbehebung.

Grenzen

Ein Workspace kann in jedem Zeitraum von 30 Tagen über alle seine Repositorys hinweg bis zu 30 Aufgaben zur Erstellung von Repository-Prüfungen starten, einschließlich fehlgeschlagener oder abgebrochener Aufgaben.

Die Datei einer Repository-Prüfung darf bis zu 16.000 Byte groß sein.

Eine Prüfung führt höchstens 10 passende Repository-Prüfungen aus, in der Reihenfolge der Dateinamen. HeyDeer führt die übrigen unter Hinweise zur Prüfung auf, der Check HeyDeer Review zeigt „Prüfung unvollständig“, und HeyDeer genehmigt diese Prüfung nicht automatisch.

Grenze Repository-Prüfungen ein oder fasse sie zusammen, damit weniger passen. Um festzulegen, welche zuerst laufen, stelle ihren Dateinamen Zahlen voran, etwa 10-auth.md.

Wenn eine Repository-Prüfung ungültig ist

Dateien ohne Frontmatter oder ohne den Schlüssel files werden ignoriert. Ungültiges YAML, zu großes Frontmatter, leere files-Muster und Muster mit ausschließlich Ausschlüssen werden übersprungen und gemeldet.

Bei Repository-Prüfungen, die zu geänderten Dateien passen, validiert HeyDeer auch den Dateinamen, die Dateigröße und die Skill-Namen. Ungültige Repository-Prüfungen werden übersprungen und unter Hinweise zur Prüfung aufgeführt. Die Prüfung läuft weiter, aber HeyDeer genehmigt sie nicht automatisch.

Korrigiere die Repository-Prüfung im Pull Request und kommentiere dann @heydeer review.