Intégrer Claude Code dans un dépôt existant: choisir une première tâche sans rien casser

Troisième jour dans une nouvelle boîte, on me confie le code du paiement: environ 150 fichiers. Quasiment aucune documentation. Quand je pose des questions, on me répond toujours la même chose: « ça marche, alors on évite d’y toucher ». Faute de mieux, j’ai demandé à Claude Code: « comprends ce dépôt et corrige ce qui te dérange ».

Dix minutes plus tard, Claude m’a annoncé avec aplomb: « J’ai rangé 20 fichiers ». J’ouvre le diff et je blêmis. Il avait reformaté des fichiers SQL de migration, réordonné le .env.example, et surtout « optimisé » de sa propre initiative le délai d’attente des relances de paiement en le divisant par deux. Le code compilait, certes. Mais en production, le téléphone n’aurait pas arrêté de sonner pour des doubles débits.

Le problème, ce n’est pas l’intelligence de Claude. C’est simplement que le périmètre confié le premier jour était bien trop large. Pour déléguer sans danger un gros code écrit par d’autres, il faut, avant de chercher une IA plus maligne, décider en 30 minutes de quatre choses: l’ordre de lecture, les zones interdites, la première petite tâche, et la façon de vérifier. Rien que ça fait disparaître presque tous les accidents du premier jour. Aujourd’hui, je détaille ces 30 minutes, sous une forme que vous pouvez copier-coller.

Points clés

• Le premier jour sur un code existant, « regarde tout et corrige » est l’instruction la plus dangereuse: on démarre avec un périmètre flou.
• Les 30 premières minutes ne servent pas à produire un document d’architecture, mais une seule note d’une page pour choisir sans risque la première tâche.
• La note tient en quatre lignes: l’ordre de lecture, les zones interdites, la première petite tâche, la commande qui prouve que c’est terminé.
• La première tâche se limite à un endroit « facile à annuler »: du texte, le libellé d’un bouton, le nom d’un test, ça tombe bien.
• On confie à l’IA seulement « chercher et rédiger un brouillon ». La base de prod, la facturation, les suppressions et le bouton « publier », c’est l’humain qui appuie.

Pourquoi on trébuche sur la toute première instruction

Claude Code est rapide. Et c’est justement parce qu’il est rapide que, si la première consigne est large, il vous fabrique avec zèle des diffs dont personne n’a besoin.

Un nouveau collègue humain demanderait: « je peux toucher à ça ? ». L’IA ne demande pas. Par gentillesse, elle élargit le périmètre. Dites « range », et elle range vraiment jusque dans les moindres recoins. Le reformatage des migrations, l’« optimisation » des relances de facturation: de son point de vue, elle fait bien.

Donc, le premier jour, votre travail n’est ni de digérer tout le code, ni de pondre un beau plan d’amélioration. C’est de tracer des limites. Jusqu’où peut-elle agir seule, à partir d’où doit-elle demander à un humain. Une fois ce trait posé, votre demande passe de « réfléchis librement » à « reste dans ce périmètre et laisse une preuve ». Tracer ce trait prend 30 minutes. Pas besoin de comprendre tout le code.

La note d’une page à écrire en 30 minutes

Papier ou bloc-notes, peu importe. Remplissez seulement ces quatre points. Et l’ordre compte aussi.

1. Limitez l’ordre de lecture. Pas tous les fichiers d’un coup, mais juste le README et le package.json. Vous saurez quel langage, comment démarrer, quels outils sont utilisés. Ensuite, deux ou trois écrans ou routes principales. C’est suffisant.
2. Écrivez les zones interdites. Facturation, authentification, variables d’environnement, migrations de base de données. Indiquez explicitement: « tu peux lire, mais ne modifie pas ». Sans cela, Claude les traite comme des fichiers à éditer comme les autres.
3. Choisissez une seule petite première tâche. Limitez-la à un endroit facile à annuler: la formule en fin d’article, le libellé d’un bouton, le nom obscur d’un test. Quelque chose qu’on peut remettre en l’état immédiatement en cas d’erreur.
4. Décidez de la vérification qui prouve que c’est fini. Le build passe, le diff reste dans le périmètre prévu, l’écran ne casse pas. On juge sur le résultat d’une commande, pas à l’instinct.

Une fois ces quatre points remplis, l’essentiel de l’anxiété du premier jour s’évapore. Parce que la question n’est plus « qu’est-ce que Claude va bien pouvoir faire ? » mais « jusqu’où ai-je décidé de lui confier ? », et ça, c’est vous qui le maîtrisez.

Ce qu’on délègue à l’IA et ce qu’on décide soi-même

Mettre la frontière par écrit évite d’hésiter à chaque fois. Voici la répartition que j’utilise.

