Best Practices

Prüfhinweise schreiben

Prüfanweisungen und AGENTS.md funktionieren am besten als kurze, konkrete Regeln, die ein neues Teammitglied befolgen könnte. Zur Wahl zwischen beiden siehe Wohin welche Regel gehört.

Von echten Prüfungen ausgehen

Lassen Sie HeyDeer einige Pull Requests prüfen, bevor Sie etwas schreiben. Fügen Sie eine Regel hinzu, wenn etwas wiederholt übersehen wird oder ein unerwünschter Kommentar immer wieder auftaucht, jeweils wenige Regeln auf einmal, und lesen Sie die nächsten Prüfungen, um die Wirkung zu sehen.

Kurze, konkrete Regeln schreiben

Gruppieren Sie Regeln unter wenigen Überschriften, etwa „Priorities“, „Leave alone“ und „Conventions“.
Schreiben Sie eine Regel pro Aufzählungspunkt, und nennen Sie die Pfade, Funktionen und Bibliotheken, um die es geht.
Nennen Sie die Begründung, wenn sie nicht offensichtlich ist.
Halten Sie Ausnahmen eng: „Keine Kommentare zu Dateien in scripts/one-off/“, nicht „Keine Kommentare zu Skripten“, was auch echte Probleme verbirgt.
Zeigen Sie einige Zeilen falschen und richtigen Codes aus Ihrer Codebasis.
Bleiben Sie deutlich unter dem Limit von 12.000 Zeichen. Wenn die Anweisungen wachsen, verschieben Sie Konventionen nach AGENTS.md und harte Anforderungen in Repository-Prüfungen.

Was nicht hineingehört

Nicht aufnehmen	Warum	Stattdessen
Formatierungsregeln, etwa Einrückung oder Importreihenfolge	Ein Formatter oder Linter setzt sie exakt durch.	Führen Sie diese Tools in der CI aus.
„Gründlicher sein“, „Nichts übersehen“	Sie geben HeyDeer nichts Konkretes, woran es sich halten kann.	Nennen Sie die relevanten Risiken, oder verwenden Sie die Tiefe Tiefgehend oder einen breiteren Feedback-Umfang.
Rollenvorgaben wie „Du bist ein erfahrener Security-Engineer“	Eine Rolle sagt nicht, worauf geachtet werden soll.	Schreiben Sie die Regeln auf, die diese Person anwenden würde.
„Merge blockieren, wenn …“, „Kleine PRs genehmigen“	Anweisungen beeinflussen die Prüfung, nicht das, was HeyDeer auf GitHub tut.	Verwenden Sie „Prüfung bei gefundenen Problemen fehlschlagen lassen“ zusammen mit einer Branch-Regel sowie Automatische Genehmigung.
„Tests ausführen“, „Zuerst das Projekt bauen“	HeyDeer liest Code. Es führt nie Code, Tests oder Builds aus.	Verlangen Sie, was HeyDeer durch Lesen überprüfen kann.
Links wie „Die Standards in unserem Wiki befolgen“	HeyDeer kann keine Weblinks öffnen.	Kopieren Sie die relevanten Regeln, legen Sie das Dokument im Repository ab oder verbinden Sie einen MCP-Server.
„Befunde auf Japanisch schreiben“	Die Sprache ist eine Einstellung, die auch Zusammenfassungen und Überschriften umfasst.	Legen Sie die Sprache der Prüfung fest.

Vorher und nachher

Vorher:

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.

Nachher:

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

Die Überarbeitung macht aus der Rollenvorgabe und dem Wiki-Link konkrete Regeln. Alles andere wandert an die Orte aus der Tabelle oben.