Claude Code pour refactorer un projet ancien sans casser l’existant

Refactorer un projet ancien avec Claude Code peut accélérer la lecture d’un code difficile à cartographier, mais l’assistant ne connaît pas les dépendances historiques, les usages non documentés ni les contraintes de production. La bonne approche consiste à préserver le comportement observé avant de modifier la structure : fixer un périmètre minuscule, obtenir une base de tests, faire un diff lisible et garder un retour arrière documenté.

Le piège classique est de demander « modernise ce dépôt ». Cette consigne produit facilement un changement trop large : dépendances mises à jour, fichiers renommés, formatage global et règles métier modifiées dans la même passe. Commencez plutôt par une zone isolée : une fonction trop longue, un adaptateur déprécié ou une règle de validation dupliquée.

Ce que vous allez apprendre

Vous allez construire une stratégie de refactorisation avec une aide IA, sans confondre nettoyage visuel et changement sûr. Le guide couvre l’inventaire, les tests de caractérisation, les petites extractions, la revue Git et le plan de retour arrière.

Prérequis

Vous avez besoin d’un dépôt Git, d’un environnement de test connu et de l’accord du propriétaire de la zone concernée. Lisez le README, les règles locales et les éventuelles notes d’architecture. Si le projet n’a pas de tests, prévoyez du temps pour créer des tests de caractérisation avant toute extraction importante.

Commencez par contrôler l’état existant :

git status --short
git log -n 5 --oneline

Vérification : vous savez quels changements étaient déjà présents et quel historique récent peut servir de référence. Ne nettoyez jamais les modifications d’une autre personne pour préparer votre propre refactorisation.

1. Définir le comportement à préserver

Avant de modifier la forme du code, décrivez les entrées, sorties, erreurs et effets de bord observables. Pour une fonction qui transforme une commande, notez les cas valides, invalides et limites. Pour une route, notez le statut HTTP, le corps de réponse, l’autorisation et les appels externes. Ce contrat devient votre filet de sécurité.

Demandez à Claude Code de cartographier la zone : fichiers lus, appels entrants, dépendances et tests existants. Demandez-lui de séparer ce qui est confirmé dans le code de ce qui est supposé. Une réponse qui invente une utilisation inconnue doit déclencher une vérification, pas une modification.

Vérification : au moins un comportement important est formulé de façon testable. Si personne ne sait ce que la fonction doit faire, la première tâche est la découverte, pas le refactor.

2. Écrire des tests de caractérisation

Un test de caractérisation ne prétend pas que le comportement est idéal ; il enregistre ce que le système fait aujourd’hui. Il permet de détecter qu’une extraction, un renommage ou une simplification a changé un résultat connu. Choisissez des exemples réalistes mais sans données sensibles.

Pour un service, testez l’entrée normale, une entrée inhabituelle et une erreur significative. Pour une interface, vérifiez le texte, le lien ou l’état visible qui représente le contrat. Suivez le framework déjà présent dans le dépôt ; n’introduisez pas une nouvelle suite uniquement pour une petite refactorisation.

Vérification : rendez temporairement la sortie incorrecte. Le test doit échouer. S’il reste vert, il ne protège pas le comportement que vous croyez couvrir.

3. Choisir une transformation à faible risque

Préférez les transformations locales : extraire une fonction pure, remplacer une duplication identique, clarifier un nom ou isoler un adaptateur. Évitez de mélanger refactorisation, nouvelle fonctionnalité, mise à jour de dépendance et formatage global. Chaque objectif a des risques et des critères de test différents.

Demandez à Claude Code un plan avant l’écriture : fichiers touchés, éléments déplacés, tests à lancer et risques restants. Autorisez ensuite une seule tranche. Si le diff devient difficile à lire, arrêtez-vous, découpez davantage et revenez au dernier état connu via une procédure Git comprise par le propriétaire.

