Le brief en 7 blocs qui empêche Claude Code de partir dans tous les sens

Vous demandez à Claude Code d’ajouter un formulaire à votre site.

Il installe une bibliothèque, crée plusieurs composants, modifie le style global et remplace une partie de votre structure. Le formulaire apparaît, mais une autre page ne fonctionne plus et vous ne savez pas exactement pourquoi.

Claude a travaillé vite. Il a aussi pris des décisions que vous ne lui aviez pas données.

Le réflexe consiste souvent à écrire un prompt encore plus long, avec toutes les précisions imaginables. On obtient alors un bloc de texte difficile à relire, où l’objectif principal se perd au milieu des détails.

Le bon brief n’est ni une phrase vague ni un roman. C’est un contrat de travail lisible qui sépare le contexte, le résultat, les contraintes et la vérification.

Ce qu’il faut retenir

• Une IA improvise surtout dans les espaces que votre brief laisse vides.
• Le résultat attendu et les critères de réussite doivent être décrits avant la solution technique.
• Les contraintes servent à protéger ce qui fonctionne déjà et à limiter les changements inutiles.
• Demandez un plan avant l’exécution lorsque la tâche touche plusieurs fichiers ou comporte un risque.
• Une livraison n’est terminée que lorsqu’elle est testée et expliquée.

Pourquoi « fais-moi cette fonctionnalité » ne suffit pas

Vous connaissez votre projet depuis plusieurs semaines. Claude n’en voit qu’une partie : les fichiers accessibles, votre message actuel et éventuellement la documentation que vous avez préparée.

Lorsque vous écrivez « ajoute une connexion utilisateur », de nombreuses questions restent ouvertes :

• qui peut créer un compte ?
• quelles données sont collectées ?
• quel service gère l’authentification ?
• quelles pages deviennent privées ?
• que se passe-t-il après une erreur ?
• quels composants doivent rester inchangés ?
• comment vérifier que la connexion fonctionne ?

Si vous ne répondez pas, l’IA doit choisir. Elle peut choisir une solution techniquement cohérente, mais incompatible avec votre produit, votre sécurité ou votre niveau de maintenance.

Le brief réduit cette zone d’improvisation.

Les sept blocs du brief

Bloc 1 — Le contexte

Expliquez l’environnement dans lequel la tâche s’inscrit.

Incluez seulement ce qui influence le travail :

• le type de produit et son utilisateur ;
• l’état actuel de la fonctionnalité ;
• les technologies déjà en place ;
• les décisions architecturales permanentes ;
• le problème observé.

Exemple :

Il s’agit d’une landing page pour des consultants indépendants. Le projet utilise Next.js et les composants existants du dossier components. Les demandes de diagnostic sont actuellement envoyées par un formulaire simple. Sur mobile, l’utilisateur ne reçoit aucun retour visible après l’envoi.

Le contexte répond à « où sommes-nous ? » et non à « que faut-il faire ? ».

Bloc 2 — L’objectif

Décrivez le changement attendu du point de vue de l’utilisateur.

Après l’envoi du formulaire sur mobile, l’utilisateur doit comprendre immédiatement si sa demande a été reçue et savoir ce qui se passera ensuite.

Un objectif n’est pas une liste de fichiers à modifier. Il définit le résultat avant le moyen.

Utilisez un seul objectif principal. Si votre demande contient « et aussi », vous avez peut-être plusieurs tâches à séparer.

Bloc 3 — Le périmètre

Indiquez ce qui fait partie de la tâche et ce qui n’en fait pas partie.

Dans le périmètre :

• état de chargement ;
• confirmation de réussite ;
• message d’erreur ;
• comportement sur mobile.

Hors périmètre :

• changement du prestataire d’envoi ;
• refonte visuelle du formulaire ;
• ajout d’un compte utilisateur ;
• modification des autres pages.

Le hors-périmètre protège votre projet contre l’enthousiasme d’une solution trop large.

Bloc 4 — Les contraintes et garde-fous

Précisez ce qui doit rester vrai pendant et après la modification :

• réutiliser les composants existants ;
• ne pas ajouter de dépendance sans justification ;
• ne pas modifier le schéma de données ;
• préserver l’accessibilité au clavier ;
• ne jamais exposer une clé dans le navigateur ;
• ne pas inventer de texte légal ou de données.

