Le code legacy combine souvent documentation incomplète, dépendances implicites et tests insuffisants. Un agent IA peut accélérer la cartographie et les transformations mécaniques. Lui demander de « moderniser tout le projet » produit en revanche un diff impossible à vérifier.
Étape 1 : caractériser avant de modifier
Ajoutez des tests qui capturent le comportement actuel, même lorsqu'il paraît étrange. Enregistrez les entrées, sorties, erreurs, contrats réseau et performances critiques. Ces tests de caractérisation constituent la frontière de sécurité.
Étape 2 : construire la carte du système
Demandez à l'agent d'identifier les points d'entrée, dépendances, zones sans tests et interfaces publiques. Vérifiez cette carte avec la recherche de code, les manifestes et l'exécution. Une explication plausible n'est pas une preuve.
Étape 3 : choisir une tranche verticale
Migrez un flux utilisateur ou un module, pas une couche entière. Maintenez une interface de compatibilité entre ancien et nouveau code. Chaque pull request doit être livrable ou réversible.
Étape 4 : déléguer les transformations mécaniques
Renommage, adaptation d'API, génération de tests et conversion de syntaxe sont de bons candidats. L'agent doit exécuter les tests et expliquer les changements non mécaniques.
Étape 5 : comparer le comportement
Exécutez ancien et nouveau chemins sur les mêmes données. Comparez sorties, erreurs, latence et effets de bord. Pour une migration de données, vérifiez les comptes, contraintes et possibilités de retour arrière.
Les garde-fous à inscrire dans les instructions
- Pas de changement d'API publique sans validation.
- Un seul objectif par PR.
- Aucun remplacement de dépendance sans justification.
- Tests avant et après chaque étape.
- Journal de décision pour les écarts de comportement.
- Rollback documenté avant déploiement.
Ce que l'humain doit conserver
La décision d'architecture, l'acceptation des incompatibilités et le séquencement restent humains. L'agent propose, recherche et implémente ; l'équipe assume le produit et son exploitation.
Utilisez les pratiques de context engineering et de tests automatisés assistés par IA pour maintenir des tâches courtes et vérifiables.
Exemple de découpage sur une API ancienne
Supposons une API PHP historique à migrer vers une version moderne. La première PR ajoute des tests de caractérisation. La deuxième introduit un adaptateur sans changer les contrôleurs. La troisième migre un seul endpoint derrière un drapeau de fonctionnalité. La quatrième compare les erreurs et performances, puis retire l'ancien chemin après une période d'observation.
L'agent peut préparer chaque étape, mais il ne doit pas supprimer l'ancien chemin avant que les métriques et tests ne prouvent l'équivalence.
Traiter la documentation comme un résultat
Demandez la mise à jour des diagrammes, procédures de déploiement et décisions d'architecture dans la même PR. Une migration dont le fonctionnement reste uniquement dans le contexte de l'agent recrée immédiatement de la dette.
Signaux d'arrêt
Interrompez la migration si le diff mélange refactoring et changement fonctionnel, si les tests deviennent moins lisibles, si une dépendance non prévue apparaît ou si le rollback n'est plus possible. Revenir à une étape plus petite n'est pas un échec : c'est le mécanisme de contrôle du risque.
Checklist de livraison
- Tests de caractérisation verts.
- Compatibilité publique explicitement vérifiée.
- Migration et rollback testés sur une copie des données.
- Observabilité disponible pour ancien et nouveau chemins.
- Documentation et runbook mis à jour.
- Décision de suppression de l'ancien code datée et attribuée.
