Faire modifier un seul fichier à Claude Code : le brief qui évite les dégâts

« L’intro de cet article de blog, améliore-la un peu, s’il te plaît. »

J’ai tapé ça un vendredi soir, à 22 heures. Je voulais juste corriger les trois premiers paragraphes d’un seul fichier. Le lendemain matin, j’ouvre le diff : douze fichiers avaient changé. Pas seulement le corps de l’article, mais aussi la mise en page commune, la liste des tags, et même, allez savoir pourquoi, le fichier de configuration de publication. Sans avoir vérifié que quoi que ce soit fonctionnait encore, je m’étais endormi.

Il m’a fallu trente minutes pour tout remettre en place. Où était l’erreur ? Claude Code n’a pas été mauvais. C’est que ma demande ne précisait nulle part jusqu’où il avait le droit de toucher. Une IA douée a simplement voulu bien faire : « améliorer l’intro, ça veut sûrement dire ranger aussi tout ce qui gravite autour. »

Dans cet article, je vous donne, copiable tel quel, le « brief pour faire modifier un seul fichier sans danger » que j’ai construit à partir de ce vendredi soir. Définir un périmètre étroit, faire vérifier le travail à la fin, et pouvoir revenir en arrière si c’est faux. Rien de plus. Et les accidents nocturnes ont presque disparu.

Points clés

• Quand une tâche déléguée à l’IA part en vrille, ce n’est pas le modèle qui est en cause, c’est que le périmètre autorisé n’a pas été écrit.
• Le brief doit toujours contenir cinq points : les fichiers à lire, les fichiers à modifier, ce qu’il ne faut pas toucher, la commande de vérification et la procédure de retour arrière.
• Faire lancer une commande de vérification avant tout rapport de réussite évite que l’humain se retrouve, après coup, à jouer le testeur.
• Commencez par de petites tâches au point d’arrêt clair : retoucher un article, mettre au propre un rapport de bug, réécrire un texte produit.
• Restreindre le périmètre ne diminue pas la valeur du résultat. Au contraire, le lecteur transpose plus facilement à son propre contexte.

Pourquoi « améliore ça » finit en accident

Une demande comme « améliore ça » n’a pas de ligne d’arrivée.

Un relecteur humain, sollicité un vendredi soir chargé, demanderait : « Juste les trois paragraphes de l’intro, c’est ça ? » L’IA, elle, peut partir sans poser la question. Et comme elle excelle à anticiper vos besoins, elle élargit toute seule le périmètre : « Si on améliore l’intro, autant ranger les tags et ajouter quelques liens connexes, ce sera plus utile. » Aucune mauvaise intention. C’est précisément ce qui rend la chose pénible.

Ce qui marche ici, c’est l’idée d’écrire un point d’arrêt dans la consigne elle-même. Pas besoin d’un prompt long et travaillé. Plus c’est court, mieux c’est. À la place, séparez clairement, dès le départ, les fichiers autorisés et les fichiers interdits. Cela suffit à stopper la dérive.

Si vous voulez creuser l’écriture des prompts elle-même, lisez aussi la conception de prompts pour Claude Code : vous verrez comment ce « restreindre le périmètre » s’articule avec les autres techniques.

Les cinq points obligatoires du brief

Le brief que j’utilise aujourd’hui contient toujours ces cinq éléments. Et leur ordre a un sens.

Élément	Contenu	Ce qui arrive sans lui
Fichiers à lire	Le périmètre lisible pour comprendre la situation	Il lit des endroits hors sujet et fait des corrections à côté
Fichiers à modifier	Le ou les un à deux fichiers réellement modifiables	L’accident des douze fichiers
À ne pas toucher	Config, fichiers générés, secrets, réglages de publication	Un fichier qu’il ne fallait surtout pas supprimer se fait « ranger »
Commande de vérification	La commande unique à lancer après modification	Il annonce « c’est fait » alors que tout est cassé
Retour arrière	La procédure pour revenir à l’état initial en cas d’erreur	Trente minutes de récupération

