Comment automatiser le refactoring avec un agent de codage.

Guide pratique pour transformer vos codebases legacy en code propre. Techniques, prompts, Plan Mode et workflows pour déléguer intelligemment la dette technique à un agent — sans jamais perdre le contrôle.

01Introduction : le refactoring, cas d'usage idéal pour l'IA agentique

Le refactoring est la tâche où un agent de codage excelle le plus. Pourquoi ? Parce qu'elle combine exactement ce que l'agent sait faire de mieux : lire et comprendre un codebase entier, planifier une séquence de modifications cohérentes, exécuter des changements multi-fichiers, et vérifier que rien n'est cassé.

Un développeur backend a rapporté cette expérience révélatrice : face à un fichier service de 600 lignes accumulé sur deux ans, mêlant logique métier, accès données et formatage API, l'agent a produit un plan de décomposition en modules séparés, l'a exécuté, et a vérifié les tests — le tout en une session.

Ce guide vous montre comment reproduire ce résultat sur vos propres codebases.

02Principe fondamental : décrire le résultat, pas les étapes

La clé du refactoring avec un agent est de penser en termes de résultats plutôt que d'instructions pas-à-pas.

Ouvre le fichier OrderService.ts,
va à la ligne 42, extrais la
fonction calculateTotal, crée un
nouveau fichier, importe-la…

Refactore OrderService.ts pour
améliorer la maintenabilité :
— Extrais la logique métier
— Ajoute les types manquants
— Écris les tests unitaires
— Suis les conventions du CLAUDE.md

03Étape 1 — Préparer le contexte

Avant tout refactoring, assurez-vous que votre CLAUDE.md décrit les conventions du projet : nommage des fichiers, structure des dossiers, patterns architecturaux utilisés, règles TypeScript / ESLint en vigueur.

# CLAUDE.md — section architecture

## Patterns
- Architecture hexagonale : domain/ ports/ adapters/
- Un fichier = une responsabilité
- Max 200 lignes par fichier
- Injection de dépendances via constructeur

# Ce contexte est crucial : sans lui, l'agent refactore
# selon ses propres conventions, pas les vôtres.

04Étape 2 — Utiliser le Plan Mode

Pour tout refactoring impliquant plus de 3 fichiers, commencez par demander explicitement un plan avant toute modification.

You › /plan Ce service de 450 lignes gère à la fois
      l'authentification, la validation des permissions,
      et la gestion des sessions. Décompose-le en
      modules cohérents.

L'agent va alors :

1. Analyser le fichier et identifier les responsabilités mélangées
2. Proposer un découpage en modules avec les noms de fichiers
3. Lister les fichiers impactés par les changements d'imports
4. Estimer les risques de régression

Validez le plan avant de laisser l'agent exécuter. C'est votre point de contrôle stratégique.

05Étape 3 — Exécution contrôlée

Une fois le plan validé, l'agent exécute les changements. Mais contrôlez la progression :

Refactoring en petites sessions

Ne refactorez pas 20 fichiers en une seule session. Procédez module par module, en validant les tests à chaque étape. Un refactoring qui échoue après 50 modifications est un cauchemar à débugger.

Vérification intermédiaire

Demandez à l'agent de lancer les tests après chaque lot de modifications. Si un test échoue, corrigez avant de continuer.

Commits atomiques

Demandez des commits à chaque étape logique, pas à la fin. Vous pourrez toujours revenir en arrière.

06Scénarios de refactoring courants

Décompose src/api/users.ts (800 lignes) en modules séparés :
- Extraction des handlers dans users.controller.ts
- Extraction de la logique métier dans users.service.ts
- Extraction des requêtes DB dans users.repository.ts
- Mise à jour de tous les imports dans le projet
- Vérification que tous les tests existants passent

Migre tous les composants React de classe dans src/components/
vers des composants fonctionnels avec hooks.
Conserve le comportement identique.
Convertis les lifecycles (componentDidMount, etc.) en useEffect.
Lance les tests après chaque composant converti.

Ajoute des types TypeScript stricts à src/utils/.
Remplace tous les 'any' par des types appropriés.
Crée les interfaces nécessaires dans src/types/.
Assure-toi que tsc compile sans erreur.

Uniformise la gestion d'erreurs dans tous les handlers API :
- Crée une classe AppError avec code et message
- Remplace les try/catch ad-hoc par un middleware centralisé
- Ajoute le logging structuré sur chaque erreur
- Conserve les codes HTTP existants

07Bonnes pratiques avancées

Refactoring parallèle avec Git worktrees

Pour les gros projets, lancez plusieurs instances de l'agent sur des branches séparées. Chacune s'occupe d'un module indépendant. Les worktrees Git rendent cela transparent.

Refactoring avec filet de sécurité

Avant tout refactoring important, demandez à l'agent de générer d'abord une suite de tests de caractérisation. Ces tests capturent le comportement actuel — même les bugs — et servent de filet de sécurité pendant le refactoring.

Avant de refactorer, génère des tests de caractérisation
pour OrderService.ts : des tests qui capturent le
comportement actuel exact, y compris les cas limites.

Audit post-refactoring

Après le refactoring, demandez un audit :

Fais un audit du refactoring qu'on vient de faire :
- Y a-t-il des imports morts ?
- Des fonctions devenues orphelines ?
- Des incohérences de nommage ?
- La couverture de tests a-t-elle changé ?

08Les pièges à éviter

09Conclusion : le refactoring n'est plus une corvée

Avec un agent de codage, le refactoring passe de « tâche qu'on reporte indéfiniment » à « opération de 30 minutes ». La dette technique n'est plus une fatalité quand on a un agent capable de la traiter méthodiquement.

La clé : structurez votre CLAUDE.md, utilisez le Plan Mode, procédez par itérations, et vérifiez à chaque étape.