Claude Code Styleguide-Prompts für konsistente Code-Reviews

Warum sich Styleguide-Verstöße so schnell ausbreiten

Verstöße gegen den Styleguide tauchen selten als ein großer Fehler auf. Sie beginnen als kleine „ist nah genug“-Entscheidungen, die in einem Pull Request harmlos wirken, und häufen sich dann, bis der Codebasis uneinheitlich und schwerer lesbar wird.

Style-Drift sieht oft so aus: eine Datei verwendet userID, eine andere userId, eine dritte uid. Ein Handler gibt { error: "..." } zurück, ein anderer wirft, ein dritter loggt und gibt null zurück. Jede Änderung ist klein, aber zusammen entsteht ein Repo, in dem Muster nicht mehr vorhersehbar sind.

Schnelles Iterieren und mehrere Beitragende verschlimmern das Problem. Menschen kopieren, was sie sehen, besonders unter Zeitdruck. Wenn der jüngste Code im Repo eine Abkürzung nutzte, wird diese Abkürzung zur Vorlage für die nächste Änderung. Nach ein paar Wochen ist der „Standardstil“ nicht mehr der geschriebene Guide, sondern das, was zuletzt passiert ist.

Darum muss das Ziel konsistente Konventionen sein, nicht persönliche Vorlieben. Die Frage ist nicht „Gefällt mir dieser Name?“, sondern „Entspricht das den Regeln, die wir vereinbart haben, sodass die nächste Person es ohne Nachdenken übernehmen kann?"

Verstöße früh zu erkennen heißt, schlechte Muster zu stoppen, bevor sie sich durch Copy-Paste verbreiten. Konzentriere dich auf neuen und geänderten Code, behebe das erste Auftreten einer neuen Inkonsistenz und blockiere Merges, die neue Drift einführen. Wenn du ein Problem meldest, füge ein kurzes bevorzugtes Beispiel hinzu, das andere beim nächsten Mal nachahmen können.

Ein realistisches Beispiel: Ein Entwickler fügt einen neuen API-Endpunkt hinzu und loggt rohe Request-Bodies „nur zum Debuggen“. Wenn das landet, kopiert der nächste Endpoint es, und bald tauchen sensible Daten in Logs auf. Das im ersten PR zu fangen ist günstig. Es erst nachträglich zu bereinigen ist schmerzhaft und riskant.

Verwandle deinen Styleguide in klare, prüfbare Regeln

Ein Styleguide funktioniert in Reviews nur, wenn er wie eine Checkliste formuliert ist, nicht wie eine Sammlung von Vorlieben. Formuliere jede Richtlinie als Regel, die auf einem Diff geprüft werden kann.

Ordne Regeln in vier Bereiche, damit sie schwer zu übersehen sind: Naming, Layering, Error Handling und Logging. Für jeden Bereich schreibe zwei Dinge: was zwingend erfüllt sein muss und was verboten ist.

Bestimme die Gewichtung jeder Regel im Voraus:

• Mandatory: ein Verstoß blockiert die Änderung.
• Recommended: beheben, es sei denn, es gibt einen klaren Grund dagegen.
• Optional: nett zu haben, niemals blockierend.

Setze den Scope, damit Reviews nicht in endlose Refactors ausarten. Eine einfache Regel funktioniert gut: „Neuer und geänderter Code muss konform sein; bestehender, unberührter Code wird nicht umgeschrieben, es sei denn, er blockiert den Fix.“ Wenn du Aufräumarbeit willst, begrenze sie zeitlich als separate Aufgabe.

Definiere außerdem das gewünschte Review-Output, damit es leicht umsetzbar ist: ein Pass/Fail-Urteil, eine Liste von Verstößen mit Datei- und Zeilenangaben, vorgeschlagene Fixes als konkrete Änderungen und eine kurze Risikoanmerkung, wenn etwas Bugs oder Leaks verursachen könnte.

Beispiel: Wenn ein PR rohe Nutzer-Tokens loggt, sollte das Review unter „Logging: niemals Secrets loggen“ fehlschlagen und stattdessen vorschlagen, eine Request-ID zu loggen.

Prompt-Struktur, die Regeln erzwingt statt Meinungen

Style-Prompts scheitern, wenn sie wie persönliche Präferenzen klingen. Ein gutes Review-Prompt liest sich wie ein Vertrag: klare Nicht-Verhandelbares, klar benannte Ausnahmen und ein vorhersehbares Output.

