yonathan-boop/Claude

antislop-code

Anti Slop: Regeln für KI-Coding-Agenten. Skill für Code-Kommentare

Teil des antislop-Systems. Zusammen mit antislop.md (dem Kern) lesen. Dieses Skill filtert Kommentare heraus, die generisch KI-artig wirken (dekorativ, Offensichtliches wiederholend, steif, laut), während es Kommentare bewahrt, die echte Informationen enthalten. Es referenziert Kernregeln per Nummer und dupliziert oder nummeriert sie nie neu. Lade es, wenn die Aufgabe Code-Kommentare schreibt oder bearbeitet.

Wie man dieses Skill verwendet

• Lade es zusammen mit antislop.md, wenn die Aufgabe Code-Kommentare betrifft. Der Kern enthält den Mechanismus (den Zwecktest, die drei Stufen, das Delivery Gate); dieses Skill enthält die kommentarspezifische Tiefe.
• Jeder Eintrag hat die gleiche Form: Sag (das Muster), Warum (warum es wie Slop wirkt), Behebung (was stattdessen zu tun ist), mit der zugehörigen Kernregel als R-XX.
• Bereichs-Schutzschranke: Dieses Skill ändert nur Kommentare. Ändere niemals ausführbaren Code, Bezeichner, Importe, Formatierung, Einrückung, Leerzeichen, Kontrollfluss oder Logik. Im Zweifelsfall den Code unberührt lassen.
• Das Delivery Gate im Kern bleibt das Tor. Die "Checkliste für Code-Kommentare" am Ende dieser Datei ist die kommentarspezifische Ergänzung, die parallel dazu ausgeführt wird.

Kommentare, die nichts hinzufügen

Dekorative Trennzeichen

• Sag: Banner-Kommentare aus wiederholten Zeichen, GROSSBUCHSTABEN-Labels oder Kästchenzeichnungen um einen Abschnittsnamen: // ======================= um Authentication, // -------- WORKFLOW -------- oder ein /* ---- ROUTES ---- */-Header.
• Warum: Die Dekoration ist die Nachricht. Ein Label, eingewickelt in = oder -, signalisiert "KI hat das gemacht", ohne Informationen hinzuzufügen, und GROSSBUCHSTABEN wirken wie Schreien.
• Behebung: Ersetze es durch eine einzelne, schlichte Zeile oder entferne es ganz, wenn das Label nichts hinzufügt (R-31).

Offensichtliches wiederholen

• Sag: Ein Kommentar, der wiederholt, was die nächste Zeile oder Deklaration bereits zeigt, wie // Initialisiere die Variable über let count = 0, // Benutzerklasse über class User {}, // Validiere Benutzer über function validateUser() oder const userAge = 25; // Benutzeralter ist 25.
• Warum: Es verdoppelt die Leselast, ohne etwas hinzuzufügen. Der Code sagt es bereits; der Kommentar wiederholt es nur.
• Behebung: Entferne es und lasse die Codezeile in Ruhe.

Arbeitsablauf-Narration

• Sag: Kommentare, die den Ablauf Schritt für Schritt erzählen, wie // Schritt 1: Eingabe validieren, // Schritt 2: Anfrage verarbeiten, // Schritt 3: Antwort zurückgeben oder // Zuerst..., // Als nächstes..., // Schließlich....
• Warum: Der Kontrollfluss ist im Code selbst sichtbar. Ihn zu nummerieren wirkt wie eine Checkliste, nicht wie eine Erklärung.
• Behebung: Entferne es. Wenn der Ablauf wirklich schwer zu verfolgen ist, ist das ein Strukturproblem, kein fehlendes Kommentarproblem.

Leere Labels

