Réduire la dette technique avec Claude Code : guide sûr pour équipes

Toutes les équipes disent vouloir réduire la dette technique. Puis le sprint se remplit de nouvelles fonctionnalités, les any s’accumulent, les dépendances vieillissent, les tests échouent par intermittence et les TODO deviennent permanents.

Claude Code ne rend pas le refactoring automatique sans risque. Sa valeur est plus concrète : il aide à inventorier la dette, ajouter des preuves, prioriser et découper le remboursement en petits PR relisibles. C’est ce qui transforme une grande opération risquée en habitude d’équipe.

Ce guide couvre l’inventaire des code smells, la dette de dépendances, les flaky tests (tests instables), la logique dupliquée, les TODO dangereux, la priorisation ICE/RICE, la stratégie de petits PR et la gouvernance. Pour la base officielle, consultez Common workflows, Memory et Settings. Côté ClaudeCodeLab, lisez aussi le guide des stratégies de test, les bonnes pratiques CLAUDE.md et le guide approval/sandbox.

Transformer la dette en boucle de remboursement

Le piège classique consiste à lancer un grand chantier de nettoyage. La branche grossit, la revue devient difficile, et personne ne peut garantir que le comportement n’a pas changé.

Préférez une boucle courte.

flowchart LR
  A["Inventaire"] --> B["Preuves"]
  B --> C["Score ICE/RICE"]
  C --> D["Petits PR"]
  D --> E["Tests et revue"]
  E --> F["Registre mis à jour"]
  F --> A

L’inventaire ne doit pas être une impression. Collectez chemins de fichiers, lignes, logs CI, paquets obsolètes, usages de any, fichiers volumineux, logique dupliquée et commentaires TODO/FIXME.

Approche	Idéal pour	Risque	Rôle de Claude Code
Gros refactoring	Migration avec frontières claires	Diff trop gros pour être relu	Recherche et plan de migration
Petits PR de dette	Maintenance continue	Impact moins visible	Registre, scoring, checklist
Sprint dépendances	Correctifs sécurité et EOL	Breaking changes cachés	Résumé de changelog et plan de test
Nettoyage flaky tests	CI moins fiable	Les relances cachent les bugs	Classification et reproduction

Cas 1 : inventorier les code smells

Un code smell n’est pas toujours un bug. C’est un signal que les changements futurs seront plus difficiles : fonction géante, classe trop responsable, validation dupliquée, nombre magique, ou contournement du typage.

Commencez par demander une inspection, pas une modification.

claude -p "
Inspecte src/ et tests/ pour trouver la dette technique. Ne modifie aucun fichier pour l'instant.

Cherche:
- Fonctions de plus de 80 lignes
- Fichiers de plus de 300 lignes
- Imbrication de plus de 4 niveaux
- Validation, dates ou permissions dupliquées
- TypeScript any, as any et @ts-ignore
- Commentaires TODO / FIXME / HACK
- Branches sans tests ou tests qui vérifient seulement le rendu

Retourne une table Markdown à coller dans docs/tech-debt/register.md.
Colonnes: ID, File, Line, Debt type, Evidence, Risk, Suggested first PR, Confidence.
"

La consigne “ne modifie aucun fichier” évite les changements spéculatifs. Laissez Claude Code enquêter et classer, puis laissez l’équipe choisir la première dette à rembourser.

Cas 2 : détecter la dette de dépendances

Bibliothèques obsolètes, paquets non maintenus, vulnérabilités et doublons de librairies sont aussi de la dette. Le nombre d’alertes npm audit ne suffit pas : il peut masquer un paquet central proche de la fin de vie.

claude -p "
À partir de package.json, du lockfile, de npm outdated et de npm audit, classe la dette de dépendances.

Catégories:
1. Correctif de sécurité requis
2. Major update avec breaking changes probables
3. Non maintenu ou remplacement recommandé
4. Librairies dupliquées pour le même besoin
5. Peut être différé

Pour chaque élément, indique la zone d'impact, le changelog à lire en premier, les tests requis et le plus petit PR sûr.
Sépare les changements automatisables de ceux qui nécessitent une revue humaine.
"

Une dépendance n’est pas sûre parce que les tests passent une fois. Dates, authentification, chiffrement, routing, build tools et test runners méritent des branches isolées et des notes de rollback.

Cas 3 : rembourser flaky tests et logique dupliquée

Les flaky tests détruisent la confiance. Dès que l’équipe pense “relance CI et ça passera”, la suite de tests cesse d’être un filet de sécurité.

claude -p "
Lis les 20 derniers logs d'échec CI et classe les flaky tests probables.

