Brancher Claude Code sur un projet existant : la méthode en 5 étapes

TL;DR — brancher Claude Code sur du legacy

• Le réflexe qui rate : ouvrir le repo, demander « refactore ça » et regarder le résultat exploser. Sur un projet existant, le problème n'est jamais la capacité du modèle — c'est ce qu'il ne sait pas de ton code.
• La méthode en 5 étapes : cartographier → écrire le CLAUDE.md → sécuriser le périmètre → première tâche jetable → poser les portes de vérification.
• Le rapport de temps : compte 2 à 3 heures de mise en place pour un repo de taille moyenne. C'est ce qui transforme un assistant qui devine en un assistant qui sait.
• Le piège n°1 : lancer une grosse tâche en premier. La première tâche doit être petite, vérifiable et jetable — elle sert à calibrer, pas à produire.
• Le piège n°2 : un CLAUDE.md écrit « au cas où ». Chaque ligne doit avoir gagné sa place, sinon elle dilue les instructions qui comptent.

Sur un projet neuf, Claude Code impressionne tout de suite : le contexte est vide, les conventions sont celles qu'il pose lui-même, rien ne le contredit. Sur une base de code existante — trois ans d'historique, deux conventions de nommage qui cohabitent, une CI capricieuse — la première session finit souvent en déception. Le modèle produit du code qui a l'air correct et qui ignore la moitié des règles implicites de ton projet.

Ce n'est pas un problème de modèle, c'est un problème d'onboarding. Un développeur senior qui arrive sur ton repo passe deux jours à lire avant d'écrire une ligne. Claude Code, lui, écrira dès la première seconde si tu le lui demandes. La méthode ci-dessous consiste à lui imposer ces deux jours de lecture — en deux heures.

Étape 1 — Cartographier avant de laisser écrire

La première session ne doit produire aucun code. Elle sert à obtenir une carte, et surtout à découvrir ce que Claude comprend de travers.

Trois demandes, dans cet ordre :

1. La structure. « Explore ce repo et décris son architecture : points d'entrée, modules principaux, où vivent les données, comment ça se lance. Ne modifie rien. »
2. Les conventions réelles. « Quelles conventions de code observes-tu réellement dans ce projet — nommage, gestion d'erreurs, structure des tests, style d'imports ? Cite des fichiers en exemple. »
3. Les incohérences. « Où observes-tu deux conventions contradictoires dans le même repo ? »

C'est la troisième question qui a le plus de valeur. Les réponses te disent où ton propre projet est ambigu — et donc où l'assistant va se tromper si tu ne tranches pas. Un repo qui mélange camelCase et snake_case dans les mêmes modules produira du code mixte tant que personne n'aura écrit la règle quelque part.

La cartographie n'est pas une formalité de démarrage. C'est le seul moment où tu obtiens gratuitement un audit externe des zones floues de ton code.

Étape 2 — Écrire le CLAUDE.md à partir de ce que tu viens d'apprendre

Le fichier CLAUDE.md à la racine est chargé automatiquement à chaque session. C'est la mémoire persistante du projet — et la principale différence entre un assistant qui devine et un assistant qui sait.

Ne le rédige pas depuis une page blanche : demande-le à Claude à partir de la cartographie, puis coupe. Le squelette qui fonctionne :

Deux règles de rédaction, et elles comptent plus que le contenu :

• Tranché, pas descriptif. « Le projet utilise plutôt des composants fonctionnels » ne sert à rien. « Composants fonctionnels uniquement, pas de classes » est une instruction.
• Zéro ligne « au cas où ». Chaque instruction inutile dilue l'attention portée aux autres. Un CLAUDE.md de 60 lignes utiles bat un fichier de 300 lignes génériques.

La section Pièges connus est celle qui rapporte le plus. C'est là que tu écris ce qu'aucune lecture du code ne révèle : « le build casse si on touche à X sans regénérer Y », « ce module est appelé par un cron externe, ne pas changer sa signature ».

Étape 3 — Sécuriser le périmètre avant la première tâche

Sur un projet existant, les dégâts potentiels ne sont pas théoriques : historique git réel, secrets en local, base de données de développement partagée. Trois garde-fous, à poser avant d'écrire quoi que ce soit.

Travailler sur une branche dédiée. Jamais sur la branche principale. Cela paraît évident et c'est pourtant l'erreur la plus fréquente des premières sessions.

Vérifier ce qui est lisible. Ce que Claude Code peut lire, il le lira si c'est pertinent pour la tâche. Un fichier d'environnement non ignoré, un dump de base laissé dans le projet, un fichier de credentials oublié : à traiter avant, pas après.

Cadrer les permissions. Les commandes destructrices — suppression de fichiers, réécriture d'historique git, opérations sur la base de données — doivent rester sous validation explicite. Notre guide sur la sécurisation des permissions de Claude Code détaille la configuration, et l'article sur la sandbox va plus loin sur l'isolation des secrets.

Le dernier point est le plus sous-estimé : si ta suite de tests ne passe pas déjà à 100 % avant la première tâche, tu n'auras aucun moyen de savoir ce qui a régressé. Répare-la d'abord, ou accepte de piloter à l'aveugle.

Étape 4 — Une première tâche petite, vérifiable et jetable

La tentation est d'attaquer par la grosse tâche qui traîne depuis six mois. C'est exactement ce qu'il ne faut pas faire. La première tâche a un seul objectif : calibrer.

Les bons candidats :

• Ajouter des tests sur un module existant qui n'en a pas.
• Corriger un bug isolé et bien décrit, avec un moyen de reproduction.
• Extraire une fonction dupliquée à trois endroits.
• Écrire la documentation d'un module que tu connais bien.