• Sag: Generische Labels ohne dahinterstehende Information: // Hauptlogik, // Kernlogik, // Geschäftslogik, // Hilfsfunktion, // Einstiegspunkt, // Fehlerbehandlung oder // Hinweis: Das ist wichtig. / // Wichtig: Bitte lesen.
• Warum: Das Label benennt eine Kategorie, keine Tatsache. "Hauptlogik" sagt dem Leser nichts, was er nicht aus dem Code schließen könnte.
• Behebung: Entferne es, es sei denn, das Label trägt spezifische Informationen. "Hinweis: Wiederholungen erfolgen nur bei 5xx" verdient seinen Platz; "Hinweis: das ist wichtig" nicht.

Vage Platzhalter

• Sag: Kommentare, die zukünftige Arbeit versprechen, ohne zu sagen was: // TODO: Verbessern, // Zukünftige Verbesserungen, // Weitere Optimierungen können hier hinzugefügt werden, // Füge mehr Validierung hinzu.
• Warum: Ein vages TODO ist Rauschen. Es benennt ein Gefühl (das könnte besser sein) anstelle einer Aufgabe (was und warum).
• Behebung: Entferne es. Behalte ein TODO nur, wenn es eine spezifische Aufgabe mit genügend Kontext zum Handeln nennt.

Signaturecho

• Sag: Dokumentation, die nur die Signatur wiederholt, wie ein JSDoc-Block, der @param price Der Preis. und @returns Gesamtpreis. für eine Funktion wiederholt, deren Name und Parameter bereits alles sagen.
• Warum: Docs, die die Signatur echoen, erhöhen die Länge, nicht das Verständnis. Der Leser erfährt nichts Neues.
• Behebung: Vereinfache oder entferne das Echo. Behalte Dokumentation, die Geschäftsregeln, Randfälle, Annahmen, Algorithmen, Einschränkungen, Nebenwirkungen, API-Verhalten oder Sicherheitsimplikationen erklärt. Entferne niemals echte Dokumentation.

Dekorative Emojis

• Sag: Emojis, die als Dekoration in Kommentaren verwendet werden, wie // ✅ Validierung oder // 🚀 Leistung.
• Warum: Emojis sind visuelles Rauschen im Code, und die spezifische Menge (✅, 🚀, 🔒) ist der KI-Standardwortschatz.
• Behebung: Ersetze es durch einfaches Deutsch oder entferne es, wenn das Label nichts hinzufügt.

End-Markierungen

• Sag: Kommentare, die nur das Ende eines Blocks markieren, wie } // Ende wenn, # Ende der Funktion oder // Ende von processOrder.
• Warum: Die schließende Klammer beendet den Block bereits. Die Markierung existiert aus Gewohnheit, nicht aus Notwendigkeit.
• Behebung: Entferne es. In dem seltenen Fall, dass eine End-Markierung in einer langen Datei wirklich hilft, behalte sie nur dort, wo sie Verwirrung verhindert, nicht als Gewohnheit.

Wie es lesen sollte

Der über-erklärte Kommentar

• Sag: Ein Kommentar, der sich über mehrere Zeilen erstreckt, Gründe, Kontext und Geschichte um eine Tatsache stapelt, die in eine Zeile passt: ein vierzeiliger Block, der erklärt, dass ein Stub auf PATH liegt, welches Release den Workaround eingeführt hat und was vorher kaputt war. Jeder Satz ist wahr. Die Länge ist das Merkmal.
• Warum: Eine Person hinterlässt eine Notiz, ein Generator schreibt einen Fall. Eine einzeilige Tatsache zu einem Absatz aufzublähen, eine "weil X, also Y, und daher Z"-Kette zu bauen oder die Issue-Nummer und die Version, die es behoben hat, zu zitieren, ist die gleiche Ausschmückung wie jedes andere KI-Muster, und sie begraben die eine Zeile, die zählt, unter den Zeilen, die es nicht tun.
• Behebung: Schneide es auf die Einschränkung allein herunter: eine Zeile, höchstens zwei, niemals drei. Behalte die Plattformfalle, den stillen Fehler, die Protokollregel, die Kosten für die Leistung. Wirf die Issue-Nummer, die Versionshistorie und die Argumentationskette weg.

Zeilenweise Erzählung

