Use Cases (Aktualisiert: 1.6.2026)

Technische Schulden mit Claude Code sicher abbauen: Team-Guide

Technische Schulden erfassen, mit ICE/RICE priorisieren und per kleinen PRs mit Claude Code abbauen.

Technische Schulden mit Claude Code sicher abbauen: Team-Guide

Jedes Team sagt, dass es technische Schulden abbauen will. Dann kommt der Sprint, neue Features gewinnen, any verbreitet sich, Abhängigkeiten altern, CI schlägt gelegentlich fehl und TODOs werden zu dauerhafter Architektur.

Claude Code macht automatisches Refactoring nicht risikofrei. Der praktische Wert liegt woanders: Es hilft, Schulden zu inventarisieren, Belege anzuhängen, Prioritäten zu setzen und die Rückzahlung in kleine reviewbare PRs zu zerlegen. So wird aus einem riskanten Aufräumprojekt ein wiederholbarer Teamprozess.

Dieser Guide behandelt Code-Smell-Inventar, Dependency Debt, flaky tests (instabile Tests), duplizierte Logik, gefährliche TODOs, ICE/RICE-Priorisierung, kleine PRs und Governance. Als offizielle Grundlage dienen Claude Code Common workflows, Memory und Settings. Passend dazu: Testing Strategies, CLAUDE.md Best Practices und der Approval and Sandbox Guide.

Schulden als Rückzahlungszyklus behandeln

Der typische Fehler ist die große Aufräumaktion. Der Branch wird groß, Reviews werden unübersichtlich, und niemand kann sicher sagen, ob sich Verhalten geändert hat.

Nutze stattdessen einen kurzen Zyklus.

flowchart LR
  A["Inventar"] --> B["Belege sammeln"]
  B --> C["ICE/RICE bewerten"]
  C --> D["Kleine PRs schneiden"]
  D --> E["Tests und Review"]
  E --> F["Schuldenregister aktualisieren"]
  F --> A

Inventar heißt nicht Bauchgefühl. Sammle Dateipfade, Zeilen, CI-Logs, veraltete Pakete, any, große Dateien, duplizierte Logik sowie TODO/FIXME-Kommentare.

AnsatzGeeignet fürRisikoRolle von Claude Code
Großes RefactoringMigrationen mit klarer GrenzeDiff wird unreviewbarRecherche und Migrationsplan
Kleine Debt-PRsLaufende WartungWirkung wirkt unsichtbarRegister, Scoring, Checklist
Dependency SprintSecurity-Fixes und EOLBreaking Changes werden übersehenChangelog-Zusammenfassung und Testplan
Flaky-Test-CleanupCI wird nicht mehr vertrautRetries verstecken echte BugsFehlerklassifikation und Reproduktion

Use Case 1: Code Smells inventarisieren

Ein Code Smell ist nicht automatisch ein Bug. Er zeigt an, dass künftige Änderungen schwerer werden: riesige Funktionen, Klassen mit zu vielen Verantwortlichkeiten, duplizierte Validierung, Magic Numbers oder Typ-Ausnahmen.

Bitte Claude Code zuerst um Inspektion, nicht um Änderungen.

claude -p "
Untersuche src/ und tests/ auf technische Schulden. Ändere noch keine Dateien.

Suche nach:
- Funktionen über 80 Zeilen
- Dateien über 300 Zeilen
- Verschachtelung tiefer als 4 Ebenen
- Duplizierter Validierung, Datumslogik oder Permission Checks
- TypeScript any, as any und @ts-ignore
- TODO / FIXME / HACK Kommentare
- Branches ohne Tests oder Tests, die nur Rendering prüfen

Gib eine Markdown-Tabelle aus, die ich in docs/tech-debt/register.md einfügen kann.
Spalten: ID, File, Line, Debt type, Evidence, Risk, Suggested first PR, Confidence.
"

Die Formulierung “Ändere noch keine Dateien” ist wichtig. Sonst schleichen sich spekulative Änderungen ein. Claude Code soll untersuchen und klassifizieren; das Team entscheidet, welche Schuld zuerst dran ist.

Use Case 2: Dependency Debt finden

Veraltete Bibliotheken, unmaintained Packages, Sicherheitslücken und doppelte Libraries sind ebenfalls Schulden. Die Zahl der npm audit-Meldungen ist kein gutes Priorisierungssignal: laute Warnungen können ein zentrales EOL-Paket verdecken.

claude -p "
Klassifiziere Dependency Debt anhand von package.json, lockfile, npm outdated und npm audit.

Kategorien:
1. Security Fix erforderlich
2. Major Update mit wahrscheinlichen Breaking Changes
3. Unmaintained oder Ersatz empfohlen
4. Doppelte Libraries für denselben Zweck
5. Sicher aufzuschieben

