Was macht clean-code-guard (Code-Qualitätsprüfung)?
Du überprüfst generierten oder geänderten Code, bevor er ausgeliefert wird. Wende die folgenden Regeln als Wächterdurchlauf nach dem ersten Implementierungsdurchlauf an – und sobald dieser Skill aktiv ist, wende ihn auf jede spätere Codeänderung in derselben Sitzung an, indem du die Selbstprüfung vor der Auslieferung nach jeder Bearbeitung erneut ausführst, anstatt aufgrund der früheren Aktivierung auf ungeschützte Ausgabe zurückzugreifen. Wenn der Benutzer diesen Skill vor dem Schreiben von Code explizit aufruft, verwende dieselben Regeln während des Schreibens und führe trotzdem die Selbstprüfung vor der Auslieferung durch.
Integration in das Agententeam
Die Repository-Regeln, akzeptierten Verträge, Rollenberechtigungen und der Benutzerbereich haben Vorrang vor diesem Leitfaden und seinen Verweisen. DEV (Entwickler) verwendet den Wächterdurchlauf auf seine eigenen Änderungen; CR (Code-Reviewer) verwendet den schreibgeschützten Überprüfungsmodus und bearbeitet die Implementierung nicht. Behandle numerische Grenzen, Namensverbote, Argumentsignaturen und Abstraktionsregeln als Signale zum Untersuchen, nicht als automatische Änderungen oder Blockaden. Ein Befund sollte einen konkreten Korrektheits- oder Wartungskosten im Kontext erklären; teile keinen zusammenhängenden Code auf, breche keine Schnittstellen auf oder füge Ausnahmekommentare hinzu, nur um eine Anzahl zu erfüllen. Überprüfe den geänderten Code und seine direkt betroffenen Aufrufer, nicht unzusammenhängende Schulden.
Alle von diesem Paket verwendeten Anleitungen und Checklisten sind lokal. Externe Veröffentlichungsnamen dienen nur der Quellenangabe; verwende Beweise aus dem Repository und die gebündelten Referenzen, anstatt zu navigieren. Wenn diese Aufgabe außerhalb des Bereichs dieses Skills fällt, folge dem normalen Prozess des Repositorys; kein übergeordneter Skill ist erforderlich.
Kompatibilität
Dies ist ein portabler Instruktions-Skill. Er benötigt keinen MCP-Server, Netzwerkzugriff, API-Schlüssel, Shell-Befehl, lokale ausführbare Datei oder gebündeltes Skript. Er kann in jeder Laufzeitumgebung verwendet werden, die SKILL.md sowie direkt verlinkte references/-Dateien unterstützt; agents/openai.yaml ist leichtgewichtige Anzeigemetadaten.
Dieser Skill ersetzt keine Projekt-Linter, Formatierer, Typprüfer oder Test-Runner. Verwende die eigenen Werkzeuge des Projekts für die mechanische Überprüfung; verwende diesen Skill für die Urteilsebene rund um Codequalität und Überprüfung.
So verwendest du diesen Skill
Dieser Skill hat drei Modi – wähle basierend auf der Anfrage des Benutzers.
Guard-Pass-Modus (empfohlen): Nachdem Code generiert, bearbeitet, umgestaltet oder korrigiert wurde, überprüfe den Diff oder die Zieldateien anhand der Immer angewendeten Imperative unten. Behebe Verstöße, bevor du das Ergebnis präsentierst, committest oder zusammenführst.
Live-Modus (explizit): Wenn der Benutzer diesen Skill vor einer riskanten Codebearbeitung aufruft, wende dieselben Imperative während des Schreibens an und führe dann die Selbstprüfung vor der Auslieferung durch. Wenn du gegen eine Regel verstößt, behebe es, bevor du es dem Benutzer zeigst.
Überprüfungsmodus (ausgelöst, wenn der Benutzer dich bittet, Code zu überprüfen, zu auditieren, zu kritisieren oder zu bewerten): Gehe references/review-checklist.md gegen die Zieldatei(en) durch und erstelle einen strukturierten Ergebnisbericht. Bearbeite im Überprüfungsmodus keinen Code, es sei denn, du wirst darum gebeten.
In allen drei Modi befinden sich die Regeltexte in references/. Lies die entsprechende Referenzdatei, wenn:
- Du auf eine Regel stößt, an deren Begründung du dich nicht vollständig erinnerst.
- Der Benutzer eine Regel hinterfragt und du die Quellenangabe benötigst.
- Du dich im Überprüfungsmodus befindest und die vollständige Checkliste benötigst.
- Der zu überprüfende Code ein bestimmtes Prinzip betrifft (z. B. Unterklassen → references/solid.md; Deduplizierung → references/dry-kiss-yagni.md).
Die Referenzdateien sind:
- references/naming-and-functions.md – Namen, Funktionsgröße, Parameter, Command/Query Separation.
- references/comments-and-formatting.md – Wann kommentieren, wann löschen, Anpassung an den Stil der Nachbarschaft.
- references/solid.md – SRP, OCP, LSP, ISP, DIP mit modernen Formulierungen und Erkennungsmustern.
- references/dry-kiss-yagni.md – Wissen vs. Codeduplizierung, Sandi Metz' Re-Inline-Regel, McCabe-Komplexität, Fowlers YAGNI-Kostenkategorien.
- references/ai-failure-modes.md – Die 14 systematischen Arten, wie LLMs schlechten Code produzieren. Lies diese Datei zuerst, wenn du ein KI-Agent bist, der diesen Skill liest. Sie ist die Datei mit der größten Hebelwirkung im Skill.
- references/review-checklist.md – Strukturierte Checkliste für den Überprüfungsmodus.
- references/sources.md – Zentrale Bibliographie für Quellen-URLs. Lies sie nur, wenn du eine externe Quelle überprüfen oder zitieren musst.
Beispiele
- Ein Codierungsagent implementiert einen Endpunkt: Verwende den Guard-Pass-Modus für den Diff, bevor das Ergebnis präsentiert oder committed wird.
- Der Benutzer fragt: „Überprüfe diesen PR“ oder „Sollte ich das zusammenführen?“: Verwende den Überprüfungsmodus und melde Ergebnisse aus references/review-checklist.md; bearbeite nichts, es sei denn, du wirst darum gebeten.
- Der Benutzer fragt: „Implementiere diesen Endpunkt mit clean-code-guard“: Verwende den Live-Modus während des Schreibens, führe dann die Selbstprüfung vor der Auslieferung durch.
- Der Benutzer fragt: „Refaktoriere diese Funktion, gleiches Verhalten“: Bewahre das beobachtbare Verhalten genau und behandle jede Fehlerbehebung als separate Änderung.
Erfolgskriterien
Dieser Skill funktioniert, wenn Codierungsaufgaben die aufgeführten Fehlermodi vermeiden, Code-Überprüfungsaufgaben priorisierte Ergebnisse mit konkreten Beweisen liefern und Refaktorisierungen das Verhalten bewahren, es sei denn, der Benutzer fordert explizit eine Verhaltensänderung. Er sollte bei konzeptionellen, CI-, Git-Workflow-, Prosa-, Datenanalyse- und Testausführungsaufgaben, die von den Frontmatter-Ausschlüssen abgedeckt werden, still bleiben.
Warum dieser Skill existiert
LLM-generierter Code hat messbare, systematische Fehlermodi, die generische „Folge Clean Code“-Anweisungen nicht abfangen. Beispiele, die durch veröffentlichte Forschung gestützt werden:
- Codeduplizierung ist um das 8-fache gestiegen in verfolgten Codebasen zwischen 2021 und 2024 (GitClear 2025 Bericht).
- Paket-Halluzinationsrate liegt im Durchschnitt bei 19,6 % über 16 Modelle hinweg (Spracklen et al., USENIX Security '25).
- LLMs verpacken riskante Operationen oft in breiten Catch-all-Handlern, die Fehler verschlucken (Karpathy).
- KI-Agenten „erklären trotz fehlgeschlagener Tests den Erfolg“ , indem sie hartcodierte Testfixture-Werte zurückgeben (Fowler, Patterns for Reducing Friction).
- Die Funktionsgröße stieg von 142 auf 267 Zeilen, die zyklomatische Komplexität von 4,2 auf 8,1 in KI-unterstützten Commits (GitClear).
Die klassischen Prinzipien (Clean Code, SOLID, DRY/KISS/YAGNI) sind immer noch die Grundlage – aber dieser Skill fügt die KI-spezifische Schicht hinzu, die die meisten Regelpakete vermissen.
Immer angewendete Imperative
Dies sind die Regeln, die bei jeder Codeänderung zu befolgen sind. Sie sind zwingend, keine Vorschläge.
Funktionen und Namen
- Namen zeigen die Absicht. Verwende niemals
data,data2,result,result_final,item,temp,value,obj,info,helper,manager,utilsoderhandle_*/process_*/do_*ohne Qualifizierer. Ein Name muss beantworten: Warum existiert es und was tut es? (Clean Code Kap. 2) - Funktionen bleiben klein. Ziel: ≤20 Zeilen, eine Abstraktionsebene, eine Sache. Wenn du eine Funktion mit einem Namen extrahieren kannst, der den Körper nicht wiederholt, hat die übergeordnete Funktion mehr als eine Sache getan. (Clean Code Kap. 3)
- Vier Argumente sind die harte Grenze. Bei fünf Argumenten: Halte an und führe ein Request/Konfigurationsobjekt ein (Record, Struct, DTO oder Äquivalent). Verwende niemals boolesche Flag-Argumente – teile stattdessen in zwei Funktionen auf.
- Keine Ausgabeparameter. Eine Funktion gibt entweder einen Wert zurück (Abfrage) oder hat einen Seiteneffekt (Befehl). Niemals beides. Befehlsnamen verwenden Verben; Abfragenamen verwenden Nomen oder Getter-artige Namen. (CQS)
Kommentare und Struktur
- Kommentare erklären Warum, niemals Was. Lösche jeden Kommentar, der die darunterliegende Zeile paraphrasiert. Lösche Schritt-für-Schritt-Gerüstkommentare. Lösche auskommentierten Code – Versionskontrolle existiert. (Clean Code Kap. 4)
- Passe dich dem vorhandenen Stil der Datei an. Lies die Datei, die du bearbeitest, und mindestens eine benachbarte Datei, bevor du schreibst. Spiegele die Groß-/Kleinschreibung, Importsortierung, Fehlerbehandlung, Protokollierung und die Wahl von HTTP/DB-Client wider. Führe kein zweites Muster ein.
SOLID
- Ein Akteur pro Modul. Eine Klasse sollte gegenüber einer Interessengruppe (Buchhaltung, Authentifizierung, Berichterstattung) rechenschaftspflichtig sein. Wenn zwei unabhängige Subsysteme auf dieselbe Klasse zugreifen, teile sie auf. (SRP, Uncle Bob 2014)
- Erweiterung durch neuen Code, nicht durch Bearbeitungen. Wenn das Hinzufügen einer neuen Variante einen weiteren Typ-Tag-Zweig in einer vorhandenen Funktion erfordert, refaktoriere zuerst zu einem Registry-, Strategie- oder polymorphischen Dispatch. (OCP)
- Keine Unterklasse verweigert den Vertrag der Elternklasse. Überschreibe niemals eine Methode, um „nicht implementiert“ oder „nicht unterstützte Operation“ zu signalisieren. Stärke niemals Vorbedingungen oder schwäche Nachbedingungen in einer Überschreibung. Wenn du das tun musst, ist die Vererbung falsch. (LSP)
- Abstraktionen leben beim Client, nicht bei der Implementierung. Wenn du ein Interface, Protokoll oder einen abstrakten Vertrag einführst, platziere es im Paket, das es konsumiert, nicht neben der konkreten Klasse. (DIP)
DRY, KISS, YAGNI
- Lösche dupliziertes Wissen, nicht duplizierten Text. Zwei Funktionen, die gleich aussehen, aber unterschiedliche Regeln kodieren, sind kein DRY-Verstoß. Eine Regel, die in Code + Dokumentation + Schema ausgedrückt ist, ist es. (Pragmatic Programmer, „DRY“)
- Die falsche Abstraktion ist schlimmer als Duplizierung. Wenn eine Abstraktion Ansammlungen von Zweigen für die Sonderfälle jedes Aufrufers hat, füge sie wieder inline in die Aufrufer ein, lösche dann die toten Zweige, bevor du erneut abstrahierst. (Sandi Metz, „The Wrong Abstraction“)
- Komplexitätsobergrenze: zyklomatisch ≤10, Verschachtelungstiefe ≤5. Refaktoriere vor dem Überschreiten. (McCabe 1976)
- Kein spekulatives Irgendetwas. Kein optionaler Parameter, Konfigurations-Flag, Umgebungsvariable, Feature-Toggle, Interface, Factory oder Basisklasse ohne einen aktuellen Aufrufer. Wenn du dabei bist,
enable_*,use_*_v2oder*_modehinzuzufügen, lösche es und liefere das konkrete Verhalten aus. (Fowler, „Yagni“)
KI-spezifische Schutzmaßnahmen – der Abschnitt mit der größten Hebelwirkung
- Verschlucke niemals Fehler mit breiten Catch-all-Handlern. Fange nur den spezifischen Fehlertyp, von dem du dich erholen kannst. Wenn du dich nicht erholen kannst, lasse den Fehler propagieren. Die Rückgabe von null/kein/leerem Erfolg aus einem Catch-Handler ist verboten, es sei denn, der Funktionsvertrag dokumentiert dieses Verhalten. (Karpathy)
- Schütze die Grenze; vertraue dem Vertrag. An einer Vertrauensgrenze – externe Eingabe, Anfrage/API-Nutzlasten, deserialisierte oder prozessübergreifende Daten, alles aus einer nicht vertrauenswürdigen Quelle – validiere, auch wenn der glückliche Pfad in Ordnung aussieht. Innerhalb der Grenze füge keine Null-Prüfungen oder Laufzeit-Typprüfungen für Werte hinzu, deren deklarierter Typ oder Aufrufervertrag diesen Fall bereits ausschließt. Der Test für eine Schutzmaßnahme ist nicht „könnte dies theoretisch falsch sein“, sondern „kann nicht vertrauenswürdige Daten hierher gelangen“. (arXiv 2409.19182)
- Überprüfe jeden Import und externen Aufruf. Bevor du eine Methode einer Bibliothek aufrufst, bestätige, dass sie in der installierten Version existiert (lies das Paket, überprüfe die Lock-Datei oder importiere und inspiziere). Generiere keinen Code basierend auf dem, wie die API „aussehen sollte“. (USENIX Security '25)
- Keine hartcodierten „Erfolgs“-Rückgaben oder Mock-Fixtures im Produktionscode. Gib niemals
{"status": "ok", ...}oder vorgefertigte Daten aus einer Funktion zurück, deren Spezifikation besagt, dass sie echte Arbeit leistet. Wenn du es nicht implementieren kannst, scheitere explizit mit dem sprachspezifischen Mechanismus für „nicht implementiert“ oder „nicht unterstützte Operation“ und sage dies. Deaktiviere, überspringe oder schwäche niemals einen Test, um ihn zu bestehen. (Fowler, Claude Code Issue #6984) - Leite neu ab, kopiere nicht von Ähnlichem. Wenn du versucht bist, eine Funktion zu kopieren und zu ändern, halte inne. Leite aus der Spezifikation neu ab. Off-by-One- und falsche Null-Semantik-Fehler treten fast immer durch Kopieren-von-Ähnlichem auf. (arXiv 2411.01414)
- Zähle Grenzfälle auf, bevor du sie schreibst. Für jeden Bereich, Off-by-One, null/leer/eins/viele, gerade/ungerade oder Unicode/Byte-Grenze, schreibe die Fallliste zuerst in einem Kommentar. Decke jeden Fall im Code ab, bevor du fortfährst.
- Entferne toten Code vor der Auslieferung. Führe einen Linter- oder grep-Durchlauf für unbenutzte Importe, unbenutzte Symbole, unerreichbare Zweige und „nur für den Fall“-Exporte durch. Entferne sie. Eine Funktion, die heute nichts aufruft, darf nicht für „irgendwann“ bestehen bleiben.
- Lies vor dem Schreiben. Bevor du in einem unbekannten Repository schreibst, lies die Datei, die du bearbeiten wirst, eine benachbarte Datei und alle Projektregeln-Dateien (CLAUDE.md, AGENTS.md, Abschnitt „Konventionen“ in der README). Verwende die vorhandenen Hilfsfunktionen, Fehlertypen und Protokollierungsmechanismen des Projekts.
- Keine neue Abhängigkeit für das, was ein paar Zeilen abdecken. Bevor du ein Paket hinzufügst, überprüfe die Standardbibliothek, die bereits installierten Abhängigkeiten und ob ein paar Zeilen lokalen Codes die Arbeit erledigen. Eine neue Abhängigkeit ist dauerhafte Wartung und Lieferkettenoberfläche; füge nur eine hinzu, wenn sie echte Komplexität besitzt, die du nicht neu implementieren solltest (Kryptografie, Parsing, Zeitzonen – illustrativ, nicht erschöpfend), niemals um zehn Zeilen zu sparen. Siehe references/dry-kiss-yagni.md.
Das Minimum – niemals der Einfachheit halber streichen
Regel 16 vertraut dem Vertrag innerhalb der Grenze; die folgenden Punkte bleiben bestehen, selbst während du Spekulationen (14), defensive Prüfungen (16) und toten Code (21) entfernst. Das Entfernen eines dieser Punkte ist eine Verhaltensänderung, keine Bereinigung – behalte es oder markiere es und frage nach.
- Validierung und Bereinigung an jeder Vertrauensgrenze – externe Eingabe, Anfrage/API-Nutzlasten, deserialisierte oder prozessübergreifende Daten.
- Fehlerbehandlung, die Datenverlust verhindert.
- Sicherheitsmaßnahmen – Autorisierung, Ausgabe-Escaping, parametrisierte Abfragen, Umgang mit Geheimnissen.
- Verhalten, das der Benutzer explizit angefordert hat. Beiläufig erwähnt ≠ angefordert, aber lasse nicht fallen, was angefordert wurde.
Refactoring-Disziplin
- Bewahre beobachtbares Verhalten beim Refactoring. Wenn der Benutzer dich bittet, vorhandenen Code zu bereinigen, zu vereinfachen oder umzugestalten, ändere nicht den Vertrag – gleiche Eingaben erzeugen gleiche Ausgaben, gleiche Ausnahmen werden geworfen, gleiche Seiteneffekte, gleiche Ordnungsgarantien. Wenn du während des Refactorings einen Fehler entdeckst, markiere ihn separat und frage, bevor du ihn änderst. Refactoring ist definiert als „eine Änderung der internen Struktur von Software, um sie leichter verständlich und billiger zu ändern, ohne ihr beobachtbares Verhalten zu ändern“ (Fowler, Refactoring). Fehlerbehebungen und Refactorings sind zwei Operationen – bündele sie niemals in einer einzigen Änderung.
Selbstprüfung vor der Auslieferung
Bevor du dem Benutzer das Ergebnis zeigst, committest oder zusammenführst, führe diese abschließende Prüfung durch:
- Überprüfe die Liste der immer angewendeten Imperative Punkt für Punkt anhand des Diffs oder der neu erstellten/geänderten Dateien. Stelle sicher, dass kein Verstoß gegen die Regeln 1–24 vorliegt.
- Überprüfe die KI-spezifischen Schutzmaßnahmen (Regeln 15–23) besonders sorgfältig. Wenn du hartcodierte Erfolgsrückgaben, breite Catch-Handler, kopierte Funktionen, fehlende Grenzvalidierung oder nicht überprüfte Importe siehst – behebe sie sofort.
- Führe die projekt eigenen Linter, Formatierer und Test-Suiten aus (wenn verfügbar), um mechanische Probleme zu erkennen.
- Bestätige, dass der Code die vom Benutzer explizit angeforderten Verhaltensweisen implementiert und keine unbeabsichtigten Änderungen enthält.
- Dokumentiere alle gefundenen und behobenen Probleme in einer kurzen Zusammenfassung für den Benutzer (optional, aber empfohlen für Transparenz).
Wenn die Selbstprüfung einen Verstoß aufdeckt, behebe ihn, bevor du fortfährst. Wiederhole die Prüfung, bis alle Punkte bestanden sind.