Classe par:
- Dépendance à l'heure, au fuseau horaire ou à des données aléatoires
- Dépendance au réseau ou à une API externe
- État partagé qui fuit entre tests
- Attente asynchrone instable
- Bug produit probable à ne pas classer flaky

Pour chaque candidat, donne la commande de reproduction, le correctif minimal et l'assertion à ajouter.
"

Pour la logique dupliquée, le premier PR doit rester ennuyeux. Si les permissions sont copiées dans quatre fichiers, extrayez d’abord un helper pur et verrouillez le comportement avec des tests. Remplacez les appels un par un dans des PR suivants.

Script copiable de scan

Claude Code aide à analyser, mais les marqueurs mécaniques doivent être reproductibles. Enregistrez ceci dans scripts/debt-scan.mjs, puis lancez node scripts/debt-scan.mjs src.

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.");
}

Ce script ne comprend pas toute l’architecture et ne détecte pas toutes les duplications. Il fournit toutefois une base hebdomadaire stable pour TODO, FIXME, any et fichiers trop grands.

Modèle de registre de dette

Avant de créer des issues, regroupez les éléments dans un registre.

# 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 sert à trier vite. RICE est utile quand la portée et l’effort doivent être explicites. Ce ne sont pas des vérités mathématiques, mais des outils de discussion.

Prompt pour un plan sûr

Une fois la dette choisie, demandez un plan avant toute modification.

claude -p "
Crée un plan sûr pour rembourser TD-001. Ne modifie pas encore les fichiers.

Périmètre:
- src/auth/guard.ts
- src/auth/roles.ts
- tests/auth/guard.test.ts

Contraintes:
- Ne pas changer le comportement de l'API externe
- Inspecter les tests existants d'abord
- Si le comportement est peu testé, ajouter des characterization tests avant le refactor
- Viser un PR sous 300 lignes modifiées
- Inclure risques, rollback et points d'attention pour reviewers

Sortie:
1. Résumé du comportement actuel
2. Non-goals explicites
3. Plan du premier PR
4. Commandes de test
5. Message de demande de review
"

Les non-goals évitent l’élargissement du périmètre. Claude Code peut être trop serviable si les limites du PR ne sont pas écrites.

Checklist de PR de refactor

## 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.

Ajoutez-la au corps du PR rédigé par Claude Code. Elle transforme “c’est juste un refactor” en preuves vérifiables.

Pièges concrets

Trop faire confiance à l’automatisation Le typage qui passe ne suffit pas. Autorisation, paiement, dates, asynchrone et migrations nécessitent tests de caractérisation et revue humaine.

Supprimer tous les TODO Certains TODO bloquent une release, d’autres sont de simples notes. Priorisez remove before release, bypass auth, temporary token et FIXME.

Regrouper trop de mises à jour Dix major updates dans un PR rendent le diagnostic pénible. Séparez build tools, UI, auth et test runners.

Utiliser les scores comme politique ICE/RICE doit porter des preuves : chemins de fichiers, runs CI, incidents et hypothèses d’effort.

Ne pas garder la mémoire d’équipe Les règles comme “code de permissions avec approbation” ou “refactors sous 300 lignes” doivent vivre dans CLAUDE.md ou les settings. Memory et Settings réduisent les prompts répétés.

Gouvernance d’équipe

Une cadence réaliste : 30 minutes de revue de dette par semaine.

1. Lire le scanner et l’inventaire Claude Code.
2. Mettre à jour ICE/RICE pour les 10 premiers seulement.
3. Choisir un PR de remboursement pour le sprint suivant.
4. Prioriser flaky tests et dépendances de sécurité.
5. Noter dans le registre ce qui est devenu plus simple.

ClaudeCodeLab peut aider à mettre ce système en place : registre, checklists de PR, settings et règles de départ pour CLAUDE.md. Pour l’adapter à votre dépôt et à votre culture de revue, consultez Claude Code training, templates and consultation.

Résumé

La façon sûre de réduire la dette technique avec Claude Code n’est pas de demander “refactorise tout”. Il faut collecter des preuves, scorer le travail et rembourser une petite dette par PR. Code smells, dépendances, flaky tests, logique dupliquée et TODO dangereux entrent dans la même boucle.

Après avoir appliqué ce flux sur de petits projets de Masa, le principal gain a été la séparation entre dette urgente et dette à simplement enregistrer. Découper le nettoyage de any et des vieux TODO en petits PR a réduit le risque sans alourdir beaucoup la revue. Les major updates de dépendances ont été plus coûteuses que prévu ; il était donc plus sûr d’ajouter tests et notes de release avant de demander à Claude Code de rédiger les changements.