Reprendre le code d'un autre avec Claude Code : la première heure

Premier jour de la passation, j’ouvre le dépôt d’un outil interne laissé par la personne qui partait. Le README fait trois lignes, la dernière mise à jour remonte à huit mois. Sans trop réfléchir, je demande à Claude Code : « comprends ce projet et corrige le texte de l’écran de connexion ». Cinq minutes plus tard, il avait « rangé au passage » les fichiers de configuration liés à l’authentification, et même un script de déploiement en production que plus personne n’osait toucher.

Heureusement, un git status m’a alerté et j’ai tout annulé. Mais quand je pense à ce qui se serait passé si j’avais fait un git commit sans rien voir, j’en ai encore des frissons. Le problème n’était pas l’intelligence du modèle. C’est que je lui ai confié le travail sans savoir moi-même où il avait le droit de toucher.

La première heure dans le code de quelqu’un d’autre n’est pas une heure pour corriger, c’est une heure pour dessiner une carte. Dans cet article, je détaille comment tracer cette carte, sous la forme d’une procédure qui évite l’accident même sur un dépôt inconnu.

Points clés

• La première heure ne sert pas à « corriger » mais à « cartographier ». On sépare d’abord les zones où l’on peut toucher de celles où l’on ne touche pas.
• Ce que l’on confie à Claude Code se limite à « lire et lister ». C’est l’humain qui décide ce qui devient zone protégée.
• Avant de corriger, on choisit toujours une commande de preuve (build ou tests). C’est elle qui atteste que « c’est réparé ».
• Le premier correctif se limite à quelque chose de petit, réversible avec une seule commande git.
• Ce que l’on a compris tient sur une seule note. La prochaine personne qui entrera dans ce dépôt (vous compris, plus tard) n’aura pas à refaire la même enquête.

Pourquoi l’accident arrive dans la première heure

Sur un nouveau dépôt, le faux pas vient rarement de la difficulté du code. Il vient du fait que la forme du dépôt reste invisible.

Quel dossier correspond à l’écran ? Où se trouve la logique en coulisses ? Quel fichier porte la configuration de production ? Sans réponse à ces questions, demander « corrige ça comme il faut » pousse Claude Code à réécrire, de bonne foi, un périmètre trop large. Tant qu’on ne lui dit pas « ne touche pas à ça », l’IA considère qu’un endroit est autorisé à l’édition.

Les reprises de projet sont particulièrement risquées. Les règles implicites du prédécesseur, ses habitudes de nommage, ce commentaire mis en commentaire on ne sait pourquoi : ce contexte n’est écrit nulle part dans le code. Même un humain ne saisit pas tout le premier jour. C’est précisément pour ça que la première chose à faire n’est pas l’édition, mais la cartographie.

Les 4 étapes pour dessiner la carte

L’ordre compte. Délimiter ce qu’on lit, fixer les zones protégées, choisir la commande de preuve, et seulement à la fin corriger une petite chose. On avance dans cet ordre.

Étape 1 : écrire l’objectif du jour en une phrase

« Comprendre ce projet » est trop large. Avec un objectif aussi vaste, Claude Code comme l’humain perdent l’endroit où s’arrêter.

À la place, on écrit ceci : « corriger une seule formulation sur l’écran de connexion et vérifier que le build passe ». Un objectif qui tient en une phrase permet aussi de voir d’un coup d’œil s’il est atteint.

Étape 2 : séparer ce qu’on lit de ce à quoi on ne touche pas

C’est le cœur de la carte. Avant de tout confier à Claude Code en lecture, on met d’abord en mots les endroits interdits à l’écriture.

Ce que je place systématiquement en zone protégée : l’authentification, la facturation, les fichiers de variables d’environnement (.env), et les scripts de déploiement en production. Une erreur y fait beaucoup de dégâts et reste difficile à annuler. Au début, je précise donc explicitement : « lire, oui ; écrire, non ».

Étape 3 : choisir la commande de preuve à l’avance

Quand l’IA annonce « c’est corrigé », sur quelle base peut-on dire que c’est vraiment le cas ? On le décide avant.

Dans la plupart des projets, c’est une commande de build ou de tests qui sert de preuve. npm run build qui passe, npm test qui devient vert. En fixant cette commande unique avant de corriger, on ne gobe pas le « c’est fait » de Claude Code : on tranche par un verdict de machine.

Étape 4 : un seul petit correctif réversible

Une fois la carte prête, on ne se montre pas gourmand pour le premier correctif. On choisit une seule chose annulable d’un git checkout : une formulation, l’ajout d’un commentaire, une faute de frappe évidente.

On résiste au « tant qu’on y est, faisons aussi ». Un gros diff, personne ne peut le relire, et en cas d’accident, le retour en arrière devient pénible.