Beginne mit zwei kurzen Blöcken: was zwingend wahr sein muss und was gebogen werden kann. Füge dann eine Entscheidungsregel hinzu: „Wenn unklar, markiere mit Needs Clarification. Rate nicht.“

Erzwinge Evidenz. Wenn das Tool einen Verstoß meldet, fordere es auf, den genauen Identifier und den Dateipfad zu zitieren, nicht eine vage Beschreibung. Diese einzige Vorgabe reduziert viel Hin und Her.

Halte den Scope eng: kommentiere nur geänderte Zeilen und direkt betroffene Codepfade. Wenn du ungefragte Refactors erlaubst, wird Stilprüfung zum „schreibe die Datei neu“ und die Leute hören auf, dem Feedback zu vertrauen.

Hier ist eine Struktur, die du wiederverwenden kannst:

Role: strict style guide reviewer.
Input: diff (or files changed) + style guide rules.
Non-negotiables: [list].
Allowed exceptions: [list].
Scope: ONLY comment on changed lines and directly impacted code paths. No unrelated refactors.
Evidence: Every finding MUST include (a) file path, (b) exact identifier(s), (c) short quote.
Output: structured compliance report with pass/fail per category + minimal fixes.

Fordere, dass der Report jedes Mal dieselben Abschnitte behält, selbst wenn einige „No issues found“ sind: Naming, Layering, Error handling, Logging.

Wenn dort steht „service layer leaking DB details“, muss es etwas zitieren wie internal/orders/service/order_service.go und den genauen Aufruf (z. B. db.QueryContext), damit du das Leak beheben kannst, ohne über die Bedeutung zu debattieren.

Schritt für Schritt: Baue einen Style-Check Prompt-Workflow

Ein Styleguide hält sich, wenn der Prozess reproduzierbar ist. Das Ziel ist, das Modell Regeln prüfen zu lassen, nicht Geschmack zu diskutieren, und es jedes Mal gleich zu tun.

Verwende einen einfachen Zwei-Pass-Workflow:

1. Füge deine Standards als kompakten, nummerierten Regelblock ein (10–25 Zeilen). Halte jede Regel prüfbar.
2. Gib Kontext zur Änderung: das Diff, die getroffenen Dateien und einen Satz zur Absicht.
3. Fordere zuerst einen Verletzungsreport an. Verlange Datei- und Zeilenangaben, einen kurzen Grund und die genaue Regelnummer.
4. Erst nach dem Report frage nach dem kleinsten Patch, um Konformität zu erreichen.
5. Führe denselben Prompt erneut auf dem aktualisierten Code aus, um zu bestätigen, dass nichts mehr offen ist.

Beispiel: Ein PR fügt einen neuen Endpoint hinzu. Pass 1 meldet, dass der Handler direkt PostgreSQL anspricht (Layering), gemischte Namensgebung für Request-Structs verwendet wird (Naming) und volle E-Mails geloggt werden (Logging). Pass 2 schlägt minimale Fixes vor: verschiebe DB-Call in einen Service oder Repository, benenne die Struct um und maskiere die E-Mail in Logs. Sonst ändert sich nichts.

Namenskonventionen: Prompts, die die kleinen Dinge auffangen

Namensprobleme wirken klein, verursachen aber echte Kosten: Leute lesen die Absicht falsch, Suchen werden schwerer und „fast gleiche“ Namen vervielfältigen sich.

Lege die Namensregeln fest, die der Reviewer in der gesamten Änderung durchsetzen muss: Dateinamen, exportierte Typen, Funktionen, Variablen, Konstanten und Tests. Sei explizit bei Casing (camelCase, PascalCase, snake_case) und wähle eine Akronym-Regel (z. B. APIClient vs ApiClient). Erzwinge diese Regel überall.

Standardisiere auch geteilte Vokabeln: Fehlertypen, Log-Felder und Config-Keys. Wenn Logs request_id verwenden, erlaube nicht reqId in einer Datei und requestId in einer anderen.

Eine praktische Reviewer-Anweisung:

Check every new or renamed identifier. Enforce casing + acronym rules.
Flag vague names (data, info, handler), near-duplicates (userId vs userID), and names that contradict behavior.
Prefer domain language: business terms over generic tech words.