• Sag: Ein Kommentar zu jeder trivialen Anweisung, der jede Zeile erzählt, wie sie geschrieben ist: // Zähler initialisieren, dann // Elemente durchlaufen, dann // Element holen, dann // Erhöhen, dann // Ergebnis zurückgeben.
• Warum: Wenn jede Zeile kommentiert ist, ist keiner der Kommentare wichtig. Der Leser muss jeden prüfen, um den zu finden, der Bedeutung trägt.
• Behebung: Schreibe einen prägnanten Kommentar pro logischem Block anstatt einen pro Zeile. Wenn der Block keinen Kommentar benötigt, schreibe keinen.

Steife oder laute Formulierung

• Sag: Kommentare, die formell, lang oder schreiend klingen: "Diese Funktion ist dafür verantwortlich zu validieren, ob die bereitgestellten Anmeldeinformationen gültig sind, bevor mit dem Authentifizierungsprozess fortgefahren wird", oder // HAUPTLOGIK in Großbuchstaben.
• Warum: Formelle und laute Formulierungen wirken generiert, nicht wie ein Ingenieur, der eine Notiz für die nächste Person hinterlässt.
• Behebung: Schreibe kurze, in Satzfällen gehaltene Zeilen in einer natürlichen Entwicklerstimme: // Anmeldeinformationen validieren, bevor ein Token ausgestellt wird. Gute Kommentare erklären warum, nicht was, und sie bleiben kurz.

Kein Verbot (diese behalten)

Entferne niemals Kommentare, die erklären:

• Geschäftslogik und Absicht
• Architekturentscheidungen
• Sicherheitsüberlegungen
• Leistungskompromisse
• Nebenläufigkeitsverhalten
• Protokolldetails
• API-Verträge
• Workarounds
• Randfälle und Annahmen
• Lizenzierung und rechtliche Hinweise

Beispiel, das bleiben muss:

// Stripe kann Webhook-Zustellungen bis zu drei Tage lang wiederholen.
// Ignoriere doppelte Ereignisse mithilfe der Ereignis-ID.

Ein Kommentar verdient seinen Platz, wenn er etwas erklärt, das der Code nicht bereits zeigt: den Grund, die Einschränkung, das nicht offensichtliche Verhalten.

Einen Platz verdienen sagt, was bleiben darf, niemals, wie lang es laufen darf. Eine Workaround-Notiz ist eine Zeile über den Workaround, kein Absatz darüber. Das obige Beispiel hat zwei Zeilen, weil zwei Fakten real sind, nicht weil zwei Zeilen ein Ziel sind. Diese Liste ist der häufigste Grund, warum ein Kommentar eine Überprüfung überlebt, die er nicht sollte: Der Inhalt ist legitim wertvoll, also bleibt die Länge ungeprüft. Wert ist nicht Länge.

Checkliste für Code-Kommentare

Führe diese zusammen mit dem Kern-Delivery Gate aus, wenn die Aufgabe Kommentare betrifft. Alle Antworten müssen ja sein:

• Fügt jeder Kommentar Informationen hinzu, die der Code nicht bereits zeigt? (R-31)
• Vermeiden die Kommentare dekorative Trennzeichen, GROSSBUCHSTABEN-Banner und Kästchen-Header?
• Vermeiden die Kommentare das Wiederholen der offensichtlichen Zeile, Deklaration oder Signatur?
• Vermeiden die Kommentare eine schrittweise Arbeitsablauf-Narration?
• Vermeiden die Kommentare leere Labels und vage TODOs, die keine Aufgabe nennen?
• Vermeiden die Kommentare dekorative Emojis und End-Markierungen?
• Ist die Kommentardichte ein pro logischem Block, nicht ein pro Zeile?
• Ist jeder Kommentar eine Zeile oder zwei nur, wenn die zweite eine neue Tatsache trägt?
• Lesen sich die verbleibenden Kommentare kurz, natürlich und in Satzfällen?
• Wird die Bereichs-Schutzschranke eingehalten: nur Kommentare geändert, der Code unberührt?