Nenne pro Eintrag Impact-Bereich, zuerst zu lesendes Changelog, benötigte Tests und den kleinsten sicheren PR.
Trenne automatisierbare Änderungen von Änderungen mit zwingender menschlicher Review.
"

Eine Dependency ist nicht sicher, nur weil Tests einmal durchlaufen. Datumslogik, Auth, Krypto, Routing, Build Tools und Test Runner brauchen isolierte Branches und klare Rollback-Notizen.

Use Case 3: Flaky Tests und duplizierte Logik abbauen

Flaky Tests zerstören Vertrauen. Sobald das Team glaubt “CI noch einmal starten, dann passt es”, ist die Test-Suite kein Sicherheitsnetz mehr.

claude -p "
Lies die letzten 20 CI-Fehlerlogs und klassifiziere wahrscheinliche flaky tests.

Klassifiziere nach:
- Abhängigkeit von Uhrzeit, Zeitzone oder Zufallsdaten
- Netzwerk- oder externe API-Abhängigkeit
- Geteiltem Zustand zwischen Tests
- Instabilem async waiting
- Wahrscheinlichem Produktbug, der nicht als flaky gelten darf

Gib pro Kandidat Reproduktionsbefehl, minimalen Fix und hinzuzufügende Assertion aus.
"

Bei duplizierter Logik sollte der erste PR langweilig sein. Wenn Permission Checks in vier Dateien kopiert sind, extrahiere zuerst einen reinen Helper und sichere das Verhalten mit Tests. Ersetze Call Sites danach einzeln.

Kopierbarer Scanner

Claude Code hilft bei Analyse, aber mechanische Marker sollten scriptbar sein. Speichere dies als scripts/debt-scan.mjs und führe node scripts/debt-scan.mjs src aus.

import fs from "node:fs";
import path from "node:path";

const root = process.argv[2] || "src";
const maxLines = Number(process.env.MAX_LINES || 300);
const extensions = new Set([".js", ".jsx", ".ts", ".tsx", ".mjs", ".cjs"]);
const findings = [];

function walk(dir) {
  if (!fs.existsSync(dir)) return;

  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
    const fullPath = path.join(dir, entry.name);

    if (entry.isDirectory()) {
      if ([".git", "node_modules", "dist", "build", ".next", "coverage"].includes(entry.name)) continue;
      walk(fullPath);
      continue;
    }

    if (entry.isFile() && extensions.has(path.extname(entry.name))) {
      scanFile(fullPath);
    }
  }
}

function add(file, line, type, severity, detail) {
  findings.push({ file, line, type, severity, detail });
}

function scanFile(file) {
  const text = fs.readFileSync(file, "utf8");
  const lines = text.split(/\r?\n/);

  if (lines.length > maxLines) {
    add(file, 1, "large-file", 3, `${lines.length} lines`);
  }

  lines.forEach((line, index) => {
    const lineNumber = index + 1;

    if (/\b(FIXME|TODO|HACK)\b/i.test(line)) {
      add(file, lineNumber, "unsafe-comment", /FIXME|HACK/i.test(line) ? 4 : 3, line.trim());
    }

    if (/\.(ts|tsx)$/.test(file) && /(:\s*any\b|as\s+any\b|<any>)/.test(line)) {
      add(file, lineNumber, "typescript-any", 4, line.trim());
    }
  });
}

walk(root);

console.log("| file | line | type | severity | detail |");
console.log("| --- | ---: | --- | ---: | --- |");
for (const item of findings.sort((a, b) => b.severity - a.severity || a.file.localeCompare(b.file))) {
  const detail = item.detail.replaceAll("|", "\\|");
  console.log(`| ${item.file} | ${item.line} | ${item.type} | ${item.severity} | ${detail} |`);
}

if (findings.length === 0) {
  console.error("No obvious debt markers found.");
}

Der Scanner versteht keine Architektur und findet nicht jede Duplikation. Er liefert aber eine stabile wöchentliche Basis für TODO, FIXME, any und große Dateien.

Vorlage für das Schuldenregister

Sammle Findings zuerst in einem Register, bevor du Issues erstellst.

# Technical Debt Register

| ID | Area | Evidence | User or team impact | ICE | RICE | Owner | Next PR | Status |
| --- | --- | --- | --- | ---: | ---: | --- | --- | --- |
| TD-001 | Auth permissions | src/auth/guard.ts duplicates role checks in 4 places | New role changes take 2 days and often miss one path | 420 | 1680 | Backend | Extract pure canAccess() with tests | Ready |
| TD-002 | Dependencies | vite is 2 major versions behind | Security patches and plugin updates are blocked | 280 | 900 | Platform | Upgrade in isolated branch and run build/test | Investigating |

## Scoring note