Fordere einen kurzen Report an: die drei verwirrendsten Namen, alle Near-Duplicates und welche Variante beibehalten werden soll sowie alle Log/Config/Error-Namen, die nicht dem Standard entsprechen.

Layering-Regeln: Verantwortlichkeiten sauber trennen

Layering-Regeln funktionieren am besten in klarer Sprache: Handler sprechen HTTP, Services halten Business-Logik, Repositories sprechen zur Datenbank.

Sichere die Abhängigkeitsrichtung. Handler dürfen Services aufrufen. Services dürfen Repositories aufrufen. Repositories dürfen keine Services oder Handler aufrufen. Handler sollten keine DB-Codes, SQL-Helper oder ORM-Modelle importieren. Wenn du Shared-Packages (config, time, IDs) nutzt, halte sie frei von Applikationslogik.

Weise Cross-Cutting-Aufgaben ein Zuhause zu. Validation gehört oft an die Grenze für die Request-Form und in den Service für Business-Regeln. Authorization beginnt häufig im Handler (Identity, Scopes), aber der Service sollte die finale Entscheidung durchsetzen. Mapping gehört an Layer-Grenzen: Handler mappt HTTP auf Domain-Input, Repository mappt DB-Rows auf Domain-Typen.

Droppe diesen Block in ein Prompt, um Reviews konkret zu halten:

Check layering: handler -> service -> repository only.
Report any leaks:
- DB types/queries in handlers or services
- HTTP request/response types inside services or repositories
- repository returning DB models instead of domain objects
- auth/validation mixed into repository
For each leak, propose the smallest fix: move function, add interface, or rename package.

Mach den Report explizit: nenne die Datei, das Layer, zu dem sie gehört, den Import oder Aufruf, der die Regel bricht, und die minimale Änderung, die das Muster am Ausbreiten hindert.

Fehlerbehandlungs-Konventionen: Konsistenz unter Druck

Die lautesten Style-Debatten entstehen häufig, wenn etwas in Prod kaputtgeht. Eine klare Error-Handling-Policy hält Fixes ruhig, weil alle wissen, wie „richtig“ aussieht.

Formuliere die Philosophie und setze sie durch. Zum Beispiel: „Wrap errors to add context; create a new error only when changing meaning or mapping to a user message. Return raw errors only at the system boundary." Dieser eine Satz verhindert zufällige Muster.

Trenne user-facing Text von internen Details. Nutzer-Nachrichten sollten kurz und sicher sein. Interne Errors können den Operationsnamen und Schlüssel-Identifiers enthalten, aber keine Secrets.

Prüfe in Reviews wiederkehrende Fehler: geschluckte Fehler (geloggt, aber nicht zurückgegeben), mehrdeutige Rückgaben (nil Wert und nil Error nach einem Fehlschlag) und user-facing Messages, die Stacktraces, Query-Text, Tokens oder PII leaken. Wenn du Retries oder Timeouts unterstützt, mache sie explizit erforderlich.

Beispiel: Ein Checkout call time-out. Der Nutzer sieht „Payment service is taking too long.“ Intern wrappen wir das Timeout mit op=checkout.charge und der Bestell-ID, sodass es durchsuchbar und handhabbar ist.

Logging-Konventionen: lesbar, durchsuchbar und sicher

Logs helfen nur, wenn alle gleich schreiben. Wählt jeder Entwickler eigene Wortwahl, Level und Felder, wird Suchen zur Ratespiel.

Mache Log-Levels nicht verhandelbar: debug für Entwicklungsdetails, info für normale Meilensteine, warn für unerwartete, aber gehandelte Situationen und error, wenn die nutzer-relevante Aktion fehlschlägt oder Aufmerksamkeit braucht. Halte fatal/panic selten und an eine klare Crash-Policy gebunden.

Strukturierte Logs sind wichtiger als perfekte Sätze. Erfordere stabile Schlüssel-Namen, damit Dashboards und Alerts nicht brechen. Lege ein kleines Kernset fest (z. B. event, component, action, status, duration_ms) und halte es konsistent.

Behandle sensible Daten als harte Grenze. Sei explizit, was nie geloggt werden darf: Passwörter, Auth-Tokens, komplette Kreditkartennummern, Secrets und rohe personenbezogene Daten. Nenne Dinge, die harmlos wirken, es aber nicht sind, wie Passwort-Reset-Links, Session-IDs und komplette Request-Bodies.

