Confier sa première tâche à Claude Code : le brief en 9 points

« Ce dépôt, mets-moi un peu d’ordre dans le README, fais au mieux. »

Trente minutes après l’installation, c’est la première demande que j’ai lancée à Claude Code. Ce que j’ai récupéré : un diff censé toucher uniquement le README, mais qui avait aussi renommé des scripts dans package.json. Ça fonctionnait, certes, mais trois fichiers avaient changé ailleurs que là où je voulais. Je suis resté figé devant l’écran : « Bon, je peux publier ça ou pas ? »

Pourquoi un outil aussi intelligent que Claude Code va-t-il bricoler des endroits qu’on ne lui a pas demandé de toucher ? Ce n’est pas un problème de capacité. C’est juste que je n’avais pas dit un seul mot sur « jusqu’où il avait le droit d’aller ». C’est un peu comme dire à un nouveau venu « occupe-toi du magasin, fais au mieux » avant de partir, et retrouver tous les rayons réorganisés en rentrant.

Cet article parle justement de ce « jusqu’où », écrit sur une seule page. J’appelle ça le brief : le document de cadrage de la première tâche.

Points clés

• Si la première demande tourne mal, c’est parce qu’on dit « fais au mieux » sans avoir défini l’objectif, le périmètre autorisé, la vérification et le rollback.
• Le brief contient 9 points : objectif / état du lecteur / lecture autorisée / édition autorisée / exécution autorisée / interdits / vérification / rollback / prochaine étape.
• On confie à Claude Code « lire, corriger, lancer les commandes de vérification ». La suppression, la mise en production et tout ce qui facture restent des décisions humaines.
• Je fournis un modèle de brief prêt à copier-coller, plus un script JavaScript qui vérifie automatiquement qu’il ne manque rien.
• Le chemin le plus court vers une première réussite : choisir une seule petite tâche « réversible avec git même en cas d’échec ».

Pourquoi la première tâche part en vrille

Juste après avoir installé Claude Code, la plupart des gens lancent une « demande large ». « Range-moi le dépôt. » « Corrige le README. » Je comprends l’envie : on veut tester ce que l’outil sait faire.

Mais une demande large fait partir les dix premières minutes en exploration. Claude Code lit des fichiers un peu partout, corrige de son propre chef ce qui lui semble lié, et termine par un rapport flou du genre « ça devrait marcher ». De votre côté, vous devez relire tout le diff, et vous finissez par vous dire « j’aurais été plus rapide à le faire moi-même ».

La cause n’est pas l’intelligence du modèle. C’est qu’on ne lui a transmis ni objectif ni frontières. Même un nouveau collègue humain, à qui on dit le premier jour « fais comme tu veux », va soit se bloquer, soit déraper. Définir les frontières d’abord suffit à faire disparaître presque tous ces accidents.

Si vous n’êtes pas encore à l’aise avec les manipulations de base, passez d’abord par Bien démarrer avec Claude Code, puis revenez ici : tout ce qui concerne le brief rentrera beaucoup plus facilement.

Les 9 points à écrire dans le brief

Voici les 9 points que je couche sur une page à chaque fois. Pas besoin de jargon. Il suffit de remplir une réponse par ligne.

Point	Quoi écrire	Mauvais → Bon exemple
Objectif	À quoi ressemble le succès une fois fini	« Corriger le README » → « Aligner les étapes du README sur package.json »
État du lecteur	Pour qui est ce travail	(vide) → « Débutant, veut réussir une fois à coup sûr »
Lecture autorisée	Fichiers qu’il peut consulter	(tous) → « README.md et package.json uniquement »
Édition autorisée	Fichiers qu’il peut modifier	(tous) → « README.md uniquement »
Exécution autorisée	Commandes qu’il peut lancer	(n’importe quoi) → « npm run build uniquement »
Interdits	Ce qu’il ne doit jamais toucher	(non précisé) → « package-lock, config de déploiement, prix »
Vérification	La preuve du succès	« Si ça marche, c’est bon » → « build passe / diff limité au README »
Rollback	Comment revenir en arrière en cas d’échec	(rien) → « Restaurer le README depuis git »
Prochaine étape	Une seule chose vers laquelle orienter le lecteur	(en aligner 3) → « D’abord juste la ressource d’intro gratuite »

L’essentiel se joue sur « interdits », « vérification » et « rollback ». À l’instant où vous écrivez ces trois lignes, la demande passe du statut de « faveur » à celui de « travail qu’on peut déléguer en toute sécurité ».

Un modèle de brief à copier-coller

Voici un canevas utilisable tel quel. Je le mets dans un bloc de code pour que vous puissiez le coller directement dans Claude Code. Remplacez le nom de votre dépôt et l’endroit à corriger.

# Brief de la première tâche

