CommunityCodierung & Entwicklunggithub.com

Tech-Debt (Technische Schulden)

Analysiert eine Codebasis auf technische Schulden (toter Code, Duplikate, Architekturprobleme, aufgeschobene Arbeit, Framework-Antipattern, minderwertige Tests), bewertet die Funde nach Schweregrad und erstellt nach Bestätigung durch den Benutzer GitHub-Issues. Verwenden Sie dies, wenn der Benutzer ein Tech-Debt-Audit, eine Codequalitätsprüfung, eine Liste von Refactoring-Kandidaten oder die Umwandlung von Schulden in nachverfolgte Issues wünscht. Unterstützt einen eingegrenzten Pfad, einen vollständigen Scan, ausgewählte Kategorien und einen Probelauf.

Was ist Tech-Debt (Technische Schulden)?

Dieses Skill führt eine gründliche, lesende Analyse einer Codebasis durch, um technische Schulden in sechs Kategorien zu identifizieren: toter Code, Duplikate, Architektur, aufgeschobene Arbeit, Framework-Antipattern und Testqualität. Es priorisiert die Funde nach Schweregrad (P0 bis P4) und formatiert sie als strukturiertes JSON. Nach der Deduplizierung und einem Abgleich mit bestehenden GitHub-Issues (unter Verwendung der gh CLI) erstellt es neue Issues – jedoch nur nach einer expliziten Benutzerbestätigung. Das Skill kann parallel mit Subagenten arbeiten, erkennt den Technologie-Stack des Projekts (z. B. Rails, Django, Go) und passt seine Analyse an die Projektkonventionen an, die in READMEs oder AGENTS.md-Dateien dokumentiert sind. Es priorisiert Genauigkeit vor Vollständigkeit und überspringt unsichere Funde, um Rauschen zu vermeiden. Es ist für Claude Code, Codex und andere KI-Agenten konzipiert, die GitHub-Workflows integrieren.

Funktioniert mit✓Claude Code~Codex CLI~Cursor✓Gemini CLI
npx skills add https://github.com/JAdshead/toolkit/tree/HEAD/skills/tech-debt

Installed? Explore more Codierung & Entwicklung skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

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

  1. Wenn Pfade angegeben wurden, diese verwenden.
  2. Wenn --full angegeben wurde, das Repository mit den obigen Ausschlüssen scannen.
  3. 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 --categories vorschlagen.
  • Ü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:

IndikatorStack
Gemfile mit rails, oder config/application.rbRuby on Rails
manage.py oder django in requirements / pyproject.tomlDjango
pyproject.toml / requirements.txt mit fastapi oder flaskPython Web
package.json mit next, react, vue, svelte, express, nestjsJS/TS Framework
go.modGo
Cargo.tomlRust
pom.xml / build.gradle*JVM (Spring, falls vorhanden)
composer.json mit laravel/frameworkLaravel
*.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):

  1. Analysiere [Kategorie]... (X von N) ankündigen.
  2. Die Checkliste für diese Kategorie in references/categories.md anwenden, angepasst an den erkannten Stack.
  3. Ergebnisse im untenstehenden JSON-Format sammeln.
  4. [Kategorie] abgeschlossen: X Ergebnisse melden.

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

MusterSchweregradKategorie
Tests, die Sicherheitsprobleme verbergenP0Testqualität
Fehlende Autorisierungsprüfung beim RessourcenzugriffP1Musterverstöße
God-Klassen (>500 Zeilen oder >20 öffentliche Methoden)P1Architektur
Zirkuläre AbhängigkeitenP1Architektur
Unerreichbarer CodeP1Toter Code
Reine Mock-Tests (der Test mockt das, was er testet)P1Testqualität
Stubbing des Subjekts und dann Assertion daraufP1Testqualität
Tautologische TestsP1Testqualität
Leere TestkörperP1Testqualität
Übermäßiges Mocking (>50% des Tests ist Setup)P1Testqualität
Jede Instanz einer Klasse stubenP1Testqualität
Über Tests hinweg geteilter veränderlicher ZustandP1Testqualität
Lange Funktionen (>50 Zeilen)P2Architektur
Hohe Kopplung (>10 Projekt-Imports)P2Architektur
Exakte oder nahe DuplikateP2Duplikation
VeraltungsmeldungenP2Aufgeschobene Arbeit
Temporäre oder Workaround-MarkierungenP2Aufgeschobene Arbeit
Framework-AntipatternP2Musterverstöße
Implementierungsgekoppelte TestsP2Testqualität
Tests, die nur auf „kein Fehler“ prüfenP2Testqualität
Nicht referenzierte Funktionen, tote Zweige, verwaiste DateienP2Toter Code
Tiefe Verschachtelung (>4 Ebenen)P3Architektur
Unbenutzte ImportsP3Toter Code
TODO / FIXME-KommentareP3Aufgeschobene Arbeit
Auskommentierter CodeP3Aufgeschobene Arbeit
KonventionsverstößeP3Musterverstöße
Brüchige Test-AssertionsP3Testqualität
TODOs, die auf ein Ticket verweisenP4Aufgeschobene 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

  1. 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.
  2. 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.
  3. 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

  1. Schreibgeschützt. Keine Codeänderungen während der Analyse.
  2. Konservativ. Bei Unsicherheit überspringen, anstatt ein falsch Positives zu melden. Ein verrauschter Bericht wird ignoriert.
  3. Das Projekt respektieren. Framework-Konventionen (Callbacks, Decorators, Dependency Injection, konventionsbasiertes Routing) und im Repository dokumentierte Entscheidungen sind keine Schuld.
  4. Belege zuerst. Jedes Ergebnis zitiert eine Datei, eine Zeile und den Code, der es beweist.
  5. Strukturierte Ausgabe. Kategorieanalysen geben JSON zurück, sodass Zusammenführen und Deduplizieren zuverlässig sind.
  6. Benutzer bestätigt vor dem Einreichen. Die Liste wird immer zuerst angezeigt.

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

Verwandte Skills