Korrelations-IDs machen Debugging über Layer hinweg möglich. Erfordere ein request_id in jeder Logzeile innerhalb einer Anfrage. Wenn du user_id loggst, definiere, wann das erlaubt ist und wie fehlende/ anonyme Nutzer dargestellt werden.

Ein wiederverwendbarer Prompt-Block:

Review the changes for logging conventions:
- Check level usage (debug/info/warn/error). Flag any level that does not match impact.
- Verify structured fields: require stable keys and avoid free-form context in the message.
- Confirm correlation identifiers: request_id on all request-bound logs; user_id only when allowed.
- Flag any sensitive data risk (tokens, secrets, personal data, request/response bodies).
- Identify noisy logs (in loops, per-item logs, repeated success messages) and missing context.
Return: (1) violations with file/line, (2) suggested rewrite examples, (3) what to add or remove.

Vor dem Merge einen schnellen „Safety Pass“ machen: jede neue Logzeile ohne request_id für request-gebundene Arbeit, neue Keys, die bestehende Namen ändern (userId vs user_id), Error-Logs ohne Hinweis, was fehlgeschlagen ist (Operation, Resource, Status), High-Volume-Logs, die bei jeder Anfrage feuern, und jede Möglichkeit, dass Secrets oder PII in Feldern oder Messages auftauchen.

Wie du Verstöße stoppst, bevor sie sich ausbreiten

Behandle Style-Drift wie einen Build-Break, nicht wie einen Vorschlag. Füge ein striktes Gate vor dem Merge hinzu, das ein klares Pass oder Fail zurückgibt. Wenn eine Mandatory-Regel gebrochen wird (Naming, Layer Boundaries, Logging Safety, Error Handling), schlägt das Gate fehl und zeigt exakte Dateien und Zeilen.

Halte das Gate kurz. Ein praktischer Trick ist, pro Regel ein YES/NO-Checklist zu verlangen und Approval zu verweigern, wenn ein Item NO ist.

Eine PR-gerechte Checkliste, die die meisten Probleme fängt:

• Naming: entspricht dem genehmigten Muster für Dateien, Typen und Funktionen
• Layering: keine direkten Aufrufe, die Layer überspringen (z. B. Handler ruft DB)
• Errors: konsistent mit Kontext zurückgegeben, nichts wird still verschluckt
• Logging: konsistente Felder, keine Secrets, Level entspricht Impact
• Tests/Docs: sind bei Veränderungen von Verhalten oder öffentlichen APIs aktualisiert

Wenn das Tool Fixes vorschlägt, erzeuge für jede berührte Regel einen kleinen, konformen Snippet. Das verhindert vage Rückmeldungen wie „rename for clarity“.

Häufige Fallen beim Einsatz von Prompts für Style Enforcement

Der schnellste Weg, dass ein Styleguide scheitert, ist, Interpretationsspielraum zu lassen. Wenn zwei Reviewer dieselbe Regel lesen und zu unterschiedlichen Schlussfolgerungen kommen, wird das Tool Geschmack durchsetzen, nicht Standards.

Naming ist ein häufiges Beispiel. „Benutze klare Namen“ ist nicht prüfbar. Schärfe es zu etwas Verifizierbarem: „Funktionen sind Verben (z. B. createInvoice), Booleans beginnen mit is/has/can, exportierte Typen sind PascalCase."

Eine andere Falle ist, alles auf einmal zu verlangen. Wenn ein Prompt versucht, Naming, Layering, Errors, Logging, Tests und Performance abzudecken, wird das Feedback oberflächlich. Teile Reviews in fokussierte Pässe auf, wenn du Tiefe brauchst, oder beschränke das Gate auf Mandatory-Regeln.

Die Probleme, die Enforcement am häufigsten aus der Bahn werfen:

• Vage Regeln: ersetze „sauber“ und „konsistent“ durch messbare Sprache.
• Style-Fixes mit Redesign mischen: lasse ein Style-Prompt keine neue Architektur vorschlagen.
• Keine zitierte Evidenz: verlange, dass jeder Kommentar den exakten Identifier oder das Snippet zitiert.
• Stille Ausnahmen: wenn du eine Ausnahme erlaubst, fordere eine kurze Notiz, warum und wann sie entfernt werden soll.

Wenn du Prompts wie Tests behandelst, erhältst du vorhersehbare Durchsetzung. Wenn du sie als Rat behandelst, schleichen sich Verstöße ein und vermehren sich.

