Anpassung
Optionale persönliche Einstellungen: ${AGENT_SKILLS_CONFIG:-~/.config/agent-skills}/CodeQuality/PREFERENCES.md.
Falls diese Datei existiert, lies sie ein und wende sie an; ansonsten arbeite mit den Standardeinstellungen der Skill. Persönliche Einstellungen nur: Alles, was eine Tatsache über ein Repository oder Produkt ist, gehört in dieses Repository (in seine .claude/workflow-profile.sh oder Tool-Konfigurationen), niemals hierher.
Was macht CodeQualität?
Ein Loop, zwei Linsen. Der Loop ist immer: erkennen → einen Punkt auswählen → hinter Tests fixen → verifizieren → wiederholen. Die Werkzeuglinse behebt, was Scanner melden, in der Prioritätsreihenfolge, mit vorhandenen Tests als Schutz. Die Prinzipienlinse behebt, was Code schwer änderbar macht (God-Klassen, Duplikate, untestbare Kerne), ein SOLID-/Clean-Code-Prinzip nach dem anderen, und wendet nie einen Design-Schritt an, ohne ihn vorher zu zeigen. Beide Linsen lesen dasselbe Werkzeug-Manifest, schreiben in dasselbe Berichtsverzeichnis und enden mit demselben Qualitätsverbesserungsbericht.
Zwei Linsen
| Werkzeuglinse | Prinzipienlinse | |
|---|---|---|
| Treiber | Scanner-Ausgabe (summary.md) | Design-Smells gemappt auf Principles.md (smell-inventory.md, roadmap.md) |
| Arbeitseinheit | ein Fund: eine Regel an einer Datei:Zeile | ein Prinzip an einem eingegrenzten Hotspot: ein Extract, eine Klassenaufteilung, eine Abhängigkeitsinversion |
| Reihenfolge | P0 Sicherheit → P1 Korrektheit → P2 Wartbarkeit | Hebel-Hierarchie (unten), je nach Repository angepasst |
| Autonomie | fixen, dann Diff zeigen | vorschlagen → bestätigen → anwenden; nichts wird vor der Zustimmung bearbeitet |
| Sicherheitsnetz | vorhandene Tests bleiben grün | Charakterisierungstests werden zuerst geschrieben, wenn das Ziel ungetestet ist |
| Metrik | weniger Funde, Tool erneut sauber ausführen | Duplikationsgrad, zyklomatische Komplexität, Funktionslänge, Fan-In/Out, „jetzt unit-testbar“ |
| Wann verwenden | Lint/Typ/Sicherheitsschulden, CI rot, „Scanner zufriedenstellen“ | Code, der sich gegen Änderungen sträubt; strukturelle Ebene eines Remediation-Sprints |
Der Loop
SCAN → AUSWÄHLEN → SICHERHEITSNETZ → [VORSCHLAGEN → BESTÄTIGEN] → FIXEN → VERIFIZIEREN → BERICHT → WIEDERHOLEN
└─ verpflichtend im Prinzipienmodus, im Werkzeugmodus übersprungen ─┘
Workflow-Routing
| Auslöser | Workflow | Erzeugt |
|---|---|---|
| „Qualitätswerkzeuge installieren“, „Codequalität einrichten“ | Workflows/Install.md | Manifest-Werkzeuge installiert und verifiziert |
| „scannen“, „Baseline“, „Codequalität analysieren“, „Smell-Report“, „Was sollten wir zuerst fixen?“, „Refactoring-Roadmap“ | Workflows/Scan.md | summary.md (A), smell-inventory.md (B), roadmap.md (C) |
| „Codequalität verbessern“, „Lint fixen“, „Qualitätsloop“, „[Fund] fixen“ | Workflows/Loop.md im Werkzeug-Modus | Fixes, session-log.md, Bericht |
| „refaktorieren“, „SOLID anwenden“, „das hier aufräumen“, „Loop starten“ | Workflows/Loop.md im Prinzipien-Modus | Fixes, session-log.md, Bericht |
| „Dieses Repo aufräumen“ ohne Qualifikation | Scan A + B + C, dann Loop im Prinzipienmodus | alles oben Genannte |
| „Remediation-Sprint“, „Remediation-Zyklus“ | IssueFlow Remediation verwaltet Branch, PR und Merge; Scan beschreibt den Zyklus, Loop führt ihn aus | ein PR pro Zyklus |
Der Loop wählt seinen Modus selbst, wenn keiner angegeben ist: Werkzeug, wenn keine roadmap.md für das Repository existiert, Prinzipien, wenn eine existiert. Der Benutzer kann sowohl erzwingen.
Das Manifest
Tools/tools.tsv ist die einzige Liste der Werkzeuge in dieser Skill. Tabulatorgetrennt, eine Zeile pro Werkzeug und Sprache: language category priority tool install run notes, mit language in js | python | yaml, category in lint | format | types | security | deadcode | duplication | complexity | deps | coverage, priority in P0 | P1 | P2. Beide Skripte lesen es; die Workflows listen Werkzeuge nie inline. Zum Hinzufügen oder Entfernen eines Werkzeugs bearbeitest du eine Zeile.
| Skript | Liest aus dem Manifest | Macht |
|---|---|---|
Tools/install-quality-tools.sh [--dry-run] [lang ...] | install-Zellen der gewählten Sprachen | erkennt Sprachen (package.json → js; pyproject.toml, requirements.txt oder *.py → python; *.yaml/*.yml → yaml); installiert js-Werkzeuge als devDependencies mit dem Paketmanager des Repository (lockfile → npm/pnpm/bun), Python- und YAML-Werkzeuge mit uv pip install oder pip; npm:/pip:-Prefixe überschreiben den Kanal, - installiert nichts |
Tools/run-quality-baseline.sh [--dry-run] [lang ...] | run-Zellen | führt jedes Werkzeug in reports/codequality/<YYYY-MM-DD>-<HHMMSS>/ aus, ersetzt $OUT (Berichtsverzeichnis), $SRC (QUALITY_SRC_DIRS, Standard src falls vorhanden, sonst .), $PM und $NPX; ein nicht installiertes Werkzeug ist MISSING, ein abstürzendes ist FAILED, keines stoppt die Ausführung; schreibt summary.md mit Status pro Werkzeug, geparsten Issue-Anzahlen und P0/P1/P2-Summen; gibt den Berichtspfad aus |
Zeilen, deren run - ist (Coverage-Werkzeuge), werden installiert, aber nicht von der Baseline ausgeführt: Coverage wird im Loop gemessen, begrenzt auf das Ziel. Jedes Werkzeug ist kostenlos und läuft lokal; npm audit, pip-audit und checkov erreichen das Netzwerk nur für ihre Schwachstellendatenbanken.
Hebel-Hierarchie (Standardreihenfolge der Prinzipienlinse)
- Namen — Code, den du nicht lesen kannst, kannst du nicht sicher ändern. Günstig, macht alles möglich.
- DRY / Duplikate — entfernt den meisten Code bei geringstem Risiko; legt versteckte Abstraktionen frei.
- Kleine Funktionen — Long Method → Extract; eine Abstraktionsebene pro Funktion.
- SRP — Klassen und Module aufteilen, die sich aus mehr als einem Grund ändern.
- OCP / DIP — Abhängigkeiten umkehren, Schnittstellen hinzufügen; hohe Auswirkung, höheres Risiko, zuerst Sicherheitsnetz.
- ISP / LSP — Fette Schnittstellen und gebrochene Substituierbarkeit; benötigen die Schnittstellen aus Schritt 5.
Scan Teil C passt diese Reihenfolge an das tatsächliche Inventar an (Hebel = Auswirkung ÷ Risiko; siehe Principles.md Teil 3).
Nicht verhandelbar
- Ein Punkt pro Iteration. Ein Fund, oder ein Prinzip an einem eingegrenzten Ziel. Kleine, überprüfbare Diffs.
- Verhaltensbewahrend. Struktur ändert sich, Verhalten nicht. Wenn sich das Verhalten ändern muss, stoppen und markieren: Das ist ein Feature, kein Fix.
- Grün zu Grün. Tests bestehen vorher und nachher. Rot nach einer Änderung bedeutet Zurücksetzen, niemals vorwärts fixen.
- Charakterisierungstests zuerst wenn die zu bearbeitenden Zeilen ungetestet sind. Kein Netz, keine Refaktorisierung.
- Vor dem Anwenden vorschlagen bei jedem Design-Schritt (Prinzipienmodus). Der Werkzeugmodus darf direkt fixen, zeigt dann den Diff.
- P0 → P1 → P2 für Werkzeugfunde, sprachübergreifend, niemals sprachspezifisch.
- Nie einen Test oder eine Lint-Regel abschwächen, um Grün zu erreichen. Veraltete Tests werden zum neuen korrekten Verhalten verschoben; Regeln werden im Code erfüllt.
- Boy-Scout, begrenzt. Berührte Dateien sauberer hinterlassen, aber den Umfang nicht über den aktuellen Punkt hinaus ausdehnen.
- Evidenz, keine Meinung. Nenne die Regel oder das Prinzip und eine Metrik, falls vorhanden.
Ausgabeartefakte
Alle unter reports/codequality/ (git-ignoriert):
| Datei | Geschrieben von |
|---|---|
<YYYY-MM-DD>-<HHMMSS>/summary.md + rohe Werkzeugausgabe | run-quality-baseline.sh (Scan A) |
<YYYY-MM-DD>/smell-inventory.md | Scan B |
<YYYY-MM-DD>/roadmap.md | Scan C |
<YYYY-MM-DD>/session-log.md | Loop, ein Eintrag pro Iteration |
<YYYY-MM-DD>/quality-report.md | Loop, am Ende der Sitzung (unten) |
Qualitätsverbesserungsbericht (verpflichtend)
Jede Loop-Sitzung endet mit diesem Bericht, in beiden Modi. Er ist das Lieferobjekt zusammen mit der Codeänderung und der Inhalt des PRs oder Tracker-Kommentars, wenn die Arbeit über IssueFlow ausgeliefert wird.
| Abschnitt | Inhalt |
|---|---|
| Zusammenfassungstabelle | Zeilen hinzugefügt / entfernt / netto; Issues vorher → nachher pro Priorität; Dead-Code-Hotspots entfernt; Tests vorher → nachher (Anzahl, alle grün) |
| Entfernter Code | Datei, was, Zeilen, Risiko |
| Hinzugefügter oder geänderter Code | Datei, was, Zeilen, Zweck |
| Behobene Bugs | Schweregrad, Beschreibung, Ursache (nur falls aufgetreten) |
| Komplexitätsdelta | maximale und durchschnittliche zyklomatische Komplexität vorher → nachher, mit einem ASCII-Balken pro Hotspot |
| Zurückgestellt | Gesehene, aber nicht im Scope liegende Punkte, und warum |