- ICE = Impact x Confidence x Ease
- RICE = Reach x Impact x Confidence / Effort
- Keep evidence links concrete: file path, line, CI run, or user-facing incident.

ICE ist schnell. RICE ist besser, wenn Reach und Aufwand explizit werden müssen. Beides sind Gesprächswerkzeuge, keine Wahrheit.

Prompt für einen sicheren Refactor-Plan

Wenn ein Eintrag gewählt ist, bitte zuerst um einen Plan.

claude -p "
Erstelle einen sicheren Rückzahlungsplan für TD-001. Ändere noch keine Dateien.

Scope:
- src/auth/guard.ts
- src/auth/roles.ts
- tests/auth/guard.test.ts

Constraints:
- Externes API-Verhalten nicht ändern
- Bestehende Tests zuerst prüfen
- Bei fehlender Verhaltensabdeckung zuerst characterization tests ergänzen
- Ziel: PR unter 300 geänderten Zeilen
- Risiken, Rollback und Review-Fokus angeben

Output:
1. Zusammenfassung des aktuellen Verhaltens
2. Explizite Non-Goals
3. Diff-Plan für den ersten PR
4. Auszuführende Testbefehle
5. Review-Anfrage für den PR
"

Explizite Non-Goals verhindern Scope Creep. Claude Code hilft sonst leicht über die PR-Grenze hinaus.

Refactor-PR-Checklist

## Refactor PR checklist

- [ ] This PR changes structure, not product behavior.
- [ ] Existing behavior is covered by tests before the refactor.
- [ ] New helper names describe domain behavior, not implementation detail.
- [ ] Public API, response shape, permissions, and logging are unchanged or explicitly documented.
- [ ] The diff is small enough to review in one sitting.
- [ ] Rollback is simple: revert this PR without reverting unrelated work.
- [ ] The debt register is updated with status and follow-up PRs.

Nutze die Checklist im PR-Text, den Claude Code erstellt. Sie macht aus “nur Refactoring” prüfbare Evidenz.

Konkrete Fallen

Automatisierung überschätzen Bestehende Typen reichen nicht. Authorization, Billing, Datum, Async-Verhalten und Migrationen brauchen Charakterisierungstests und menschliche Review.

Alle TODOs löschen Manche TODOs blockieren Releases, andere sind nur Notizen. Priorisiere remove before release, bypass auth, temporary token und FIXME.

Dependency Updates bündeln Zehn Major Updates in einem PR machen Fehleranalyse teuer. Trenne Build Tools, UI, Auth und Test Runner.

Scores politisch nutzen ICE/RICE braucht Belege: Dateipfade, CI-Runs, Incidents und Aufwandannahmen.

Teamgedächtnis vergessen Regeln wie “Permission-Code braucht Approval” oder “Refactor-PRs unter 300 Zeilen” gehören in CLAUDE.md oder Settings. Memory und Settings sparen wiederholte Prompts.

Team-Governance

Praktisch ist ein 30-minütiges Debt Review pro Woche:

  1. Scanner und Claude-Code-Inventar lesen.
  2. ICE/RICE nur für die Top 10 aktualisieren.
  3. Einen Rückzahlungs-PR für den nächsten Sprint wählen.
  4. Flaky Tests und Security Dependencies höher priorisieren.
  5. Im Register notieren, was nach dem PR einfacher wurde.

ClaudeCodeLab hilft, daraus ein funktionierendes System zu machen: Register, PR-Checklists, Settings und Startregeln für CLAUDE.md. Für Anpassung an Repository und Review-Kultur siehe Claude Code Training, Templates und Beratung.

Fazit

Technische Schulden mit Claude Code sicher abzubauen heißt nicht “refactore alles”. Es heißt: Belege sammeln, bewerten und eine kleine Schuld pro PR zurückzahlen. Code Smells, Dependency Debt, flaky tests, duplizierte Logik und gefährliche TODOs passen in denselben Zyklus.

Beim praktischen Test dieses Workflows in Masas kleinen Projekten war der größte Gewinn die Trennung zwischen dringender Schuld und bloß zu dokumentierender Schuld. any-Bereinigung und alte TODOs in kleine PRs zu schneiden senkte Risiko, ohne Reviews stark zu belasten. Major Updates von Dependencies waren schwerer als erwartet; sicherer war es, zuerst Tests und Release Notes zu ergänzen und Claude Code erst danach Änderungen entwerfen zu lassen.

#claude-code #tech-debt #refactoring #code-quality
Kostenlos

Kostenloses PDF: Claude-Code-Cheatsheet

E-Mail eintragen und eine Seite mit Befehlen, Review-Gewohnheiten und sicheren Workflows herunterladen.

Wir schützen Ihre Daten und senden keinen Spam.

Masa

Über den Autor

Masa

Engineer für praktische Claude-Code-Workflows und Team-Einführung.

Ähnliche Artikel