Claude Code sur un dépôt existant : sécuriser la toute première modification

Sur un dépôt interne que je venais tout juste de reprendre, j’ai fait un beau dégât dès le premier jour.

J’ai demandé à Claude Code « lis tout le projet et corrige ce qui te semble bancal ». Trente minutes plus tard, 23 fichiers étaient modifiés. Le contenu n’était pas mauvais en soi. Mais la configuration de déploiement en production et les fichiers liés au paiement, que personne n’avait le droit de toucher, avaient été « rangés au passage ». Le diff était si gros que moi-même je ne savais plus distinguer les changements vraiment nécessaires. J’ai fini par tout jeter et recommencer.

Quand une IA pourtant intelligente provoque un accident, ce n’est pas une question de capacité. C’est juste que personne n’avait décidé, avant de la lancer, jusqu’où elle avait le droit d’aller. Aujourd’hui, on reconstruit ce premier jour pour qu’il soit réversible, vérifiable et qu’il aille jusqu’au bout.

Points clés

• Le jour où vous entrez pour la première fois dans le code d’un autre, commencez par résumer sur une seule page : « les endroits lisibles, les endroits interdits, et la commande de vérification à lancer une fois fini ».
• Ne confiez pas une grosse refonte à Claude Code dès le départ. Partez d’une petite modification réversible (renommer un test, ajouter un commentaire).
• Avant tout rapport « c’est fait », lancez toujours une commande de vérification et conservez son résultat.
• Suppression, base de production, facturation, force push : le premier jour, tout reste figé sur « validation humaine ». On automatise plus tard, uniquement ce qui s’est révélé sûr.
• Dès que le diff commence à gonfler, avant de retoucher la consigne, réduisez d’abord le nombre de fichiers accessibles.

Pourquoi décider du périmètre dès le premier jour

Un nouveau dépôt, c’est une ville sans plan. Quel fichier est le cœur du réacteur, lequel casse tout si on le touche : au début, personne ne le voit.

Si vous demandez là « regarde tout et corrige », l’IA, par gentillesse, met les mains partout. Ce n’est pas la faute de l’IA. La cause est du côté de l’humain qui ne lui a pas donné de périmètre. Si vous dites à un nouveau stagiaire « occupe-toi du magasin, fais au mieux » et qu’il finit par changer les réglages de la caisse, le problème vient de celui qui a donné la consigne, non ?

La première chose à faire n’est donc pas d’écrire un prompt malin, mais de dessiner un plan. Les rayons qu’on peut consulter, les tiroirs qu’on n’ouvre pas, et la fermeture à vérifier avant de partir. Rien que mettre ces trois points sur papier fait quasiment disparaître les accidents du premier jour.

Les trois frontières à fixer en premier

L’ordre compte. On les verrouille de haut en bas.

À décider	Exemple concret	Pourquoi décider en premier
Endroits lisibles	src/, docs/, fichiers de test	Tout faire lire pousse à proposer des changements hors sujet
Endroits interdits	.env, paiement, authentification, migrations de base, config de déploiement prod	Casser ça est irrattrapable
Vérification finale	npm run build, un seul test	Pour laisser à chaque fois une « preuve que ça marche »

Ces trois points écrits (même en simple texte), je les pose dans un fichier ONBOARDING.md à la racine du dossier de travail. C’est aussi le premier fichier que je fais lire à Claude Code. On partage le plan, puis on laisse marcher dans la ville. Dans cet ordre.

Ce qu’on délègue à l’IA, et ce que l’humain décide

Mélanger les deux, c’est l’accident assuré. Traçons la ligne clairement.

Ce qu’on peut confier à Claude Code

• Survoler tout le dépôt et résumer sa structure.
• Chercher « dans quel fichier se trouve telle fonctionnalité ».
• Rédiger le brouillon de petites améliorations réversibles : renommer des tests, ajouter des commentaires, compléter des types.
• Exécuter la commande de vérification, lire le journal d’échec et avancer une hypothèse sur la cause.

Ce que l’humain doit toujours décider

• Autoriser ou non un changement qui entre dans une zone interdite.
• Supprimer un fichier, agir sur la base de production, toucher à la facturation, faire un force push.
• La décision finale de fusionner ou non un gros changement d’architecture.
• Arrêter ou non quand le diff s’étend au-delà du prévu.