À faire	Confié à Claude	Décidé par l’humain
Lire le code et résumer la structure	○ lui faire un brouillon	la compréhension finale, je la vérifie moi-même
Proposer les zones interdites	○ lui faire lister des candidats	facturation et auth toujours validées par l’humain
Corriger du texte ou des libellés	○ on peut lui confier	je regarde le diff et j’approuve
Écrire dans la base de prod	×	l’humain l’exécute à la main
Suppression, publication, facturation	×	l’humain appuie sur le bouton

L’idée: mettre dès le départ toutes les opérations dangereuses du côté « demander à un humain ». On ne fait monter en automatique que les opérations dont on a confirmé la sécurité. Jamais l’inverse. Tout autoriser largement puis resserrer après l’accident, c’est l’ordre des choses inversé.

Si vous voulez approfondir cette logique, lisez aussi le Guide des premiers pas avec Claude Code et la checklist des 30 premières minutes: vos gestes du premier jour s’enchaîneront naturellement.

Le modèle de demande à copier-coller

Première astuce: ne le laissez surtout pas éditer tout de suite. Au début, on lui demande seulement de « lire et résumer dans un tableau ».

Je découvre ce dépôt. Ne modifie encore rien.
Lis dans cet ordre et renvoie le résultat sous forme de tableau.

