CursorREFACTOR GUIDÉ AVEC
Prérequis
- Dépôt Git propre (branche dédiée, working tree sans dette)
- Scripts `typecheck`, `lint` et tests ciblés fonctionnels
- Périmètre refactor défini (ex. extraire `src/lib/blog/` en module)
- Rule refactor dans `.cursor/rules/` interdisant les changements hors scope
Un prompt « refactorise tout le repo » sature le contexte de l’agent et introduit des régressions silencieuses sur les imports dynamiques ou les routes App Router. @codebase combiné à un périmètre explicite, un plan validé étape par étape et des garde-fous Git permet de restructurer progressivement sans big-bang.
Cadrer le périmètre et le plan
Formulez l’objectif métier : « isoler la logique de parsing MDX », « renommer le module analytics sans changer l’API publique ». Listez les fichiers autorisés avec @folder et les dossiers interdits explicitement.
Demandez un plan numéroté sans exécution. Vérifiez qu’il respecte Next.js App Router (pas de déplacement de `page.tsx` sans mise à jour des routes) et les alias `@/` du tsconfig.
Créez `.cursor/rules/refactor-scope.mdc` avec `alwaysApply: false` : rappeler typecheck entre étapes, interdire le formatage massif unrelated, exiger conservation des exports publics.
Exécuter étape par étape
Pour l’étape 1 uniquement : « Exécute l’étape 1 du plan. @codebase pour trouver les imports de `@/lib/blog` — mets à jour uniquement les fichiers listés. » Limitez @codebase aux usages dispersés ; préférez @folder quand suffisant.
Après chaque étape : `pnpm run typecheck`, `pnpm run lint`, tests du module (`pnpm test src/lib/blog`). Committez avec un message scoped (`refactor(blog): extract parser step 1`).
Utilisez @Git pour vérifier que le diff ne contient que l’étape en cours. Si l’agent a touché un fichier interdit, revert ciblé avant de continuer.
Vérifier les pièges Next.js
Imports dynamiques `import()` et `next/dynamic` : l’agent rate souvent les chemins string. Grep manuel ou `@codebase cherche import dynamique de X`.
Barrel files `index.ts` : une réexport oubliée casse les consommateurs. Lancez le build, pas seulement typecheck.
Contenu éditorial (`src/content/**`) : les chemins relatifs aux assets changent rarement — ne les incluez pas sans nécessité.
Erreurs fréquentes
Refactor « tout améliorer en passant » : formatage, renommages cosmétiques, mise à jour de deps.
@codebase sans scope textuel : l’agent modifie des missions unrelated.
Big-bang sans commits intermédiaires : review impossible, revert coûteux.
Oublier `next.config.ts` redirects/rewrites liés au module déplacé.
Renommer un export public sans couche de compat `@deprecated`.
Ce qu’il faut retenir
Périmètre étroit + plan validé + @folder / @codebase ciblé.
Typecheck, lint, build entre chaque étape ; commit atomique.
Rule refactor-scope pour empêcher les dérives agent.
Pas de big-bang : restructurer progressivement reste reviewable.
FAQ
@folder pour un refactor localisé (module cohérent). @codebase quand les usages sont dispersés — mais gardez une liste textuelle de fichiers autorisés et interdits.
Oui, mais encadrez : une étape dédiée, grep de vérification, build complet. TypeScript seul ne couvre pas les strings ni les imports dynamiques.
Étapes courtes mergeables early, rebase fréquent sur main, pas de formatage global. Synchronisez avec l’équipe sur les dossiers touchés.
ChatGPT