Ce qu’on confie à Claude Code, et ce que l’humain décide

Quoi déléguer et quoi garder en main pendant la cartographie : mélanger les deux, c’est exactement l’accident du début.

Tâche	Responsable	Raison
Lister les fichiers, comprendre l’arborescence	Claude Code	La lecture mécanique est rapide et précise
L’enquête « où se trouve cette fonctionnalité ? »	Claude Code	La recherche et le résumé sont son point fort
Décider ce qui devient zone protégée	Humain	L’ampleur des dégâts dépend du contexte. L’IA l’ignore
Trancher la commande de preuve	Humain	Seul l’humain connaît les particularités du projet
Modifier la production, la facturation, l’authentification	Humain	Les opérations difficiles à annuler exigent un feu vert humain

Le principe est simple. On délègue la lecture et le listage. L’humain garde les décisions difficiles à annuler. On ne fait monter en grade Claude Code, ensuite, que sur les opérations dont on a confirmé qu’elles sont sûres.

La conception fine des permissions fait l’objet d’un autre article. Si vous hésitez sur ce qu’il faut bloquer en premier, voyez le guide des permissions.

Le prompt de cartographie à copier-coller

Voici le prompt que j’envoie réellement dans la première heure. Collez-le tel quel et remplacez seulement le nom du dépôt par le vôtre.

Je touche ce dépôt pour la première fois. Ne modifie encore rien.
Examine les points suivants dans l'ordre et rends-moi un compte rendu sous forme de liste à puces.

1. La structure des dossiers de premier niveau et le rôle de chacun (une supposition suffit, mais indique-la comme telle)
2. Les commandes de build, de test et de démarrage (depuis package.json ou le README)
3. L'emplacement des fichiers liés à l'authentification, la facturation, les variables d'environnement et le déploiement en production
4. Dans quel fichier se trouve « le texte de l'écran de connexion »

Après le compte rendu, les fichiers du point 3 sont désormais en « lecture seule, édition interdite ».
Le seul fichier que tu as le droit de modifier est celui trouvé au point 4.

Le point clé, c’est de poser dès la première ligne le garde-fou « ne modifie encore rien ». Sans ça, certaines IA se mettent à corriger au passage de l’enquête.

Le script de vérification prêt à l’emploi

Une fois la carte tracée, c’est plus rassurant de pouvoir lancer le même contrôle avant et après le correctif. Le script suivant vérifie que le build passe avant comme après, et que le diff ne s’étend pas trop. Il tourne avec Node.js.

// verify-edit.mjs
// Vérifie que le build passe avant/après le correctif et que le diff n'est pas plus large que prévu
import { execSync } from "node:child_process";

// On fixe à l'avance un plafond de fichiers modifiés, pour rester dans le réversible en une commande
const MAX_CHANGED_FILES = 3;

function run(cmd) {
  return execSync(cmd, { encoding: "utf8" }).trim();
}

try {
  // On compte le nombre de fichiers modifiés
  const changed = run("git diff --name-only")
    .split("\n")
    .filter(Boolean);

  console.log(`Fichiers modifiés : ${changed.length}`);
  changed.forEach((f) => console.log(`  - ${f}`));

  if (changed.length > MAX_CHANGED_FILES) {
    console.error(
      `Le diff est trop large (${changed.length} > ${MAX_CHANGED_FILES}).`,
    );
    console.error("Annule d'abord avec git checkout, puis découpe le correctif en plus petit.");
    process.exit(1);
  }

  // On vérifie qu'aucune zone protégée n'a été touchée
  const protectedHits = changed.filter((f) =>
    /(^|\/)\.env|auth|billing|deploy/i.test(f),
  );
  if (protectedHits.length > 0) {
    console.error("Des modifications touchent une zone protégée :");
    protectedHits.forEach((f) => console.error(`  - ${f}`));
    process.exit(1);
  }

  // On vérifie que le build passe (à remplacer selon le projet)
  console.log("Vérification du build...");
  run("npm run build");
  console.log("Build OK. Le correctif reste dans le périmètre sûr.");
} catch (err) {
  console.error("La vérification a échoué :", err.message);
  process.exit(1);
}

On l’exécute avec node verify-edit.mjs. Si trop de fichiers sont modifiés, ou si une zone protégée a été touchée, il s’arrête sur-le-champ. L’accident du début, où même les fichiers d’authentification avaient été « rangés », aurait été stoppé en amont si je l’avais passé par ce script.

Trois situations où ça marche

Concrètement, sur quels dépôts s’en servir : voici trois cas que j’ai testés.

1. L’outil interne hérité Quand on entre dans une base de code sans documentation. On fait d’abord lister l’arborescence et les commandes de démarrage, puis on fige l’authentification et les fichiers de configuration en zone protégée. Le premier correctif porte sur quelque chose de visuel, comme le changement d’un libellé dans l’écran d’administration, dont le résultat se voit à l’œil.