Une contrainte n’est utile que si elle peut guider une décision. « Fais quelque chose de moderne » reste subjectif. « Réutilise la palette, les espacements et les composants existants » est vérifiable.

Bloc 5 — Les entrées et références

Donnez les matériaux fiables :

• fichiers à consulter ;
• exemple de comportement attendu ;
• capture ou maquette ;
• données fictives pour le test ;
• documentation officielle pertinente ;
• bon et mauvais exemple.

Indiquez la fonction de chaque référence. Une capture peut servir à copier une disposition sans copier son texte. Un exemple de code peut illustrer une convention sans être la solution complète.

Ne partagez pas de secrets, de données clients ou de clés API dans le brief.

Bloc 6 — La méthode de travail

Pour une modification risquée, imposez une séquence :

1. inspecter les fichiers concernés ;
2. résumer l’état actuel ;
3. lister les hypothèses et questions bloquantes ;
4. proposer un plan court ;
5. attendre votre validation si le choix est structurant ;
6. modifier par étapes limitées ;
7. tester après chaque étape.

Vous séparez ainsi l’IA qui analyse de l’IA qui exécute.

Pour une petite correction locale et réversible, cette validation intermédiaire n’est pas toujours nécessaire. Adaptez le niveau de contrôle au risque.

Bloc 7 — Les critères de réussite et la livraison

Décrivez comment vous saurez que la tâche est terminée.

Exemple :

• sur mobile, le bouton indique l’envoi en cours ;
• un double clic ne crée pas deux demandes ;
• une réussite affiche le prochain délai de réponse ;
• une erreur conserve les données saisies ;
• le formulaire reste utilisable au clavier ;
• les tests existants continuent de passer.

Demandez enfin une livraison structurée : fichiers modifiés, décisions prises, tests exécutés, limites et vérifications manuelles restantes.

Le modèle complet à copier

# 1. CONTEXTE
Produit et utilisateur : {{contexte}}
État actuel : {{état}}
Problème observé : {{problème}}
Technologies et conventions : {{stack_et_règles}}

# 2. OBJECTIF
À la fin, {{utilisateur}} doit pouvoir {{résultat_observable}}.

# 3. PÉRIMÈTRE
Inclus :
- {{élément}}

Exclus :
- {{élément}}

# 4. CONTRAINTES ET GARDE-FOUS
- {{ce_qui_doit_rester_inchangé}}
- {{interdiction}}
- {{exigence_sécurité_accessibilité}}

# 5. ENTRÉES ET RÉFÉRENCES
- {{fichier_ou_exemple}} : sert à {{rôle}}

# 6. MÉTHODE DE TRAVAIL
Avant de modifier : inspecte l’existant, liste les hypothèses et propose un plan.
Arrête-toi si une décision structurante ou une information sensible manque.
Effectue ensuite des changements limités et vérifiables.

# 7. CRITÈRES DE RÉUSSITE ET LIVRAISON
La tâche est réussie si :
- {{critère_testable}}

À la fin, fournis :
- les fichiers modifiés ;
- les décisions et hypothèses ;
- les tests exécutés et leurs résultats ;
- les limites ou contrôles manuels restants.

Ce modèle n’a pas vocation à être rempli avec cinquante lignes dans chaque bloc. Il sert à rendre visible ce qui manque.

Exemple : demander une page de prise de rendez-vous

La demande trop vague

Ajoute une belle page de réservation avec un calendrier.

Claude doit imaginer le service, le parcours, le contenu, la gestion des erreurs et la direction visuelle.

La demande cadrée

Le site présente un accompagnement pour freelances. Les visiteurs réservent actuellement depuis un lien externe placé dans le pied de page. Je veux une page /diagnostic qui explique le déroulement avant d’afficher le module de réservation déjà utilisé.

La page doit conserver les composants, la palette et le ton existants. Elle ne doit pas créer un second système de calendrier ni collecter d’information supplémentaire. Sur mobile, le module doit rester lisible sans défilement horizontal.

Commence par identifier le composant de réservation et les modèles de page existants. Propose ensuite la structure minimale. La tâche est terminée lorsque le parcours fonctionne sur mobile et ordinateur, que les liens existants pointent vers la nouvelle page et qu’aucun secret n’apparaît dans le code client.

