refactor

Refactor — une expérience structurelle

Refactor modifie la structure tout en préservant le comportement observable. Il exécute une transformation choisie par l'appelant et rapporte le résultat.

Invite

Refactoriser billing-service/internal/retry/backoff.go : extraire le calcul de backoff exponentiel de RetryRequest dans sa propre fonction, sans autre changement de comportement. Enregistrer une baseline, exécuter go test ./internal/retry/... avant et après, et rapporter le résumé du diff, les commandes, les résultats et tout ce qui n'a pas été vérifié.

Ça fonctionne si

• Le rapport nomme le comportement préservé et cite go test ./internal/retry/... exécuté avant et après.
• git diff --stat ne touche que internal/retry/backoff.go, jamais un fichier non lié.
• Les hash des sorties de référence sont capturés et comparés octet par octet chaque fois que la surface modifiée produit une sortie, par ex. sha256sum avant et après.
• La liste des « comportements non vérifiés » du rapport est présente dans la sortie même lorsqu'elle est vide, nommant toute surface que les portes ont ignorée.

Procédure

1. Nommer le comportement préservé, la surface d'acceptation ciblée et le problème structurel concret pour ses appelants. Réutiliser les termes du domaine de l'appelant et les exemples comportementaux acceptés ; préserver leur sens à travers le changement.
2. Enregistrer une baseline honnête, y compris les échecs ambiants reproductibles. Pour une évaluation comparant le comportement exécutable, figer la source de départ et construire sa baseline avant les modifications ; conserver ce binaire et les entrées de comparaison. Comparer le candidat en utilisant ces entrées et la même chaîne d'outils. Cela n'ajoute aucun rituel de comparaison exécutable à une refactorisation ordinaire.
3. Appliquer une transformation bornée : extraire, renommer, mettre en ligne, simplifier, encapsuler, déplacer ou supprimer du code mort. Juger le résultat par ce que les appelants doivent comprendre et où une règle de domaine doit être modifiée, pas seulement par la taille du fichier.
4. Exécuter le check ciblé et le plus petit check de régression au niveau du package justifié par la surface modifiée.
5. Retourner le résumé du diff, les commandes, les résultats et les comportements non vérifiés.

Ne pas combiner une correction de comportement nouvellement découverte avec le changement structurel. Un résultat rouge est une preuve pour l'appelant ; ce skill n'annule pas, ne réduit pas, ne réessaie pas, ne valide pas, n'engage pas et n'oriente pas automatiquement les travaux ultérieurs.

Responsabilité et coût de l'interface

Avant d'ajouter une interface ou de diviser un module, inspecter des appelants représentatifs. Compter les concepts qu'ils doivent coordonner : configuration requise, ordonnancement, états, gestion d'erreurs et règles de domaine répétées. Une frontière utile place une règle cohérente sous un seul propriétaire et permet aux appelants de demander un résultat sans reproduire cette règle. Rejeter un wrapper qui ajoute seulement un autre nom ou repousse la même coordination dans ses appelants. Les frontières existantes sont suffisantes lorsqu'aucun problème concret d'appelant ne justifie de les modifier.

Utiliser le vocabulaire de l'appelant pour les opérations et types extraits. Une ambiguïté de nommage qui modifie le comportement appartient à la définition de domaine existante ; consulter Domaine uniquement lorsque cette distinction a besoin d'être travaillée. Renommer un symbole public, un champ persistant ou une valeur de protocole est un changement de compatibilité, sauf si le périmètre accepté le prévoit.

Lorsque la transformation nécessite une couture — une frontière d'extraction, une interface ou une division de module — et qu'il existe plus d'une couture candidate, sonder avant de couper. Exécuter la sonde en isolation jetable (une branche de travail, un worktree ou un arbre copié que la politique de l'appelant permet) : esquisser la couture, voir ce qu'elle force — remaniement de signatures, cycles d'importation, réécritures de tests — puis jeter la sonde et ne conserver que la connaissance. Condition d'arrêt : au maximum deux sondes ; si la deuxième couture candidate résiste également, rapporter les deux résultats à l'appelant au lieu d'en essayer une troisième. Couper la première couture imaginable directement dans l'arbre de travail est le mode d'échec de la couture prématurée : la mauvaise frontière se calcifie car l'annuler coûte maintenant plus cher que de vivre avec.

Portes de neutralité

« Préserver le comportement » est une affirmation à exécuter, pas à affirmer. Verrouiller la transformation sur une preuve de comportement identique :

• Le check ciblé et le check de régression au niveau du package passent à la fois avant et après, avec le même ensemble d'échecs préexistants — aucun nouveau rouge, et aucun rouge disparu silencieusement non plus (un test qui cesse de s'exécuter est un changement de comportement).
• Pour les surfaces produisant des sorties (générateurs, sérialiseurs, formateurs, rapports), hasher les sorties : capturer les hash des sorties de référence sur des entrées identiques avant le changement et comparer octet par octet après. Une divergence de hash est une différence de comportement à signaler et expliquer, jamais à ignorer ; l'appelant décide de conserver, réduire ou inverser le changement.
• Les messages d'erreur observables, les codes de sortie et les signatures publiques sur la surface modifiée font partie du comportement, sauf si l'appelant les a exclus.

Une porte de neutralité qui a été sautée ou réduite après coup est le mode d'échec de la neutralité post-hoc — le diff décide ce qui a été testé. Nommer toute surface que les portes n'ont pas couverte dans la liste des comportements non vérifiés du rapport.

Références

• Simplification préservant le comportement
• Scénarios de comportement
• Référence de capacité amont — Matt Pocock ; adaptation originale AgentOps.