Mon critère est simple. Ce qui « se rattrape avec git même en cas d’erreur », je le confie à l’IA. Ce qui « ne se rattrape pas », c’est l’humain qui appuie sur le bouton. Tant qu’on tient cette seule ligne, rien ne s’effondre dès le premier jour.

Modèle de prompt prêt à copier-coller

Avant d’entrer dans la première modification, voici ce que j’envoie. L’astuce : ne pas le laisser écrire tout de suite, mais lui faire d’abord renvoyer un plan.

C'est un dépôt existant que je touche pour la première fois. Respecte ces règles.

[Lecture autorisée] uniquement src/, docs/ et les fichiers de test
[Interdit] .env / authentification / paiement / migrations de base / config de déploiement prod
[Objectif du jour] une seule petite amélioration réversible (ex : renommer un test)
[Vérification] après la modification, lance toujours `npm run build` et colle le résultat

Ne modifie pas encore le code.
Renvoie d'abord le plan « quel fichier corriger et comment »,
ainsi qu'une reformulation, avec tes propres mots, des règles ci-dessus.

Si le plan renvoyé reformule correctement mes contraintes, c’est validé. S’il cherche à élargir le périmètre, j’arrête sur-le-champ. Si le plan est bon, j’enchaîne : « alors fais exactement ça, et va jusqu’à l’exécution du build ».

Garder les frontières sous forme de code

Les règles sur papier, on les oublie. Je conserve donc aussi mon plan d’onboarding dans un format lisible par la machine. Le script ci-dessous fonctionne tel quel. Remplacez juste le contenu pour votre propre dépôt.

#!/usr/bin/env bash
# Regrouper le plan d'onboarding d'un depot existant dans un seul JSON
set -euo pipefail

cat > onboarding-plan.json <<'JSON'
{
  "goal": "Terminer en securite la toute premiere modification du depot",
  "readOnlyCommands": [
    "git status --short",
    "git ls-files | head -50",
    "grep -rn \"TODO\\|FIXME\" src | head -20"
  ],
  "protectedAreas": [".env", "billing", "auth", "db/migrations", "deploy/prod"],
  "firstTask": "Une petite amelioration reversible de doc ou de test",
  "proofCommand": "npm run build",
  "rollback": "git diff -- path/to/changed-file && git checkout -- path/to/changed-file"
}
JSON

echo "=== Plan d'onboarding ==="
cat onboarding-plan.json

echo ""
echo "=== Diff actuel (vide = rien de modifie) ==="
git status --short

Ce script n’a rien de spectaculaire. Sa valeur, c’est de fixer dans un fichier, avant d’attaquer le travail, les « zones interdites » et la « commande qui sert de preuve ». Il suffit de réécrire protectedAreas avec les endroits dangereux de votre dépôt pour avoir le plan du premier jour.

Préparer aussi une seule commande de vérification rassure. Sur un projet Node.js, ce contrôle minimal confirme mécaniquement « si rien n’est cassé ».

// check.mjs : script minimal qui verifie seulement que le build passe
import { execSync } from "node:child_process";

try {
  // Remplacez par la commande de verification de votre projet
  execSync("npm run build", { stdio: "inherit" });
  console.log("Verif OK : le build passe. Passez le diff en revue.");
} catch (e) {
  console.error("Verif KO : le build a echoue. On ne fusionne pas, on cherche la cause.");
  process.exit(1);
}

Si node check.mjs est au vert, le diff part en revue ; au rouge, on s’arrête. Rien que cette ligne fait disparaître l’accident classique : fusionner en se disant « ça devrait marcher ».

Trois cas concrets sur le terrain

Si une situation vous est proche, ne refaites pas la procédure : remplacez juste les noms par ceux de votre contexte.

1. Reprise d’un site de contenu Faites d’abord lire et cartographier l’emplacement des articles, le dossier d’images, la commande de build et les pages produit. La première modification : une seule « correction de lien cassé ». Si le build passe, vous l’envoyez en revue. La réécriture massive du texte, ce sera plus tard, une fois la sécurité établie.

2. Base de code d’un SaaS Notez explicitement authentification, facturation et migrations de base comme zones interdites. Limitez la première tâche à quelque chose comme « rendre plus claire la description d’un test », et avancez seulement après validation humaine. Relâcher ici, c’est laisser une « amélioration bienveillante » entrer dans la logique de paiement et se faire des frayeurs.

3. Vieux dépôt legacy « Modernise tout » est une phrase interdite. Le diff devient illisible. À la place, partez d’un petit pas vérifiable par le build : corriger une faute de frappe dans un nom de fonction, renommer un test. Une réussite, puis le pas suivant sur le même modèle.

