Visualiser et réduire systématiquement la dette technique avec Claude Code

« On veut refactoriser mais on n’a jamais le temps. » « Par où commencer ? » La dette technique s’accumule en silence. Avec Claude Code, vous pouvez révéler, prioriser et rembourser la dette systématiquement pour une fraction du coût habituel.

1. Détecter les code smells dans tout le code

Commencez par un balayage complet.

claude -p "
Scanne src/ pour détecter les code smells. Vérifie :

- Fonctions de plus de 50 lignes
- Imbrication profonde (4+ niveaux)
- Logique dupliquée
- God Classes (responsabilités surchargées)
- Nombres magiques
- Exports inutilisés
- Utilisation du type any
- Commentaires TODO / FIXME

Sortie dans docs/tech-debt/smells.md sous la forme :
| Fichier | Ligne | Smell | Sévérité(1-5) | Correction suggérée |
"

Un inventaire classé par sévérité devient votre point de départ.

2. Mesurer la dette de dépendances

Les bibliothèques obsolètes et les vulnérabilités sont aussi de la dette.

claude -p "
Analyse package.json ainsi que npm audit et npm outdated :

1. Bibliothèques nécessitant des mises à jour majeures
2. Vulnérabilités connues
3. Paquets non maintenus
4. Doublons (par exemple moment + date-fns mélangés)

Sortie dans docs/tech-debt/dependencies.md avec version actuelle, dernière version, breaking changes, priorité de mise à jour — sous forme de tableau.
"

3. Prioriser avec les ICE Scores

On ne peut pas tout corriger. Classez par Impact × Confidence × Ease.

claude -p "
En utilisant docs/tech-debt/smells.md et dependencies.md, note chaque élément :

- Impact (I) : effet sur le business / la vélocité de dev (1-10)
- Confidence (C) : certitude de l'impact (1-10)
- Ease (E) : effort pour corriger (1-10)

Trie par Score = I × C × E décroissant.
Sortie dans docs/tech-debt/backlog.md.
Inclus les jours-homme estimés pour le top 10.
"

Les scores numériques rendent l’argument clair pour les product managers.

4. Générer automatiquement de petites PR de remboursement

Découpez le remboursement en PR révisables.

claude -p "
Pour l'élément n°1 dans docs/tech-debt/backlog.md :

1. Crée la branche : refactor/tech-debt-001
2. Corrige uniquement ce problème (pas de changement de comportement)
3. Vérifie que les tests existants passent
4. Découpe en plusieurs commits si c'est trop gros
5. Exécute gh pr create

Le corps de la PR doit inclure :
- Ce qu'était la dette
- Pourquoi la rembourser maintenant
- Score ICE
- Rayon d'impact sur le reste du code
"

5. Identifier les hot spots non testés

Les zones à faible couverture deviennent de la dette future.

npm test -- --coverage --coverageReporters=json

claude -p "
Analyse coverage/coverage-summary.json :

- Fichiers avec moins de 50 % de couverture
- Parmi eux, ceux qui contiennent de la logique métier
- Priorité pour ajouter des tests

Sortie dans docs/tech-debt/coverage-gaps.md.
Propose des cas de test pour les 3 premiers fichiers.
"

Combinez avec la Génération automatique de tests pour un impact cumulé.

6. Rendre le remboursement visible avec des rapports hebdomadaires

Sans visibilité, les équipes abandonnent.

claude -p "
Fais un rapport sur le remboursement de dette technique de la semaine écoulée :

- Éléments résolus (vérifie docs/tech-debt/backlog.md)
- Nouvelle dette découverte
- Éléments de sévérité 5 encore ouverts
- Progression des mises à jour de dépendances

Sortie dans docs/tech-debt/weekly-report-$(date +%Y-%m-%d).md.
Calibré pour une lecture de 5 minutes en standup.
"

Planifiez en cron le lundi matin pour institutionnaliser le remboursement.

7. Arrêter toute nouvelle dette à la porte

Le remboursement est vain si l’entrée continue. Codifiez les règles dans CLAUDE.md.

## Règles pour prévenir toute nouvelle dette technique

### Interdit
- Nouvelles valeurs typées any (utiliser // @ts-expect-error avec raison si inévitable)
- Logique de contournement sans TODO
- Logique métier sans tests

### Checklist PR
- [ ] Couverture du nouveau code ≥ 80 %
- [ ] Zéro erreur ESLint
- [ ] Ajouts de dépendances justifiés dans la PR

### Exceptions acceptables
- Hotfixes (avec ticket de suivi)
- Code POC (doit être réécrit avant production)

Imposez via des pre-commit hooks. Voir le Guide des Hooks.

Anti-patterns

❌ Une PR géante de refactor

Les PR qui « corrigent tout » sont ineffaçables. Un smell = une PR.

❌ Mélanger des changements de comportement

Ne combinez jamais travail de feature et refactoring dans la même PR. La charge de revue double.

❌ Refactorer sans tests

Si la couverture est faible, écrivez d’abord les tests, puis refactorez. Pas de filet = nouveaux bugs.

Conclusion

• Utilisez Claude Code pour révéler smells, dette de dépendances et lacunes de couverture
• Quantifiez la priorité avec le scoring ICE
• Découpez le remboursement en petites PR
• Publiez des rapports hebdomadaires de progression
• Bloquez la nouvelle dette via des règles dans CLAUDE.md
• Un smell = une PR

La dette technique n’est pas quelque chose à corriger « un jour ». C’est quelque chose à rembourser un peu chaque semaine. Claude Code effondre le coût de cette cadence.

Associé : Automatisation du refactoring / Modernisation du code legacy / Checklist de code review

Documentation officielle : Anthropic Claude Code