Le point essentiel : faites-lui renvoyer un « plan » une première fois, avant de commencer à modifier. Ne le laissez pas écrire d’emblée. Faites-lui d’abord énoncer « quels fichiers je lis, lequel je change, et si je me trompe ce qui casse ». Si le plan revient à côté de la plaque, vous l’arrêtez à ce moment-là. C’est bien moins cher que de s’en apercevoir une fois la modification écrite.

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

Pas besoin de tout confier à l’IA. Voici où je trace la ligne.

Ce qu’on peut déléguer à l’IA

• Lire les fichiers pour comprendre la situation
• Établir le plan de modification et le mettre en mots
• Écrire le texte ou le code lui-même
• Lancer la commande de vérification et rapporter le résultat

Ce que l’humain garde en main

• Quels fichiers entrent dans le périmètre de modification (décision du périmètre)
• Appuyer sur le bouton de publication ou de mise en production
• Décider de toucher à un fichier de config ou à des secrets
• Décider de bloquer la publication quand la vérification échoue

Cette frontière compte d’autant plus que vous débutez dans la délégation à l’IA. La façon de répartir « périmètre délégué » et « décisions humaines » est aussi un principe de base dans Claude Code pour les non-développeurs. Tant que vous n’êtes pas à l’aise, une règle grossière suffit : « lire et écrire pour l’IA, supprimer et publier pour l’humain ».

Le modèle de brief, copiable tel quel

Collez-le, et remplacez seulement les noms de fichiers par les vôtres. En PowerShell comme en bash, il s’agit juste de mettre le texte dans une variable et de l’afficher pour vérifier.

brief=$(cat <<'EOF'
Objectif : effectuer une seule modification sûre, à un seul endroit.
Fichiers modifiables : site/src/content/blog/example.mdx
À ne pas toucher : fichiers de packages, fichiers générés, secrets,
réglages de publication et de déploiement.

Avant de commencer la modification, renvoie :
1. Les fichiers que tu vas lire pour comprendre la situation
2. L'unique fichier que tu vas réellement modifier
3. Ce qui casse si cette modification est fausse
4. La commande de vérification à lancer après la modification

Une fois la modification terminée, renvoie :
- Un résumé du diff
- Le résultat de la commande de vérification
- La procédure de retour arrière
EOF
)

echo "$brief"

Ce texte n’a rien de spectaculaire. Sa valeur, c’est de mettre la frontière par écrit avant de commencer le travail. Réécrivez les noms de fichiers, ce qu’il ne faut pas toucher et la commande de vérification pour votre dépôt, puis passez le tout à Claude Code. Quand un bon plan revient, faites-lui réénoncer les mêmes contraintes avant de le laisser travailler.

Si vous inscrivez ces mêmes contraintes dans le CLAUDE.md, elles s’appliquent automatiquement sans avoir à les coller à chaque fois. La méthode est résumée dans les bonnes pratiques du CLAUDE.md.

Un petit script pour faire vérifier le travail à la fin

Ne pas croire le « c’est fait » sur parole. C’est le deuxième pilier.

Une fois la modification terminée, on contrôle mécaniquement qu’un seul fichier a réellement changé. Le script ci-dessous se contente de compter les fichiers modifiés non commités et de s’arrêter s’il y en a plus que prévu. Il fonctionne tel quel, commentaires en français inclus.

#!/usr/bin/env bash
# Vérifie qu'un seul fichier a été modifié. S'arrête s'il y en a trop.
set -e

# Nombre de fichiers modifiés attendu (1 pour une édition d'un seul fichier)
expected=1

# Compte les fichiers modifiés non commités
changed=$(git status --porcelain | grep -c .)

echo "Nombre de fichiers modifiés : $changed (attendu : $expected)"

if [ "$changed" -gt "$expected" ]; then
  echo "Plus de fichiers que prévu ont changé. Vérifie le diff."
  git status --porcelain
  exit 1
fi

echo "Conforme au périmètre."

Si vous désignez ce script comme « commande de vérification » dans le brief, l’IA le lance d’elle-même et rapporte le résultat. S’il y a douze fichiers modifiés, le texte rouge apparaît dès le moment du rapport. Au lieu de m’en apercevoir au réveil, ça s’arrête sur place. Et ça, ça change tout.

