Tech-Debt Discovery (Analyse technischer Schulden)
Analysieren Sie die Codebasis auf technische Schulden und wandeln Sie die Ergebnisse in umsetzbare GitHub-Issues um. Die Analyse ist schreibgeschützt: Ändern Sie während der Ausführung dieses Skills niemals Code.
Optionen
Diese aus der Benutzeranfrage oder den Befehlsargumenten parsen:
- Scope paths: Verzeichnisse oder Dateien zur Analyse (z. B.
src/services lib/). - --full: Das gesamte Repository scannen, mit Ausnahme von Abhängigkeits-, Build- und VCS-Verzeichnissen (
node_modules,vendor,.git,dist,build,target,tmp,log, virtuelle Umgebungen, generierter Code). - --dry-run: Ergebnisse melden, ohne Issues zu erstellen.
- --all: Das Limit von 20 Issues aufheben.
- --force: Issues auch dann erstellen, wenn ein ähnliches offenes Issue existiert.
- --yes: Den Bestätigungsdialog überspringen (nur, wenn der Benutzer es explizit angibt).
- --categories=X,Y: Nur diese Kategorien ausführen:
dead-code,duplication,architecture,deferred-work,patterns,tests.
Ausführungsmodell
Jede Kategorie wird unabhängig analysiert. Wenn Ihr Agent parallele Subagenten erzeugen kann, geben Sie jeder Kategorie einen eigenen Subagenten mit dem Umfang, dem erkannten Stack und der Checkliste der Kategorie aus references/categories.md, und lassen Sie jeden das untenstehende JSON-Format zurückgeben. Andernfalls führen Sie die Kategorien nacheinander aus, um innerhalb der Kontextlimits zu bleiben.
Eine vollständige sechs-Kategorien sequentielle Ausführung dauert bei einer mittelgroßen Codebasis etwa 15 bis 30 Minuten. Für schnellere Ergebnisse empfehlen Sie --categories oder einen engeren Umfang.
Schritt 1: Umfang bestimmen
- Wenn Pfade angegeben wurden, diese verwenden.
- Wenn
--fullangegeben wurde, das Repository mit den obigen Ausschlüssen scannen. - Andernfalls die vorhandenen Haupt-Quell- und Testverzeichnisse automatisch erkennen (häufige:
src/,app/,lib/,pkg/,internal/,cmd/,test/,tests/,spec/). Anzeigen:Automatisch erkannter Umfang: [Verzeichnisse]. Etwa X Dateien. Fortfahren? (verwenden Sie --full für einen vollständigen Scan)
Zählen Sie die Quellcodedateien im Umfang mit den Erweiterungen, die das Repository tatsächlich verwendet (z. B. git ls-files -- <scope> | grep -E '\.(rb|py|ts|tsx|js|go|java|kt|rs|php|cs)$' | wc -l).
- Über 1.000 Dateien: Warnen, dass die Ausführung lange dauern wird, und
--categoriesvorschlagen. - Über 5.000 Dateien: Dringend empfehlen, jeweils nur eine Kategorie auszuführen, und eine grobe Zeit pro Kategorie angeben.
Schritt 2: Voranalyseschritte
Sofern nicht --dry-run, die GitHub CLI überprüfen:
gh auth status
Wenn dies fehlschlägt, gh_available=false setzen und sagen: „gh CLI nicht gefunden oder nicht authentifiziert. Ergebnisse werden gemeldet, ohne Issues zu erstellen. Führen Sie gh auth login aus, um die Issue-Erstellung zu aktivieren.“
Wenn verfügbar, das für später Benötigte abrufen:
gh issue list --state open --limit 200 --json number,title,body,labels
gh label list --limit 200 --json name,description
Die Issue-Liste für die Duplikatserkennung und die Label-Liste für die Beschriftung aufbewahren.
Schritt 3: Stack erkennen
Die Sprache, das Framework und den Testrunner aus dem Repository erkennen, anstatt einen anzunehmen. Typische Indikatoren:
| Indikator | Stack |
|---|---|
Gemfile mit rails, oder config/application.rb | Ruby on Rails |
manage.py oder django in requirements / pyproject.toml | Django |
pyproject.toml / requirements.txt mit fastapi oder flask | Python Web |
package.json mit next, react, vue, svelte, express, nestjs | JS/TS Framework |
go.mod | Go |
Cargo.toml | Rust |
pom.xml / build.gradle* | JVM (Spring, falls vorhanden) |
composer.json mit laravel/framework | Laravel |
*.csproj | .NET |
Auch das Test-Framework erkennen (RSpec, Minitest, pytest, unittest, Jest, Vitest, Mocha, Go testing, JUnit, PHPUnit usw.) und die Testverzeichnisse.
Lesen Sie die eigenen Konventionen des Projekts, bevor Sie etwas beurteilen: README, CONTRIBUTING, Agenten-Anweisungsdateien (AGENTS.md, CLAUDE.md, GEMINI.md), Linter-Konfigurationen und alle Architektur-Dokumente. Ein Muster, das das Projekt bewusst gewählt hat, ist keine Schuld.
Melden: Stack erkannt: [Sprache / Framework / Testrunner]. Analyse-Regeln entsprechend angepasst.
Schritt 4: Kategorienanalysen durchführen
Für jede aktivierte Kategorie (standardmäßig alle sechs):
Analysiere [Kategorie]... (X von N)ankündigen.- Die Checkliste für diese Kategorie in
references/categories.mdanwenden, angepasst an den erkannten Stack. - Ergebnisse im untenstehenden JSON-Format sammeln.
[Kategorie] abgeschlossen: X Ergebnissemelden.
Wenn eine Kategorie deutlich länger läuft als die anderen (ca. 5 Minuten aktive Analyse), stoppen Sie sie und markieren Sie sie im Bericht als Unvollständig (abgebrochen), anstatt die Ausführung zu blockieren.
Ergebnisformat
Jede Kategorie gibt Folgendes zurück:
{
"category": "Dead Code",
"findings": [
{
"type": "Unused Import",
"severity": "P3",
"location": "src/utils/format.ts:5",
"line_number": 5,
"description": "Import 'date-fns' wird in dieser Datei nie verwendet",
"evidence": "import { format } from 'date-fns'",
"remediation": "Entfernen Sie den unbenutzten Import",
"complexity": "simple"
}
]
}
Bei Duplikaten jeden Ort in location setzen, getrennt durch , . Bei Architektur-Ergebnissen die Metriken in description setzen (z. B. „567 Zeilen, 23 öffentliche Methoden“).
Schweregrad-Referenz
| Muster | Schweregrad | Kategorie |
|---|---|---|
| Tests, die Sicherheitsprobleme verbergen | P0 | Testqualität |
| Fehlende Autorisierungsprüfung beim Ressourcenzugriff | P1 | Musterverstöße |
| God-Klassen (>500 Zeilen oder >20 öffentliche Methoden) | P1 | Architektur |
| Zirkuläre Abhängigkeiten | P1 | Architektur |
| Unerreichbarer Code | P1 | Toter Code |
| Reine Mock-Tests (der Test mockt das, was er testet) | P1 | Testqualität |
| Stubbing des Subjekts und dann Assertion darauf | P1 | Testqualität |
| Tautologische Tests | P1 | Testqualität |
| Leere Testkörper | P1 | Testqualität |
| Übermäßiges Mocking (>50% des Tests ist Setup) | P1 | Testqualität |
| Jede Instanz einer Klasse stuben | P1 | Testqualität |
| Über Tests hinweg geteilter veränderlicher Zustand | P1 | Testqualität |
| Lange Funktionen (>50 Zeilen) | P2 | Architektur |
| Hohe Kopplung (>10 Projekt-Imports) | P2 | Architektur |
| Exakte oder nahe Duplikate | P2 | Duplikation |
| Veraltungsmeldungen | P2 | Aufgeschobene Arbeit |
| Temporäre oder Workaround-Markierungen | P2 | Aufgeschobene Arbeit |
| Framework-Antipattern | P2 | Musterverstöße |
| Implementierungsgekoppelte Tests | P2 | Testqualität |
| Tests, die nur auf „kein Fehler“ prüfen | P2 | Testqualität |
| Nicht referenzierte Funktionen, tote Zweige, verwaiste Dateien | P2 | Toter Code |
| Tiefe Verschachtelung (>4 Ebenen) | P3 | Architektur |
| Unbenutzte Imports | P3 | Toter Code |
| TODO / FIXME-Kommentare | P3 | Aufgeschobene Arbeit |
| Auskommentierter Code | P3 | Aufgeschobene Arbeit |
| Konventionsverstöße | P3 | Musterverstöße |
| Brüchige Test-Assertions | P3 | Testqualität |
| TODOs, die auf ein Ticket verweisen | P4 | Aufgeschobene Arbeit |
Komplexitätsleitfaden
- simple: unter 10 Zeilen, eine Datei, offensichtliche Behebung (einen unbenutzten Import entfernen).
- moderate: 10 bis 50 Zeilen, 2 oder 3 Dateien, einfaches Refactoring (eine Funktion extrahieren).
- complex: über 50 Zeilen, erfordert eine architektonische Entscheidung oder betrifft die gesamte Codebasis (eine God-Klasse aufteilen). In der Behebung anmerken, dass wahrscheinlich ein Design oder Vorschlag vor der Implementierung erforderlich ist.
Schritt 5: Sammeln und deduplizieren
- Ergebnisse nach Kategorie + Datei + Zeile gruppieren (innerhalb von 10 Zeilen). In jeder Gruppe das Ergebnis mit den detailliertesten Belegen und dem höchsten Schweregrad in der Gruppe behalten.
- Kategorieübergreifend: Wenn toter Code und Architektur dieselbe Klasse markieren, das Architektur-Ergebnis behalten. Wenn mehrere Kategorien dieselbe Zeile markieren, zusammenführen und den höchsten Schweregrad behalten.
- Sortieren: P0 zuerst, dann P1 bis P4.
Schritt 6: Auf bestehende Issues prüfen
Diesen Schritt nur überspringen, wenn --force gesetzt ist. Für jedes Ergebnis nach einem offenen Issue suchen, das:
- denselben Dateipfad in Titel oder Text erwähnt, UND
- die gleiche Art von Problem oder eine Zeile innerhalb von 20 Zeilen dieses Ergebnisses abdeckt.
Bevorzugen Sie Issues mit dem Titel [TechDebt] oder einem Tech-Debt-Label, aber gleichen Sie jedes offene Issue ab, das eindeutig dasselbe Problem verfolgt. Bei einem Treffer das Ergebnis als bereits verfolgt als #N markieren und kein Issue dafür erstellen. Unterschiedliche Problemtypen in derselben Datei sind separate Ergebnisse.
Schritt 7: Bestätigen, dann Issues erstellen
Erstellung überspringen, wenn --dry-run oder gh_available=false; direkt zum Bericht gehen.
Limit: maximal 20 Issues, sofern nicht --all. Slots in Reihenfolge füllen: alle P0 und P1, dann P2 (vorzugsweise über Dateien verteilt, nicht viele Issues in einer Datei), dann P3, dann P4. Mit --all und mehr als 50 Issues warnen, dass es eine Weile dauern wird.
Labels: Nur Labels verwenden, die bereits in gh label list existieren. Die nächste Übereinstimmung für Tech-Debt wählen (z. B. tech-debt, technical-debt, debt, refactor, chore) und, falls das Repository sie hat, ein Prioritätslabel passend zum Schweregrad und ein Typ-Label (z. B. testing). Niemals Labels ohne Nachfrage erstellen. Wenn kein passendes Label existiert, dies sagen und entweder ohne Label einreichen oder den Benutzer fragen, ob tech-debt erstellt werden soll.
Bestätigung (erforderlich): Vor dem Erstellen die vollständige Liste anzeigen und auf die Antwort des Benutzers warten. Niemals Issues ohne diese Bestätigung erstellen, es sei denn, der Benutzer hat --yes übergeben.
Es werden X Issues erstellt (Labels: tech-debt, P2):
1. [P1] [TechDebt] Architektur: OrderService aufteilen (612 Zeilen, 27 öffentliche Methoden)
2. [P1] [TechDebt] Testqualität: Mock-only-Test in payment_test.py:45 beheben
3. [P2] [TechDebt] Duplikation: Adressvalidierung extrahieren (user.ts:40, account.ts:88)
...
Bereits verfolgt (übersprungen): 3. Über dem Limit (nicht eingereicht): 12.
Fortfahren? Sie können auch Einträge nach Nummer entfernen oder Labels ändern.
Alle vom Benutzer vorgenommenen Änderungen anwenden, dann jedes Issue erstellen. Jeder Text muss für sich allein stehen und für jemanden lesbar sein, der diesen Bericht nicht gesehen hat:
gh issue create \
--title "[TechDebt] <Kategorie>: <Kurzbeschreibung>" \
--label "<vorhandenes-Label>" \
--body "$(cat <<'EOF'
**Kategorie:** <Kategorie>
**Schweregrad:** P<N>
**Ort:** <Datei:Zeile>
## Problem
<Beschreibung>
## Beleg
```
<Beleg>
```
## Vorgeschlagene Behebung
<Behebung>
**Komplexität:** <simple|moderate|complex>
## Abnahmekriterien
- <überprüfbare Bedingung, dass die Schuld behoben ist>
- Die vollständige Testsuite des Projekts läuft erfolgreich
EOF
)"
Titelbeispiele:
[TechDebt] Toter Code: Unbenutzte Imports in format.ts:5-12 entfernen[TechDebt] Architektur: OrdersController aufteilen (567 Zeilen, 23 Aktionen)[TechDebt] Testqualität: Mock-only-Test in payment_service_test.go:45 beheben
Wenn ein gh issue create-Aufruf fehlschlägt, den Fehler und den Befehl protokollieren, mit den restlichen fortfahren und am Ende melden: X Issues erstellt, Y fehlgeschlagen.
Wenn das Repository Arbeit auf einem GitHub-Projektboard verfolgt (der Abschnitt Issue tracking in den Agentenanweisungen sagt Mode: project, oder es gibt keinen solchen Abschnitt und gh repo view --json projectsV2 zeigt ein verknüpftes Board), anbieten, das place-issues-Skill auf die neuen Issues auszuführen.
Schritt 8: Zusammenfassungsbericht
=== Tech-Debt Discovery Bericht ===
Umfang: [analysierte Pfade]
Analysierte Dateien: [Anzahl]
Stack: [Sprache / Framework / Testrunner]
Dauer: [benötigte Zeit]
## Zusammenfassung
- Ergebnisse insgesamt: X | Erstellte Issues: Y | Bereits verfolgt: Z | Über Limit: W
- Nach Schweregrad: P0: A, P1: B, P2: C, P3: D, P4: E
## Ergebnisse nach Kategorie
### Toter Code (X)
- [ ] #N: Unbenutzte Imports in format.ts:5-12 entfernen (P3)
### Duplikation (X)
- [ ] #N: Adressvalidierung extrahieren (user.ts:40, account.ts:88) (P2)
### Architektur (X)
- [ ] #N: OrderService aufteilen (612 Zeilen, 27 öffentliche Methoden) (P1)
### Aufgeschobene Arbeit (X)
- [ ] #N: TODO in billing.py:123 auflösen (P3)
### Musterverstöße (X)
- [ ] #N: N+1-Abfragerisiko in OrdersController#index beheben (P2)
### Testqualität (X)
- [ ] #N: Mock-only-Test in payment_test.py:45 beheben (P1)
## Bereits verfolgt
- billing.py:100 TODO → #N
## Zusätzliche Ergebnisse (über dem Limit, nicht eingereicht)
[Liste]
Führen Sie mit --all aus, um die verbleibenden X Ergebnisse einzureichen.
## Übersprungen (falsch positiv oder beabsichtigt)
- tests/fixtures/** : Fixtures ausgeschlossen
- TODO(#42) in conftest.py : hat ein verknüpftes Ticket (P4)
## Analysestatus
- Toter Code: Abgeschlossen
- ...
- Testqualität: Unvollständig (abgebrochen)
## Fehler
[alle fehlgeschlagenen gh-Befehle]
Bei --dry-run Issues-Nummern durch [würde erstellen] ersetzen.
Prinzipien
- Schreibgeschützt. Keine Codeänderungen während der Analyse.
- Konservativ. Bei Unsicherheit überspringen, anstatt ein falsch Positives zu melden. Ein verrauschter Bericht wird ignoriert.
- Das Projekt respektieren. Framework-Konventionen (Callbacks, Decorators, Dependency Injection, konventionsbasiertes Routing) und im Repository dokumentierte Entscheidungen sind keine Schuld.
- Belege zuerst. Jedes Ergebnis zitiert eine Datei, eine Zeile und den Code, der es beweist.
- Strukturierte Ausgabe. Kategorieanalysen geben JSON zurück, sodass Zusammenführen und Deduplizieren zuverlässig sind.
- Benutzer bestätigt vor dem Einreichen. Die Liste wird immer zuerst angezeigt.