Tech Debt Ledger
Macht technische Schulden aus Git-Daten belegbar – und in Stakeholder-Sprache verhandelbar.
Das Problem
Entwickler sehen technische Schulden, können sie aber nicht in Budget übersetzen. Product Owner müssen sie priorisieren, können sie aber nicht selbst erkennen. Beide reden über dasselbe und meinen Verschiedenes.
Installation
Der Skill ist eine SKILL.md mit Referenztexten und abhängigkeitsfreien Node-Scripts – nichts davon ist an einen Anbieter gebunden. Wähle deinen Agenten:
Schritt 1
git clone https://github.com/larsdecker/agents-skillsSchritt 2
node agents-skills/install.mjs --agent cursor --skill tech-debt-ledger --target .Statt cursor auch copilot, windsurf, cline, gemini oder agents (für Codex, Zed, Amp, opencode). node install.mjs --list zeigt alle. Der Installer legt die Dateien unter .agents/skills/ ab und schreibt den Einstiegspunkt dorthin, wo dein Agent ihn erwartet.
Getestet mit: Claude Code, Cursor, GitHub Copilot, Codex, Windsurf, Cline, Gemini CLI, Zed. Ein hier nicht genannter Agent funktioniert ebenfalls – Skill-Verzeichnis ablegen und in der Anweisungsdatei des Agenten darauf verweisen.
Was dabei herauskommt
- TECH-DEBT.md mit maximal 10 Einträgen, fortgeschrieben über mehrere Durchläufe
- Pro Eintrag: Messsignal, Konsequenz, kleinster wirksamer Schritt
- Optionaler Einseiter für Management
Was er nicht tut
- Keine Aufwandsschätzung in Personentagen – das kann nur das Team
- Keine statische Codeanalyse – dafür gibt es ESLint, Sonar, tsc
- Keine Sicherheitsprüfung – ein Hotspot ist keine Schwachstelle
Warum ein Skill und nicht ein Prompt
Weil die entscheidende Information nicht im Code steht, sondern in der Historie. Ein Modell, das eine Datei liest, kann sagen, dass sie unübersichtlich ist. Es kann nicht sagen, ob das jemanden etwas kostet.
Der Kern des Skills ist eine einfache Unterscheidung mit großen Folgen: Schuld kostet erst dann, wenn sie berührt wird. Eine 2.000-Zeilen-Datei, die seit zwei Jahren unverändert läuft, kostet nichts – egal wie sie aussieht. Eine 800-Zeilen-Datei, die wöchentlich geändert wird, zahlt den Aufschlag bei jeder einzelnen Anforderung erneut.
Genau diese Kombination misst der Skill: Änderungshäufigkeit mal Umfang, normalisiert auf das Maximum im Zeitfenster. Dazu vier weitere Signale, die eine Datei allein nicht hergibt.
Was gemessen wird
Hotspots — Churn × Größe. Die Sortierhilfe, nicht die Priorität.
Änderungskopplung — Dateien, die regelmäßig gemeinsam geändert werden, obwohl sie in getrennten Modulen liegen. Der beste verfügbare Hinweis auf fehlende Abstraktion, und der Befund, den keine Metrik über einzelne Dateien liefern kann.
Wissensrisiko — hoher Churn bei einem einzigen Autor. In Ein-Personen-Repos wird das unterdrückt, weil es dort keine Erkenntnis ist, sondern eine Eigenschaft des Projekts.
Testlücken — Hotspots ohne zugeordnete Testdatei. Fehlt Testinfrastruktur ganz, wird daraus ein struktureller Eintrag statt einer Liste von 15 Dateien „ohne Tests".
Toter Code — unberührt und unreferenziert. Mit Filter für Konventions-Einstiegspunkte: page.tsx, route.ts, *.config.js und Ähnliches tauchen nie als Import auf und sind trotzdem nicht verwaist.
Die drei Regeln, die den Unterschied machen
Ein Tech-Debt-Bericht verliert seine Wirkung in dem Moment, in dem der Leser eine erfundene Zahl entdeckt. Deshalb sind drei Regeln fest im Skill verankert:
- Jeder Eintrag braucht ein Messsignal. „Der Code ist unübersichtlich" ist kein Eintrag.
- Keine erfundenen Zahlen. Keine Personentage, keine Kostenschätzungen, keine Prozentwerte für Verlangsamung. Stattdessen ordinale Bewertung und beobachtbare Aussagen.
- Befund und Vermutung getrennt. Ob ein Hotspot geschäftskritisch ist, weiß der Scan nicht. Solche Stellen werden als Annahme markiert und als Rückfrage gestellt – nicht als Befund getarnt.
Beispiel: derselbe Befund, zweimal formuliert
Der Scan liefert diese Zeile:
Score Commits Autoren LOC Test Datei
70.0 7 1 746 NEIN src/app/page.tsxOhne Übersetzung – so formulieren die meisten Werkzeuge:
src/app/page.tsx: Hohe Komplexität und fehlende Testabdeckung. Verletzt das Single-Responsibility-Prinzip. Technical Debt Score: 8,4/10. Refactoring empfohlen, geschätzter Aufwand 3 Wochen.
Der Empfänger kann damit nichts entscheiden. „Verletzt SRP" ist für ihn keine Kategorie, die 3 Wochen sind erfunden, und der Score suggeriert eine Objektivität, die nicht existiert.
Mit Übersetzung – so formuliert der Skill:
Startseite: die am häufigsten geänderte und umfangreichste Datei
Messsignal: 746 Zeilen, 7 Commits in 12 Monaten, keine zugeordnete Testdatei. Gemeinsam mit
layout.tsxin 5 von 5 Fällen geändert.Konsequenz: Die Startseite ist gleichzeitig der Einstiegspunkt für Besucher und die Datei mit dem größten Änderungsumfang. Jede Anpassung erfordert, den gesamten Kontext zu überblicken; Fehler sind unmittelbar öffentlich sichtbar.
Kleinster wirksamer Schritt: Die Abschnitte der Startseite als eigene Komponenten herauslösen – beim nächsten ohnehin geplanten Change, nicht als eigenes Projekt.
Priorität: mittel. Hohe Sichtbarkeit, aber überschaubare Änderungsfrequenz.
Jede Zahl ist überprüfbar. Die Konsequenz ist erklärt statt behauptet. Der Schritt ist klein genug, dass niemand ihn ablehnen muss.
Was das Register über Zeit wertvoll macht
Der Skill schreibt TECH-DEBT.md fort statt es zu überschreiben. Einträge behalten ihre ID, erledigte wandern mit Datum in einen Abschnitt „Behoben", und bei verschlechterten Signalen werden beide Werte notiert: „34 Commits (vorherige Messung: 21)".
Diese eine Zeile ist der stärkste Inhalt des ganzen Dokuments, weil sie eine Entwicklung zeigt statt eines Zustands. Der eigentliche Wert entsteht deshalb beim zweiten Durchlauf.