1. Lis README et package.json, puis liste le langage utilisé, la commande de démarrage et les dépendances principales
2. Liste les endroits dangereux à modifier (facturation, auth, variables d'environnement, migrations de BDD), avec leur chemin de fichier
3. Propose 3 candidates de « première petite tâche » faciles à annuler, avec la raison
4. Pour chaque candidate, écris la commande qui confirme que c'est terminé (build, vérification du diff, etc.)

Je le répète: à ce stade, ne modifie pas un seul caractère.

Quand le tableau revient, vérifiez de vos propres yeux qu’aucune « zone interdite » ne manque. S’il en manque une, ajoutez-la, et seulement ensuite, confiez une seule tâche.

Parmi les candidates précédentes, ne traite que ◯◯ (corriger la formule en fin d'article).
Ne touche absolument pas à la facturation, l'auth, les variables d'environnement ni aux migrations.
Après l'édition, lance `npm run build` et montre-moi le diff avec `git diff --stat`.
Si quelque chose casse, explique la cause et le correctif en une ligne, puis arrête-toi.

Si vous écrivez les « zones interdites » directement dans CLAUDE.md, vous évitez de coller cette mise en garde à chaque fois. La façon de l’écrire est résumée dans Bonnes pratiques pour CLAUDE.md.

Un petit bout de code pour faire vérifier la machine

Si vous comptez sur votre mémoire pour « ne livrer qu’une fois bien préparé », un jour chargé vous oublierez forcément une étape. Alors, faites juger par la machine si la note d’une page est au moins complète. Le code suivant tourne tel quel avec Node.js.

// Vérifie par machine si la note d'une page du jour 1 est « prête à confier à Claude »
const repoMap = {
  goal: "choisir une seule première tâche facile à annuler",
  readFirst: ["README.md", "package.json", "src/routes/"],
  protectedAreas: [".env", "billing/", "migrations/", "wrangler.toml"],
  firstTask: "corriger la formule en fin d'article (ne pas toucher au code de paiement)",
  proofCommands: ["npm run build", "git diff --stat"],
};

function isReady(map) {
  const reasons = [];
  if (map.readFirst.length < 2) reasons.push("ordre de lecture trop large ou absent");
  if (map.protectedAreas.length === 0) reasons.push("zones interdites vides");
  if (!map.proofCommands.some((c) => c.includes("build"))) {
    reasons.push("pas de commande de vérification du build");
  }
  if (!map.firstTask) reasons.push("première tâche non choisie");
  return { ready: reasons.length === 0, reasons };
}

const result = isReady(repoMap);
console.log(result.ready ? "OK pour confier" : "Pas encore: " + result.reasons.join(", "));

À l’exécution, voici ce que ça donne.

node check-repo-map.mjs
# => OK pour confier

Pour tester, mettez protectedAreas à un tableau vide et relancez: vous obtenez « Pas encore: zones interdites vides ». C’est tout bête, mais ça stoppe avant la livraison l’accident le plus courant: « lancer en tout-automatique alors qu’on a oublié d’écrire les zones interdites ». Collez cette note directement dans CLAUDE.md ou dans une issue, et le vous de demain comme vos collègues réutiliseront le même jugement.

Trois situations où ça a vraiment marché

1. Sur un blog, protéger les liens des articles qui rapportent Quand on veut juste retoucher l’appel à l’action en fin d’un article populaire, dire à Claude « améliore la formule » l’amène vite à modifier aussi l’URL du lien produit. Alors on referme le périmètre: « tu peux retoucher le texte, mais ne change pas un seul caractère de l’URL de destination. Après modification, montre le build et le diff ». Ainsi, on polit seulement le texte sans casser les liens qui touchent directement au chiffre d’affaires.

2. Sur un SaaS, ne pas approcher du traitement de facturation Quand le texte d’explication d’un écran de réglages est confus, la cible à améliorer reste uniquement le texte affiché. On ne laisse pas toucher à la logique de facturation ou de changement de plan. Mettez billing/ dans les « zones interdites » de la note, et vous empêchez Claude de mettre la main, par gentillesse, dans la logique de relance.

3. Sur un outil interne, ne corriger que le nom des colonnes de sortie On me demande de clarifier le nom des colonnes d’un export CSV. Ce qu’on corrige, c’est la chaîne du nom de colonne; la logique d’agrégation, c’est une autre histoire. « Uniquement la chaîne affichée du nom de colonne. Ne touche pas aux formules de calcul. Montre la sortie avec des données d’exemple »: la vérification se fait alors en un instant.

Le point commun de ces trois cas n’est pas un manque de capacité de Claude, mais bien ceci: quand la frontière est mince, ça casse. Plus on écrit clairement la frontière, plus l’IA agit vite et en sécurité.

Les pièges fréquents et comment les corriger

Piège 1: faire lire tous les fichiers dès le départ. On dépense temps et tokens sur du formatage sans importance, et le vrai changement devient maigre. Le correctif: réduire la cible de lecture au README, au package.json plus deux ou trois routes principales. La vue d’ensemble, on l’élargit petit à petit une fois la première tâche terminée.

Piège 2: ne pas écrire les zones interdites. Claude traite la facturation, l’auth et les réglages de déploiement comme des cibles d’édition ordinaires. Le correctif: écrire la liste de protection avec les chemins de fichiers et la faire résider dans CLAUDE.md. Une consigne orale s’oublie; l’écrit reste.

Piège 3: croire le « c’est fait » sans avoir décidé de commande de vérification. L’humain doit deviner à chaque fois si le rapport de fin est juste. Le correctif: inclure dès le départ « build et montre-moi le diff » dans la demande. Un HTTP 200 ou une réponse qui sonne juste ne sont pas une preuve de réussite. On ne croit que le résultat réellement exécuté.

FAQ

Q. Ne serait-il pas plus sûr de comprendre toute la vue d’ensemble avant de déléguer ? En théorie oui, mais le premier jour, la compréhension globale ne se termine pas. Attendre qu’elle se termine bloque tout, alors on referme d’abord les « zones interdites » et on commence par une tâche facile à annuler. La compréhension s’élargit plus vite en travaillant.

Q. À quel point la première tâche doit-elle être petite ? Une granularité qui se boucle en un fichier, un texte, une commande. Si on demande gros, Claude élargit gentiment le périmètre. En vérifiant le build et une capture d’écran avant de passer à la suite, vous réduisez le temps d’annulation sans perdre en vitesse.

Q. Où vaut-il mieux écrire les zones interdites ? Dans CLAUDE.md, c’est ce qui dure le plus. La méthode « coller dans le prompt à chaque fois » se fait oublier les jours chargés. Posée à un seul endroit comme règle du projet, elle s’applique automatiquement même sur un nouveau chantier.

Q. J’ai dit « n’y touche pas » et Claude y a touché quand même. En général, la protection s’arrête au nom de fichier sans désigner le répertoire entier. Écrivez en périmètre, comme billing/ et pas seulement billing.js. Si ça déborde encore, ajoutez en tête de demande une étape « déclare les fichiers ciblés avant d’éditer »: il s’arrête plus facilement.

Q. Faut-il refaire cette note à chaque fois ? Une fois par dépôt suffit, ensuite on la réutilise. Collée dans CLAUDE.md et dans une issue, le vous de demain comme vos collègues héritent du même jugement. Quand une nouvelle cible à protéger apparaît, il suffit de l’ajouter.

Ce que j’ai vérifié en le faisant

Après l’affaire du code de paiement en intro, j’ai retenté la même procédure sur un autre dépôt existant. D’abord sans laisser modifier quoi que ce soit, je lui ai fait sortir seulement le tableau avec la demande ci-dessus: il a bien proposé billing/ et migrations/ comme cibles à protéger. En revanche, le fichier de variables d’environnement manquait, alors j’ai ajouté .env moi-même. Cela m’a reconfirmé l’importance de prévoir une relecture humaine.

J’ai limité la première tâche à une seule correction de formule en fin d’article, et je l’ai bouclée jusqu’à npm run build et git diff --stat. Le diff faisait sept lignes et ne touchait pas un seul caractère du code de paiement. J’ai aussi fait tourner le code de vérification: avec protectedAreas vide, il s’arrête bien sur « Pas encore ». Plutôt que de chercher une IA plus maligne, décider d’abord un petit périmètre où l’on peut tout annuler après une chute. C’est ce qui a le mieux marché, le premier jour, pour déléguer le code des autres.

Si vous en êtes à vouloir fixer en équipe une méthode pour intégrer Claude Code dans le code existant de l’entreprise, on peut, en formation ou consultation, regarder un vrai dépôt et organiser ensemble la façon de tracer les frontières. Côté prérequis officiels, jetez aussi un œil à Anthropic Claude Code getting started pour avancer sereinement.