Si vous voulez automatiser davantage la vérification et l’organisation au quotidien, les techniques de productivité avec Claude Code rassemblent d’autres schémas du même genre.

Trois situations où ça marche

Ce sont toutes des tâches au « point d’arrêt » net. Autrement dit, si vous ne voyez pas le point d’arrêt, c’est un signe qu’il vaut mieux ne pas encore tout confier à l’IA.

1. Réécrire l’intro d’un article de blog Écrivez d’emblée : on ne modifie que l’intro d’un seul fichier. Ajoutez le lecteur cible et la commande de vérification. Ainsi, les mains ne se tendent plus vers le corps entier ni vers la mise en page. Mon accident des douze fichiers n’aurait pas eu lieu avec cette simple ligne.

2. Mettre au propre un rapport de bug Montrez seulement le fichier de log et un modèle, et écrivez : « interdiction de ranger du code sans rapport ». Si une refactorisation s’invite pendant qu’on remet au propre le rapport, la revue devient soudain bien plus lourde. En restreignant ce que vous montrez, vous restreignez la sortie.

3. Tester un texte de page produit Plutôt qu’une refonte complète de la page, demandez seulement « une proposition d’accroche » et « le contrôle du rendu après modification ». Comme le périmètre est figé sur une proposition, la comparaison reste simple quand vous testez en A/B.

FAQ

Q. Coller ce long brief à chaque fois, n’est-ce pas pénible ? Les contraintes fréquentes, inscrivez-les dans le CLAUDE.md : elles s’appliquent sans avoir à les recoller. Il ne vous reste qu’à indiquer « les noms de fichiers autorisés cette fois-ci ».

Q. Restreindre le périmètre ne tue-t-il pas le talent de l’IA ? C’était l’inverse. Plus le périmètre est étroit, plus l’IA corrige en profondeur, sans hésiter. Une consigne large ne fait que l’embrouiller sur « par où commencer ».

Q. Que mettre comme commande de vérification ? Au début, le seul « contrôle du nombre de fichiers modifiés » suffit. En prenant de l’assurance, vous ajoutez une commande à la fois : le build passe-t-il, les tests tiennent-ils, n’y a-t-il pas de lien cassé.

Q. Et si malgré tout un fichier imprévu a changé ? Si la procédure de retour arrière figure dans le brief, il suffit de l’appliquer. L’astuce : inscrire dès le départ la commande de retour, comme git restore ., dans la consigne.

Q. Par où commencer ? Choisissez une petite tâche réversible même en cas d’échec. Retoucher un brouillon d’article ou remplacer un texte est tout indiqué. Si les opérations de base vous inquiètent, partir du guide de démarrage de Claude Code prépare bien le terrain.

Ce que j’ai constaté en l’essayant

Après cet accident des douze fichiers, je rédige systématiquement mes briefs avec « fichiers à modifier », « à ne pas toucher » et « commande de vérification ».

Depuis que je désigne le script de vérification comme « commande de vérification », les cas où un fichier imprévu se glisse s’arrêtent sur place. La semaine dernière encore, en faisant corriger un texte de page produit, l’IA a commencé à étendre la main jusqu’à un composant commun ; mais dès que le nombre de fichiers modifiés est passé à deux, le script a affiché du rouge et s’est arrêté. Fini le réveil livide devant un diff incompréhensible.

L’autre chose que j’ai vérifiée : restreindre le périmètre ne fait pas baisser la qualité de la sortie. Les jours où je me limitais aux « trois paragraphes de l’intro », les corrections revenaient même plus justes. Plutôt que de déléguer large à une IA brillante, demander étroit et faire vérifier soi-même. Ça semble être un détour, mais c’est, pour moi, le chemin le plus rapide. C’est ma conclusion du moment.

Si vous voulez, en entreprise, mettre en place un dispositif pour déléguer l’édition et l’exploitation à l’IA, la formation et le conseil d’intégration permettent de construire ensemble, à partir des étapes concrètes. Mais d’abord, chez vous, essayez une fois un brief « un seul fichier ».

Pour référence, l’information officielle sur l’outil utilisé ici se trouve dans la documentation officielle de Claude Code.