Vérification : le diff répond à une phrase simple, comme « extraction de la validation de nom ». S’il est impossible de résumer le changement, le périmètre est trop grand.

4. Relire le diff et les dépendances cachées

Lisez les ajouts et suppressions dans git diff. Cherchez les changements de valeur par défaut, d’ordre d’exécution, de gestion d’erreur et d’interface publique. Un renommage peut casser une importation dynamique ou un appel depuis un script non couvert par les tests. Utilisez les recherches du dépôt pour confirmer les références avant de supprimer une fonction.

Ne confondez pas une compilation réussie avec une migration terminée. Certains comportements sont calculés à l’exécution, pilotés par une configuration ou utilisés par un outil externe. Quand une dépendance reste incertaine, indiquez-la dans la remise et conservez la compatibilité plutôt que de supprimer par optimisation esthétique.

Vérification : les références supprimées sont recherchées dans le dépôt, le diff est exempt d’erreur d’espacement et les tests de caractérisation restent verts.

5. Prévoir sauvegarde et retour arrière

Git rend un retour arrière possible si l’historique est propre et que les changements sont petits. Travaillez dans une branche ou un espace de travail réservé, notez le commit de départ et évitez les commandes de réinitialisation destructrices sur un dépôt partagé. Un retour arrière doit restaurer un état identifié, pas effacer tous les changements locaux au hasard.

Pour les données externes ou migrations, la stratégie est différente : sauvegarde vérifiée, environnement de test, cible explicite et procédure approuvée. Une refactorisation de code ne doit pas inclure une modification de données de production sans tâche distincte.

Vérification : vous pouvez expliquer comment revenir au point de départ sans perdre le travail d’autrui. Si ce n’est pas clair, ne lancez pas l’intégration.

Problèmes fréquents et solutions

Les tests échouent avant le premier changement

Documentez l’échec initial. Ne le masquez pas dans votre refactorisation. Isolez d’abord la panne ou demandez au propriétaire si elle est connue, sinon la comparaison avant/après ne sera pas fiable.

Claude Code propose de mettre à jour toutes les dépendances

Refusez cette tranche. Une mise à jour de dépendance est une migration avec ses propres notes de version, tests et plan de retour arrière.

Une fonction a des effets de bord difficiles à tester

Isolez la partie pure, placez les appels externes derrière une interface existante et utilisez des doubles de test si le dépôt le permet. N’inventez pas une nouvelle architecture complète pour résoudre une seule difficulté.

FAQ

Peut-on refactorer sans tests ?

C’est possible mais plus risqué. Commencez par des tests de caractérisation ou un scénario manuel documenté avant de toucher à la structure.

Claude Code peut-il décider quelles fonctions supprimer ?

Il peut proposer des pistes, mais les références, usages externes et règles métier doivent être vérifiés par une personne responsable.

Faut-il faire un gros commit final ?

Non. Des commits petits, cohérents et revus rendent l’historique et le retour arrière plus sûrs.

Comment éviter un formatage massif ?

Limitez les fichiers, désactivez les actions globales non nécessaires et vérifiez le diff avant de sauvegarder ou de lancer un formatteur.

Quand arrêter le refactor ?

Quand le comportement est mieux isolé, les tests passent et la prochaine amélioration demanderait un nouveau risque ou une décision d’architecture.

Conclusion

Claude Code aide à refactorer un projet ancien lorsqu’il sert à explorer, proposer et documenter de petites transformations. Les garde-fous restent les mêmes : comportement d’abord, tests de caractérisation, diff lisible, propriétaire clair et retour arrière compris avant intégration.

Sources et limites

• Anthropic — Claude Code best practices : pratiques d’utilisation à vérifier selon la version.
• Git documentation — git diff : inspection des changements.
• Git documentation — branches : isolation des travaux avec Git.

Ce guide ne fournit pas de commande destructive de réinitialisation et ne remplace pas une analyse métier ou une migration de données planifiée.