2. La première contribution à un dépôt public Quand on ouvre sa première Pull Request sur un open source d’autrui. On fait d’abord identifier la commande de tests, puis on propose un seul petit correctif tout en gardant npm test au vert. Une correction d’un fichier, réversible, est plus facile à intégrer qu’une vaste proposition d’amélioration.

3. La relance d’un vieux projet Quand on reprend un code laissé six mois de côté. On fait enquêter Claude Code sur « jusqu’où ça marche encore », et on cartographie les points d’entrée cassés. On corrige en partant de l’endroit le plus facile à annuler.

Pièges et comment s’en sortir

Piège 1 : vouloir tout corriger d’un coup Avec « tant qu’on y est, refactorisons aussi », le diff gonfle à 50 fichiers et plus personne ne peut le relire. La parade : poser un plafond de fichiers modifiés avec le script de vérification ci-dessus. S’il est dépassé, on annule et on découpe.

Piège 2 : considérer que le build qui passe suffit Même si le build passe en local, rien ne dit que l’écran est conforme. Pour un correctif de texte, l’ensemble n’est complet qu’une fois l’écran réellement ouvert et les caractères vérifiés à l’œil.

Piège 3 : ne signaler les zones protégées qu’à l’oral Même si on écrit « ne touche pas à l’authentification » dans le prompt, ça peut s’oublier au milieu d’une longue tâche. La parade : faire rejeter mécaniquement par le script toute modification d’une zone protégée. On se protège par une commande, pas par la mémoire humaine.

Piège 4 : ne pas conserver la carte tracée On a beau passer une heure à tout comprendre, sans note on referait la même enquête la fois suivante. Noter l’arborescence, la commande de preuve et les zones protégées sur une seule page rend service à votre futur vous.

Cette note de carte est encore plus efficace si on l’écrit dans CLAUDE.md comme règle du projet. La manière de la rédiger est résumée dans les bonnes pratiques CLAUDE.md.

FAQ

Q. La première heure, vraiment je ne corrige rien ? R. Vous pouvez corriger, mais limitez-vous à « une seule petite chose réversible ». Consacrer le reste du temps à la carte réduit les accidents et se révèle finalement plus rapide.

Q. Confier « tu peux tout lire » à Claude Code, c’est dangereux ? R. Lire seulement n’est pas dangereux. Ce qui est risqué, c’est le droit d’écrire. Lecture large, écriture étroite : c’est le découpage de base.

Q. Que faire pour un projet dont j’ignore la commande de preuve ? R. On fait d’abord proposer des candidats à Claude Code depuis package.json ou le README. Si ça reste flou, on se contente comme preuve minimale de vérifier qu’aucun diff n’apparaît avec git status.

Q. Peut-on faire la même chose avec PowerShell ? R. Oui. La logique qui compte le résultat de git diff --name-only et le compare à un plafond s’écrit aussi telle quelle en PowerShell. Réécrivez le script de vérification selon votre environnement.

Q. Cette procédure tient-elle même pour un débutant ? R. Oui. C’est même pour les débutants qu’elle est la plus utile. Sans comprendre le code à fond, fixer d’abord « les endroits où l’on peut toucher » évite les gros accidents. Si vous voulez d’abord poser les bases, le guide de démarrage facilitera la suite.

Ce que j’ai constaté en l’essayant

Cette procédure, je me la suis fabriquée après l’accident du début. Ce qui a le mieux marché à l’essai, c’est d’avoir mis dans le script de vérification le « plafond de fichiers modifiés » et le « contrôle automatique des zones protégées ».

En pratique, sur le dépôt hérité, après trois passages, une fois le nombre de fichiers modifiés a dépassé le plafond et le script s’est arrêté. En regardant de près, Claude Code avait, au passage d’un correctif de texte, réécrit jusqu’à un composant partagé. Si je l’avais laissé passer, j’aurais eu un diff dont l’impact était impossible à cerner. Grâce à l’arrêt, j’ai pu découper le correctif en deux et les proposer séparément.

Pas « je confie à une IA intelligente, donc tout ira bien », mais « je confie dans un périmètre où, même en tombant, je peux revenir en arrière ». Rien qu’en dessinant la carte d’abord, la sensation de cette première heure a complètement changé. Si une personne non technicienne veut partager ce découpage au sein d’une équipe, l’entrée pour les non-techniciens sera utile aussi.

L’usage officiel de Claude Code se vérifie également dans la documentation officielle d’Anthropic. Pour ceux qui veulent figer leurs propres règles d’exploitation et les rendre reproductibles en équipe, je cartographie un dépôt concret avec vous lors d’un accompagnement.