Objectif : aligner les étapes d'installation du README sur le contenu de package.json.
État du lecteur : débutant. Veut réussir une fois à coup sûr.
Lecture autorisée :
- README.md
- package.json
Édition autorisée :
- README.md uniquement
Exécution autorisée :
- npm run build
Interdits :
- package-lock.json
- config de déploiement (variables d'environnement, paramètres de publication)
- prix et liens d'inscription
Vérification :
- npm run build passe
- git diff ne montre que des changements dans README.md
Rollback :
- si la vérification échoue, restaurer README.md depuis git
Prochaine étape :
- orienter d'abord uniquement vers la ressource d'intro gratuite

Concrètement : s’il s’agit juste d’aligner les étapes du README sur package.json, on lit le README et package.json, on n’édite que le README, et la preuve, c’est npm run build. À ce niveau de finesse, même en cas d’échec, un seul git checkout -- README.md suffit à revenir en arrière. La toute première fois, autant rester aussi étroit. Plus c’est étroit, plus c’est vous qui pouvez juger si ça a réussi ou non.

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

Quand j’écris un brief, je trace mentalement cette ligne. Si la frontière reste floue, Claude Code la franchit « pour bien faire ».

À confier à Claude Code	Décision humaine (à ne pas automatiser)
Lire les fichiers indiqués	Décider quels fichiers il a le droit de toucher
Corriger uniquement les fichiers indiqués	Supprimer des fichiers
Lancer des commandes de vérification comme npm run build	Mettre en production / déployer
Renvoyer un résumé du diff	Toute opération qui facture
Rapporter la cause d’un échec	Toute opération irréversible comme git push --force

La colonne de gauche, on délègue. La colonne de droite, on garde tout en mode « demander à un humain avant d’exécuter », au début. On ne déplace une opération vers l’automatique que petit à petit, une fois qu’on l’a jugée sûre. Rien que respecter cet ordre fait chuter drastiquement le nombre de sueurs froides en pleine nuit.

Au moment de transmettre la demande, j’ajoute cette consigne :

Exécute une seule petite tâche, en restant strictement dans le périmètre de ce brief.
Pour tout ce que tu juges hors périmètre, ne l'exécute pas : propose-le seulement.

Renvoie d'abord ces 5 éléments :
1. les fichiers que tu vas lire
2. les fichiers que tu vas modifier
3. les commandes de vérification à lancer avant et après
4. un résumé du diff
5. la manière de revenir en arrière en cas d'échec

Le point clé, c’est de demander « renvoie-moi le plan et la vérification avant d’implémenter ». Si le plan renvoyé dépasse le périmètre du brief, vous l’arrêtez sur le champ. Arrêter avant que la machine ne touche au code, c’est zéro nettoyage derrière.

Du code pour vérifier automatiquement un brief incomplet

Même quand on croit avoir écrit un brief complet, il manque souvent un point. Moi, je vérifie la présence de chaque champ par la machine. C’est du JavaScript qui marche en copier-coller. On le lance avec Node.js, par exemple node check-brief.mjs.

// Vérifie machinalement que le brief contient tous les champs requis
const requiredFields = [
  "Objectif",
  "Lecture autorisée",
  "Édition autorisée",
  "Exécution autorisée",
  "Interdits",
  "Vérification",
  "Rollback",
  "Prochaine étape",
];

export function validateFirstTaskBrief(markdown) {
  // Repère les champs absents
  const missing = requiredFields.filter((field) => !markdown.includes(field));

  // Vérifie aussi qu'une commande de preuve (ici npm run build) est bien présente
  const hasProofCommand = markdown.includes("npm run build");

  return {
    ok: missing.length === 0,
    missing,
    readyForClaudeCode: missing.length === 0 && hasProofCommand,
  };
}

// Exemple de vérification
const sample = `
Objectif : aligner le README sur package.json
Lecture autorisée : README.md
Édition autorisée : README.md
Exécution autorisée : npm run build
Interdits : package-lock.json
Vérification : npm run build passe
Rollback : restaurer README.md depuis git
Prochaine étape : ressource d'intro gratuite
`;

const result = validateFirstTaskBrief(sample);
console.log(result);
// → { ok: true, missing: [], readyForClaudeCode: true }

Une fois qu’on passe le brief dans ce contrôle avant de le transmettre, les oublis sur « interdits » et « rollback » disparaissent. Quand on s’en remet aux seuls yeux humains, il manque forcément quelque chose les jours chargés. Ce que la machine sait vérifier, autant le lui laisser : c’est plus reposant.

Trois situations où ça fait la différence

1. Corriger un README ou un guide de procédure « Mets la doc à jour » a un périmètre infini. En resserrant à « uniquement le chapitre d’installation du README, aligné sur les noms de scripts de package.json », le diff tient sur un seul fichier et se vérifie avec npm run build. C’est la tâche idéale pour un tout premier essai.

2. La première relecture d’une pull request Pas « regarde cette PR », mais « parmi les fichiers modifiés, lis uniquement ceux sous src/ et signale les endroits où les tests risquent de casser. Ne corrige pas le code, signale seulement ». On délègue la lecture, on garde la décision de corriger côté humain. Ça évite l’accident classique du « il corrige de lui-même et introduit un autre bug ».

3. Remplacer un CTA (le lien vers la prochaine étape du lecteur) Même pour remplacer un seul bouton sous un article populaire, « trouve le composant concerné et corrige-le » est trop large. On fixe d’abord dans le brief « les fichiers qu’on peut toucher », « l’URL publique à vérifier » et « le lien à remplacer ». La vérification après coup passe alors de « ça a l’air pas mal » à « avec cette preuve-là, je peux publier ».

Trois bourdes que j’ai personnellement commises

Je joue franc-jeu. Avant d’utiliser un brief, je répétais les mêmes erreurs.

La première : ne pas avoir écrit « interdits ». Je voulais juste corriger le README, mais Claude Code a aussi « rangé » package.json par gentillesse, et le build a cessé de passer. Il a suffi d’ajouter trois lignes Interdits : package-lock.json, config de déploiement pour que ça ne se reproduise plus jamais.

La deuxième : m’être contenté de « si ça marche, c’est bon » pour la vérification. Comme je n’avais pas défini ce que voulait dire « ça marche », je devais suivre tout le diff à l’œil à chaque fois. En passant à une commande concrète, Vérification : npm run build passe / diff limité au README, le contrôle est tombé à dix secondes.

La troisième : avoir aligné trois prochaines étapes. En collant en bas d’article à la fois la ressource, le support de cours et le rendez-vous, la réaction des lecteurs est devenue floue. En resserrant à une seule, adaptée à l’état du lecteur, cette unique option finit par être réellement cliquée. Ce qu’il faut écrire, je le consigne comme règle de projet dans Comment écrire un CLAUDE.md ; ainsi je ne dévie plus à chaque fois.

FAQ

Q. Écrire les 9 points à chaque fois, c’est pénible, non ? Seulement les premières fois. Faites-vous un modèle, rangez-le sous first-task-brief.md, et ensuite il suffira de remplacer 3 ou 4 lignes. Le temps d’écriture est bien plus court que le temps passé à relire un diff parti en vrille.

Q. Un brief est-il nécessaire même pour une tâche simple ? Pour un « corriger une coquille dans un fichier », une demande orale suffit. Le brief est utile pour les tâches qui risquent de toucher plusieurs fichiers, ou qui frôlent la production, la facturation, la suppression. Dans le doute, écrivez-le : vous n’y perdez rien.

Q. Faut-il écrire avec des clés en anglais (Goal, May edit, etc.) ? Si vous comparez des logs en équipe, des clés en anglais alignées sont pratiques ; en solo, le français suffit largement. Claude Code comprend les deux. Ce qui compte, ce n’est pas la langue, c’est qu’aucun champ ne manque.

Q. Est-ce utilisable même sans faire de programmation ? Oui. Pour la rédaction d’articles ou l’organisation de documents, la logique « lecture autorisée / édition autorisée / interdits » reste la même. La porte d’entrée pour les non-techniciens est rassemblée dans Claude Code pour les non-développeurs.

Q. Et si Claude Code ignore le brief et touche au hors-périmètre ? D’abord, demandez « renvoie le plan et la vérification en premier » et arrêtez-le avant qu’il ne touche au code. S’il déborde quand même, c’est probablement que vos « interdits » manquent de précision. Indiquer les noms de dossiers et de fichiers règle souvent le problème.

Ce que j’ai constaté en l’essayant vraiment

L’exemple le plus parlant a été d’essayer ce brief sur la petite tâche d’alignement du README sur package.json. En écrivant d’avance Édition autorisée : README.md uniquement, la tendance de Claude Code à tendre la main vers package-lock ou les fichiers de config s’est arrêtée dès l’étape du plan, avant exécution. Le gros gain : la corvée de relecture du diff a simplement disparu.

Mettre les deux preuves npm run build et git diff dans la Vérification a aussi payé. Le jugement après coup est passé de « à l’ambiance, ça semble bon » à une affirmation nette : « build vert, diff limité au README, donc je peux publier ». À l’inverse, les fois où j’ai laissé Prochaine étape vide, je me retrouvais moi-même à hésiter sur « bon, qu’est-ce que j’oriente ensuite ? », et le lien de fin d’article devenait flou.

Au final, ce que j’ai compris : la valeur n’est pas de donner une grande liberté à Claude Code. Découper la première tâche tout petit, et garder le succès, l’échec et la prochaine action visibles à l’œil nu. C’est ce qui va le plus vite. La corvée d’écrire une page de frontières n’est rien à côté de la corvée de relire ensuite un diff parti en vrille.

Pour pousser plus loin le cadre extérieur, consultez la documentation officielle de Claude Code d’Anthropic pour comprendre le comportement des réglages d’autorisation : la répartition des rôles entre le brief et la configuration devient alors limpide. Si vous voulez intégrer Claude Code dans l’activité d’une entreprise et mettre en place les règles d’usage qui vont avec, on peut avancer ensemble dès la conception des briefs adaptés à vos tâches réelles via formation et conseil.