Kurze Checkliste, die du bei jeder Änderung laufen lassen kannst

Führe einen schnellen Pass über das Diff (nicht über das ganze Repo) aus und bestätige:

• Naming: neue Identifier folgen eurem Muster (Case, Präfixe, Suffixe). Ein Konzept ist über Dateien hinweg einheitlich benannt.
• Layering: Abhängigkeiten gehen nur in erlaubte Richtung. Niedrigere Layer importieren niemals höhere.
• Errors: Fehler werden mit Kontext zurückgegeben. Nichts wird still ignoriert.
• Logging: korrektes Level, stabile Felder, keine Secrets oder PII.
• Finaler Pass: der Reviewer schreibt genau: „no mandatory violations found“ oder listet die vor dem Merge zu behebenden Verstöße.

Behalte ein kleines Prompt-Template und füge es bei jeder Änderung ein:

Review ONLY the changed code against our rules for naming, layering, errors, and logging.
List mandatory violations first (with file + line if available). Then list optional suggestions.
End with either: “no mandatory violations found” or “mandatory violations found”.

Beispiel: Eine neue Funktion procUsr() in einem Handler, die direkt in PostgreSQL schreibt, sollte Naming und Layering failen, selbst wenn das Feature funktioniert. Das hier zu fangen verhindert, dass sich der Fehler per Copy-Paste verbreitet.

Beispiel: ein realistisches Review, das Probleme früh behebt

Ein Kollege fügt einen neuen Endpoint hinzu: POST /v1/invoices/{id}/send. Es betrifft einen Handler, einen Service und den Storage.

Beim ersten Pass willst du einen Report, keinen Rewrite:

Pass 1 (report only)
You are a strict style checker. Read the patch.
Rules: naming must match our guide, handlers call services only, services call storage only, no SQL in handlers,
errors must be wrapped with context, logs must be structured and not leak PII.
Output: a numbered list of violations with file:line, rule name, and one-sentence impact. Do not propose fixes.
If a rule might be intentionally broken, ask one clarification question.

Typische Befunde: SendInvoiceNow() vs SendInvoice Namensmismatch, der Handler ruft db.QueryRow direkt auf, err wird roh ohne Kontext zurückgegeben, und noisy Logs wie log.Printf("sending invoice %v", invoice), die komplette Objekte ausgeben.

Der zweite Pass verlangt minimale, sichere Änderungen:

Pass 2 (minimal fix suggestions)
Using the violations list, propose the smallest code edits to comply.
Constraints: keep behavior the same, no refactors beyond what is needed, show suggested function names and where code should move.
For each fix, include 1-2 lines of example code.

Wenn eine Regel gebrochen werden darf, sage es offen: „Exceptions are permitted only if you add a short comment explaining why, and you add a follow-up task to remove the exception."

Nach dem Fix wird der Handler zu einem dünnen Adapter, der Service steuert den Workflow, Storage enthält die Query, Fehler werden zu fmt.Errorf("send invoice: %w", err) gewrappt und Logs sind eine saubere Zeile mit sicheren Feldern (Invoice ID, nicht das komplette Invoice-Objekt).

Nächste Schritte: Routinemäßig machen, ohne zu verlangsamen

Wähle ein team-genehmigtes Prompt und behandle es wie ein gemeinsames Werkzeug. Starte mit dem, was euch in Reviews am meisten schadet (Naming-Drift, Layer-Leaks, inkonsistente Errors, unsichere Logs). Aktualisiere das Prompt nur, wenn du einen echten Verstoß in echtem Code siehst.

Behalte einen kleinen Regelblock oben im Prompt und füge ihn bei jedem Review unverändert ein. Wenn jeder die Regeln bei jeder Review ändert, habt ihr keinen Standard — ihr habt eine Debatte.

Eine einfache Kadenz hilft: eine Person sammelt die häufigsten Stilfehler der Woche und ihr ergänzt genau eine klarere Regel oder ein besseres Beispiel.

Wenn ihr in einem chatgesteuerten Build-Flow wie Koder.ai (koder.ai) arbeitet, lohnt es sich, dieselben Gate-Checks während der Änderungen laufen zu lassen, nicht nur am Ende. Features wie Planning, Snapshots und Rollback helfen, Stilfixes klein und reversibel zu halten, bevor ihr Source-Code exportiert.