La deuxième demande ne dicte pas chaque ligne. Elle donne à Claude les limites nécessaires pour bien choisir.

Le brief doit évoluer avec le niveau de risque

Toutes les tâches ne nécessitent pas la même cérémonie.

Risque faible

Correction d’une faute, changement d’un espacement ou mise à jour d’un lien. Un objectif, un périmètre et un contrôle suffisent souvent.

Risque moyen

Nouveau composant, formulaire ou changement partagé entre plusieurs pages. Utilisez les sept blocs et demandez un plan.

Risque élevé

Authentification, paiement, données clients, permissions ou migration. Ajoutez une revue de sécurité, des sauvegardes, un plan de retour arrière et, si nécessaire, une validation humaine qualifiée.

Le brief n’est pas de la bureaucratie. C’est un niveau de protection proportionnel aux conséquences d’une erreur.

Les signaux qui doivent faire arrêter l’IA

Demandez explicitement à Claude de s’arrêter lorsque :

• une information critique manque ;
• deux sources se contredisent ;
• la tâche exige un secret non disponible ;
• une modification détruirait des données ;
• plusieurs architectures sont possibles avec des conséquences différentes ;
• les tests échouent pour une cause inconnue ;
• le périmètre doit être élargi pour continuer.

Une IA fiable n’est pas celle qui termine tout coûte que coûte. C’est celle qui sait signaler la limite avant de créer un problème supplémentaire.

Les erreurs fréquentes

Décrire uniquement la solution

« Utilise telle bibliothèque » empêche parfois Claude de proposer une solution plus simple. Commencez par le résultat et ajoutez l’outil seulement lorsqu’il constitue une contrainte réelle.

Mélanger cinq objectifs

Une tâche trop large devient difficile à tester et à annuler. Découpez-la en livrables terminés.

Oublier le hors-périmètre

Sans limites, une amélioration locale peut déclencher une refonte.

Donner des critères subjectifs

« Professionnel », « intuitif » et « premium » doivent être traduits en références ou comportements observables.

Accepter « c’est terminé » sans preuve

Demandez quels tests ont été exécutés et ce qui n’a pas pu être vérifié.

Votre prochaine action en moins de 30 minutes

Prenez votre dernière demande à Claude Code qui a nécessité plusieurs corrections.

Réécrivez-la avec les sept blocs. Les zones que vous aurez du mal à remplir correspondent probablement aux décisions que vous aviez laissées à l’IA.

Conservez ce brief corrigé comme modèle pour votre prochain projet.

Questions fréquentes

Faut-il utiliser les sept blocs pour chaque prompt ?

Non. Utilisez la structure complète pour les tâches importantes, risquées ou transversales. Pour une correction locale, gardez seulement l’objectif, le périmètre, les contraintes et le contrôle attendu.

Un brief détaillé garantit-il un résultat parfait ?

Non. Il réduit l’ambiguïté et facilite la vérification. Le résultat dépend aussi de l’état du projet, des informations disponibles et de votre capacité à tester.

Claude doit-il toujours proposer un plan avant de coder ?

Le plan est utile lorsque plusieurs fichiers, choix ou risques sont concernés. Il peut ralentir inutilement une modification évidente et réversible. Adaptez le contrôle aux conséquences.

Comment éviter les briefs trop longs ?

Supprimez tout ce qui ne change aucune décision. Utilisez des liens vers les règles permanentes du projet plutôt que de les recopier. Un bloc doit rester scannable.

Que faire si Claude ignore une contrainte ?

Arrêtez l’exécution, indiquez précisément la contrainte violée et revenez à la dernière étape saine. Si le problème se répète, transformez la contrainte en test ou en règle permanente du projet.

Le brief est votre interface de pilotage

Vous ne pilotez pas une IA en lui parlant davantage. Vous la pilotez en rendant les décisions, les limites et la réussite visibles.

Les sept blocs créent un langage commun entre votre intention et l’exécution. Claude reste rapide, mais vous restez responsable de la direction.

---

Vous voulez fiabiliser vos projets construits avec l’IA ?

Chez Hél’IA Freelance, Romain vous aide à transformer vos consignes en méthodes réutilisables, avec des garde-fous et des contrôles adaptés à votre activité.

Réserver mon diagnostic gratuit de 20 minutes