Claude Code accepte des prompts de 50 000 tokens. Ça ne veut pas dire qu'il faut en écrire autant. Je construis des SaaS complets avec cet outil depuis un an, et mes meilleurs briefs tiennent en 2 pages - ni plus, ni moins.
Voici le format que j'utilise.
Le problème avec les briefs longs
J'ai commencé en écrivant des cahiers des charges de 15 pages. Chaque règle métier, chaque edge case, chaque préférence de style. Résultat : Claude Code produisait du code correct mais inégal. Trop d'informations = moins d'attention sur ce qui compte.
L'erreur, c'est de confondre brief et spécification. Un brief n'est pas une spec — c'est une direction à haute densité.
La structure qui marche
1. WHY (3-5 lignes)
L'objectif business, la douleur qu'on résout, l'utilisateur final.
2. HOW (10-15 lignes)
Les 3-5 fonctionnalités clés, sans détail technique.
Ce que l'utilisateur fait, dans l'ordre.
3. STACK (5 lignes)
Langages, frameworks, DB, contraintes techniques non-négociables.
4. CONTRAINTES (5-10 lignes)
Sécurité, performance, compat. Ce qui doit absolument être respecté.
5. NON-GOALS (3-5 lignes)
Ce qu'on ne fait PAS. Aussi important que le reste.
6. EXEMPLES (facultatif, mais précieux)
1-2 cas d'usage concrets écrits comme des scénarios.Exemple réel
Voici le brief que j'ai donné pour NaviR Field, condensé :
WHY : Remplacer les bons papier de notre boîte 3D. 8 techs, 500 interventions/mois, marchés publics avec contraintes PDF.
HOW :
- Technicien ouvre l'app sur mobile, voit sa tournée du jour
- Clic sur intervention → wizard 4 étapes (mission, inspection, actions, finalisation)
- Signature client sur canvas tactile
- À la clôture, PDF rapport + facture auto-générés
- Géoloc GPS envoyée toutes les 30 s au serveur
STACK : FastAPI async · React 19 + Vite + Tailwind 4 · PostgreSQL 16 + RLS · Docker · WeasyPrint pour PDF
CONTRAINTES :
- Mobile-first, utilisable hors-ligne jusqu'à sync
- Multi-tenant par agence (RLS stricte)
- PDF conforme marché public : en-tête bailleur, pied de page certibiocide
- Signature avec hash SHA-256 pour opposabilité
NON-GOALS :
- Pas de planning auto-optimisé (humain décide)
- Pas de chat interne (on utilise WhatsApp)
- Pas d'i18n (français uniquement)
2 pages A4. Quelques heures plus tard, une V1 fonctionnelle. Quatre semaines plus tard, un ERP complet.
Les 3 erreurs à éviter
1. Mélanger intention et implémentation
« Le technicien voit sa tournée » = intention. « Utiliser React-Query avec polling de 30s et fallback WebSocket » = implémentation. Dans un brief, on reste sur l'intention. L'implémentation émerge à la conversation.
2. Oublier les non-goals
Claude Code essaie par défaut de faire trop. Si vous ne dites pas ce qui est hors-scope, vous allez recevoir du code pour une planif auto-optimisée avec ML que personne n'a demandé.
3. Mettre des priorités implicites
Si tout est « critique », rien n'est critique. Numérotez 3 fonctionnalités par ordre de priorité dans le HOW.
Le vrai secret : l'itération
Un bon brief ne produit pas le bon code du premier coup. Il produit du code dont vous pouvez débattre. Ensuite vous itérez :
- « Tel endroit est trop couplé, extrait ça en service »
- « Les migrations devraient être en Alembic, pas en SQL raw »
- « Le PDF a un bug sur les caractères accentués »
Chaque correction affine le contexte. Après 3 à 4 itérations, vous avez un système qui tient la route.
Résumé
Un brief qui marche :
- Court (2 pages max)
- Hiérarchisé (WHY > HOW > STACK > CONTRAINTES > NON-GOALS)
- Concret (scénarios utilisateur, pas concepts abstraits)
- Honnête sur le hors-scope
Vous gagnerez plus à simplifier votre brief qu'à acheter un modèle plus gros.