Refactoring de codebase avec Claude Code

Renommer des colonnes, migrer des conventions de nommage et mettre à jour les références de modèles dans un projet dbt nécessite de trouver chaque référence dans le SQL, les YAML, les blocs de docs, les tests singuliers et les macros. Manquer une seule référence produit un run de production cassé. Claude Code lit l’intégralité du projet, trouve chaque référence, met à jour tous les fichiers affectés en une seule passe, et affiche le diff complet pour révision.

Renommages de colonnes dans les modèles en aval

Le besoin de refactoring le plus courant : une colonne dans un modèle en amont est renommée, et tout ce qui est en aval doit suivre.

Rename customer_id to customer__id across all models in models/marts/
that reference dim_customers. Update the YAML files too.

Le processus de Claude :

1. Lit dim_customers pour confirmer le nom de la colonne et ses références actuelles
2. Recherche dans tous les fichiers de models/marts/ chaque occurrence de customer_id
3. Identifie quelles occurrences référencent dim_customers par opposition aux tables sans relation avec le même nom de colonne
4. Effectue des modifications ciblées dans tous les fichiers SQL affectés
5. Met à jour les fichiers de tests et descriptions YAML correspondants
6. Affiche le diff complet pour révision

Vous obtenez un ensemble complet de modifications que vous auriez autrement faites manuellement, avec l’avantage clé : Claude ne manque pas de fichiers. La recherche-et-remplacement humaine dans un projet dbt est sujette aux erreurs parce que les noms de colonnes apparaissent dans le SQL, les YAML, les blocs de docs, les tests singuliers, et parfois les macros. Claude lit tout cela.

Migrations de conventions de nommage

Les projets plus importants accumulent une dette de nommage. Vous adoptez les séparateurs double-underscore à mi-chemin, et maintenant la moitié du projet utilise order_id et l’autre moitié order__id. Ou vous passez du préfixe stg_ à base__ et devez mettre à jour tous les appels ref().

We're moving from ref('stg_orders') to ref('base__shopify__orders') across
the codebase. Find all references to stg_* models and update them to use
the new base__* naming convention.

C’est exactement le type de travail où la conscience de la codebase entière de Claude Code est importante. Il ne s’agit pas seulement de trouver la chaîne ref('stg_orders') — c’est de comprendre que stg_orders était un modèle intermédiaire et que le nouveau base__shopify__orders en est le remplacement, puis de mettre à jour chaque appel ref() en aval, chaque déclaration de dépendance YAML, chaque définition de source qui le référence.

Pour un projet avec 50+ modèles, cette migration pourrait toucher 30 fichiers. Manuellement : une journée de recherche-et-remplacement minutieuse avec une grande anxiété quant à ce qui a été manqué. Avec Claude Code : un seul prompt, une révision du diff, et un dbt parse pour confirmer l’absence de références brisées.

Quand exécuter dbt parse et dbt compile après le refactoring

Pour tout refactoring qui touche des appels ref() ou des noms de modèles, incluez la vérification dans le prompt :

Rename all stg_* models to base__* following our naming convention.
After making changes, run dbt parse to verify no broken references.

dbt parse détecte les appels ref() brisés sans rien matérialiser. C’est suffisamment rapide pour s’exécuter comme étape de vérification dans la même session Claude. Claude voit la sortie, corrige les références manquées, et le relance jusqu’à ce que tout soit propre.

dbt compile est plus approfondi — il rend le Jinja et vous montre le SQL réel qui s’exécuterait. Pour les renommages de colonnes en particulier :

After renaming the columns, run dbt compile --select marts/+ to verify
the compiled SQL looks correct before I run a full build.

Ces étapes de vérification transforment le refactoring de “je pense que c’est correct” en “je peux voir que c’est correct.”

Une approche systématique des mises à jour YAML

Les fichiers SQL sont la cible évidente, mais les fichiers YAML sont là où le refactoring se casse silencieusement. Un renommage de colonne dans le SQL qui n’est pas reflété dans les tests de schéma YAML se construira toujours — mais le test échouera à la prochaine exécution, ou pire, la description de la colonne décrira la mauvaise colonne.

Incluez explicitement le YAML :

Rename order_amount to order__amount_usd in base__shopify__orders.
Update:
1. The SQL column definition and all its references downstream
2. The schema.yml column name and description
3. Any singular tests in the tests/ directory that reference this column
4. Any docs blocks in models/docs.md that document this column

La précision de l’instruction détermine la précision du résultat. Des prompts de refactoring vagues produisent des refactorings partiels qui semblent complets mais se cassent subtilement.

Migrations multi-couches

Certaines migrations affectent l’architecture du projet, pas seulement les noms. Déplacer des modèles entre couches, changer les stratégies de matérialisation sur un ensemble de modèles, réorganiser la structure des dossiers — ces changements nécessitent des modifications coordonnées que Claude Code gère nativement parce qu’il maintient une conscience du projet complet.

We're splitting models/marts/finance/ into two folders:
models/marts/finance/revenue/ and models/marts/finance/costs/.

Move models:
- mrt__finance__revenue, mrt__finance__arr, mrt__finance__mrr → revenue/
- mrt__finance__cogs, mrt__finance__opex → costs/

Update all ref() calls, the dbt_project.yml config block, and any
documentation that references the old paths.

Cela nécessiterait une coordination minutieuse sur plusieurs fichiers manuellement. Claude Code lit la structure du projet, effectue les déplacements, met à jour le dbt_project.yml pour appliquer les configurations aux nouveaux chemins, et met à jour toute description de modèle qui mentionne les anciens chemins.

Révision du diff

Pour le travail de refactoring, la révision du diff est l’étape la plus importante. Claude affiche chaque fichier modifié — lisez-les tous.

À surveiller :

• Références manquées. Recherchez dans le diff l’ancien nom de colonne ou de modèle pour confirmer que rien n’a été omis.
• Modifications non intentionnelles. Claude fait parfois des améliorations connexes que vous n’avez pas demandées. Décidez si vous les conservez.
• Exhaustivité du YAML. Confirmez que les noms de colonnes dans schema.yml correspondent aux noms de colonnes SQL mis à jour.
• Validité des tests. Si un test référençait l’ancien nom de colonne, confirmez qu’il a été correctement mis à jour.

La révision du diff pour un refactoring sur 30 fichiers prend 10 à 15 minutes. C’est encore nettement plus rapide que de faire les modifications manuellement, et la révision est le but — vous voulez comprendre chaque modification avant qu’elle soit déployée.

Effet sur le travail de maintenance

Un coût de refactoring réduit signifie que le travail différé se fait. Quand un renommage de colonne prend 20 minutes au lieu d’une demi-journée, la documentation reste à jour, le nommage reste cohérent, et les tests sont mis à jour plutôt que supprimés quand les schémas changent.