Le dernier est le meilleur test de tous : tu connais déjà la réponse. Si la documentation produite décrit fidèlement ce que fait le module, le contexte est correctement posé. Si elle est plausible mais fausse par endroits, ton CLAUDE.md a un trou — et tu viens de l'identifier avant qu'il ne coûte cher.

Sur les tâches plus lourdes, exige un plan avant le code. « Décris ce que tu vas modifier, fichier par fichier, et pourquoi. N'écris rien tant que je n'ai pas validé. » Le plan se relit en deux minutes ; un diff de 400 lignes se relit en trente.

Étape 5 — Poser les portes de vérification

Sur un projet existant, la règle est simple : rien n'est terminé tant que ce n'est pas prouvé. Pas « ça devrait marcher », pas « le code semble correct ». Quatre portes, à passer dans l'ordre :

1. Ça compile / ça type-check. La commande, exécutée, avec sa sortie.
2. Les tests passent. Toute la suite, pas seulement les nouveaux tests.
3. Le diff est lu par un humain. Pas survolé : lu. C'est la porte que tout le monde saute et c'est celle qui attrape les vrais problèmes.
4. Le comportement est vérifié réellement. L'app tourne, l'endpoint répond, l'écran s'affiche.

Notre protocole des 4 portes développe chacune d'elles. Sur du legacy, la porte n°3 mérite une attention particulière : Claude Code produit du code qui ressemble à ton code, ce qui rend les erreurs plus difficiles à repérer que sur un projet neuf. La cohérence stylistique n'est pas une garantie de correction.

Combien de temps ça prend, concrètement

Ces deux à trois heures ne sont pas un coût, ce sont les seules heures qui déterminent la qualité de tout ce qui suivra. Un projet sans CLAUDE.md repart de zéro à chaque session : tu réexpliques les mêmes conventions, tu recorriges les mêmes erreurs, indéfiniment.

Ce qui ne marche pas, et pourquoi

« Refactore tout le module X. » Trop de surface, aucun critère de succès, un diff illisible. Découpe : un comportement à la fois, un test à chaque fois.

Un CLAUDE.md généré automatiquement et jamais relu. Il décrira ce que le code *fait*, pas ce que tu *veux*. Or l'intérêt du fichier est précisément de contenir les décisions, pas les observations.

Enchaîner dix tâches dans la même session. Le contexte se remplit, les instructions du début pèsent de moins en moins lourd. Une tâche, une session — le sujet est traité dans notre article sur la gestion du contexte.

Faire confiance parce que le code est joli. Sur du legacy, c'est le piège central. Le code généré adopte tes conventions, donc il *paraît* juste. La seule preuve reste la vérification.

FAQ

Faut-il un CLAUDE.md sur un projet existant ?

Oui, et c'est même le seul élément vraiment indispensable de la mise en place. Sans lui, chaque session repart de zéro : les conventions du projet, les commandes de test, les zones sensibles doivent être réexpliquées à chaque fois, et l'assistant retombe dans les mêmes erreurs. Le fichier est chargé automatiquement à chaque démarrage et sert de mémoire persistante du projet. Un fichier de 60 à 120 lignes tranchées, écrit à partir d'une session de cartographie, suffit largement — un fichier long et générique est moins efficace qu'un fichier court et décidé.

Par quelle tâche commencer sur une base de code existante ?

Par une tâche petite, vérifiable et dont tu connais déjà la réponse. Écrire la documentation d'un module que tu maîtrises est le meilleur test de calibration : si le résultat est fidèle, le contexte est bien posé ; s'il est plausible mais faux par endroits, tu viens d'identifier un trou dans ton CLAUDE.md avant qu'il ne coûte cher. Ajouter des tests sur un module qui n'en a pas, ou corriger un bug isolé avec un moyen de reproduction, fonctionne également. Ce qu'il faut éviter, c'est d'attaquer par le gros refactoring qui traîne depuis six mois.

Combien de temps faut-il pour brancher Claude Code sur un projet existant ?

Entre deux heures et trois heures et quart pour un repo de taille moyenne, réparties ainsi : 30 à 45 minutes de cartographie, 45 à 60 minutes de rédaction du CLAUDE.md, 30 minutes de sécurisation du périmètre et 30 à 60 minutes de première tâche de calibration. Ce temps n'est pas une perte : c'est ce qui distingue un assistant qui devine d'un assistant qui connaît les conventions, les commandes et les pièges du projet. Sans cette mise en place, le temps est dépensé de toute façon, mais session après session et sans rien capitaliser.

Comment éviter que Claude Code casse du code existant ?

Quatre garde-fous, à poser avant la première tâche. Travailler sur une branche dédiée, jamais sur main. Vérifier qu'aucun secret n'est lisible dans le projet, car ce qui est lisible sera lu si c'est pertinent pour la tâche. Cadrer les permissions pour que les commandes destructrices restent sous validation explicite. Et surtout, s'assurer que la suite de tests passe intégralement avant de commencer : sans cette base, il devient impossible de savoir si une régression vient de toi ou de l'assistant.

Le code généré ressemble au mien, est-ce bon signe ?

C'est un signe que le contexte est bien posé, pas une preuve que le code est correct — et c'est précisément le piège du legacy. Sur un projet existant, le code produit adopte tes conventions de nommage, ta structure et ton style, ce qui rend les erreurs plus difficiles à repérer que sur un projet neuf où tout détonne. La cohérence stylistique doit donc augmenter ta vigilance, pas la baisser. Les quatre portes de vérification restent obligatoires : compilation, tests complets, lecture réelle du diff, et vérification du comportement dans l'application.