Chaque exemple a un « point d’arrêt ». C’est parce qu’il y a un point d’arrêt que le travail ne s’étend pas à l’infini.

Exemples d’échecs et comment les corriger

Je l’avoue honnêtement : les premières fois, j’ai tout raté.

Demander sans écrire les zones interdites → un diff trop gros pour être relu, à jeter intégralement. La correction est simple : avant de peaufiner la consigne, réduisez les fichiers lisibles. Plus le périmètre est étroit, plus la marge de dérapage de l’IA l’est aussi.

Builder seulement une fois tous les changements terminés → impossible de savoir quelle modification a cassé quoi. Maintenant, je lance la vérification après chaque fichier corrigé. L’instant de la casse reste enregistré, la cause saute aux yeux.

Ne compter que sur mes propres yeux pour vérifier → un jour chargé, on rate forcément quelque chose. Ce que « la machine sait constater », confiez-le littéralement à la machine : le build passe ou non, le résultat des tests, les liens morts. Réservez l’œil humain aux seules décisions de conception que la machine ne peut pas capter. Mes revues de fin de soirée ont nettement diminué.

Si je laisse ces pièges dans l’article, c’est que les seuls exemples de réussite ne permettent pas au lecteur de repérer sa propre situation à risque. Noter brièvement quelle demande s’est trop élargie, quelle vérification a manqué, évite au « moi » suivant de retomber dans le même trou.

FAQ

Q. Quelle première modification choisir ? R. Choisissez « ce qui se rattrape avec git checkout même en cas d’erreur ». Renommer un test, ajouter un commentaire, corriger une coquille sont sûrs. Une nouvelle fonctionnalité ou un changement de config ne conviennent pas au premier jour.

Q. Jusqu’où détailler les zones interdites ? R. Seulement « les endroits irrattrapables si on les casse » suffit. .env, authentification, facturation, config de déploiement prod, migrations de base. Couvrir ces cinq dès le départ écarte presque tous les accidents fatals.

Q. Peut-on sauter l’étape où Claude Code renvoie un plan ? R. Je recommande de ne pas la sauter. Ce petit effort de reformulation permet de repérer un décalage de périmètre avant la modification. C’est bien moins coûteux que de s’en apercevoir une fois le code écrit.

Q. La commande de vérification, le build suffit-il ? R. Le premier jour, un seul build suffit. Une fois à l’aise, ajoutez un test pertinent. Vouloir lancer toute la suite dès le début est trop lourd pour tenir dans la durée. On commence petit, on augmente quand les journaux de succès se sont accumulés.

Q. Précautions pour un déploiement en équipe ? R. Écrire les frontières dans un fichier partagé comme ONBOARDING.md, pour que tout le monde utilise le même plan. Si les zones interdites varient selon les personnes, le critère de revue vacille aussi.

Articles liés

Pour les fondations, Claude Code pour les non-développeurs et le guide des premiers pas avec Claude Code sont de bons points de départ. La manière de faire mémoriser les règles du projet est détaillée dans les bonnes pratiques CLAUDE.md, et pour des consignes plus poussées, voyez la pratique de la conception de prompts. Pour les détails sur les permissions, consultez aussi la documentation officielle d’Anthropic.

Ce que j’ai constaté en pratique

Après l’« accident des 23 fichiers » du début, j’ai changé l’ordre de l’onboarding. J’ai arrêté de chercher le prompt malin et j’ai d’abord figé les zones interdites et la commande de vérification dans onboarding-plan.json. Rien que ça : zéro accident touchant au paiement ou à la config de production.

Le jour où j’ai limité la première modification à « renommer un test », le diff tenait en 8 lignes et le build est passé du premier coup. La revue n’a pas pris deux minutes. À l’inverse, un autre jour où j’ai demandé sans fixer de périmètre, le diff a regonflé et j’ai de nouveau tout jeté. La différence ne venait pas de l’intelligence du modèle, mais du fait d’avoir dessiné le plan avant d’entrer.

Si vous voulez ancrer cette méthode pour toucher au code d’autrui en sécurité, à partir d’exemples concrets de votre propre équipe, je construis avec vous une démarche d’adoption adaptée à votre métier dans la formation et le conseil. Commencez dès aujourd’hui : écrivez les cinq zones interdites de votre propre dépôt.