Chapitre 2.2 — Le brief & le plan mode

⏱️ TL;DR — Le brief est le message de kickoff qui transmet tes quatre décisions à l’agent. Le plan mode est ce qui l’oblige à te montrer comment il compte s’y prendre avant de toucher au code. Ensemble, ils déplacent toutes tes corrections en amont, là où elles coûtent une phrase au lieu de trente fichiers. Un bon brief tient en une page ; un bon plan se lit en deux minutes et se corrige avant la première ligne de code.

🎯 Objectifs

• Structurer un brief de kickoff clair (objectif, contraintes, contrats, critère de fin).
• Lancer un projet en plan mode et lire un plan de façon critique.
• Corriger l’architecture dans le plan, pas dans le code.
• Enchaîner brief → plan → validation → exécution.

L’anatomie d’un bon brief

Un brief efficace n’est pas long, il est structuré. Cinq blocs :

1. OBJECTIF     — ce qu'on construit, en 1-2 phrases (+ ce qu'on EXCLUT).
2. STACK        — les choix techniques structurants.
3. CONVENTIONS  — 3 à 6 règles de code non négociables.
4. CONTRAT      — les invariants (auth, erreurs, data-fetching…).
5. CRITÈRE      — comment on saura que c'est fini (tests, build, écran qui marche).

Exemple minimal pour la première feature de TaskFlow :

OBJECTIF : CRUD des tâches d'un projet dans TaskFlow. Exclu : temps réel, drag & drop.
STACK    : Next.js App Router, TS strict, Tailwind, Prisma/SQLite, Vitest.
CONVENTIONS : feature-folders sous src/features/, alias @/, pas de any, erreurs typées.
CONTRAT  : mutations via server actions ; validation Zod côté serveur ; UI optimiste interdite en v1.
CRITÈRE  : npm test vert + page /projects/[id] qui liste, crée, édite, supprime une tâche.

C’est court, mais chaque ligne retire une décision que l’agent aurait prise à ta place.

💡 Réflexe d’architecte — Écris le CRITÈRE en premier dans ta tête. « Comment je saurai que c’est fini ? » clarifie tout le reste. Un critère vérifiable (les tests passent, cet écran fait X) transforme une demande floue en objectif de boucle agentique net.

Le plan mode : voir avant de subir

Tu as ton brief. Ne le lance pas en exécution directe : passe en plan mode. L’agent va concevoir sans rien modifier, puis présenter son plan. Tu obtiens quelque chose comme :

PLAN (proposé)
1. Modèle Prisma : Task { id, title, status, projectId, createdAt }
2. Migration + client Prisma
3. src/features/tasks/ : queries.ts (lecture), actions.ts (server actions), schema.ts (Zod)
4. Composants : TaskList, TaskItem, TaskForm dans src/features/tasks/components/
5. Page app/projects/[id]/page.tsx qui compose la liste + le form
6. Tests Vitest : actions (create/update/delete) + schema

C’est maintenant que tu interviens, à un coût dérisoire :

• « Le statut doit être un enum todo | doing | done, pas une string libre. »
• « Mets la validation Zod dans schema.ts et réutilise-la côté form. »
• « Pas de composant TaskForm générique : un pour la création, un pour l’édition. »

Chaque remarque coûte une phrase. La même correction après coup, sur du code écrit, coûte une relecture + des éditions + des tests à refaire.

⚠️ Piège — Valider un plan « en diagonale » parce qu’il a l’air bien. Le plan est le dernier endroit pas cher pour attraper une mauvaise décision d’architecture. Lis-le comme tu lirais une PR : la structure de données est-elle juste ? les seams (frontières entre modules) sont-elles propres ? qu’est-ce qui manque ? Deux minutes ici économisent une demi-journée après.

Lire un plan de façon critique

Une petite checklist mentale à passer sur chaque plan :

💡 Réflexe d’architecte — Le plan mode n’est pas qu’un garde-fou : c’est ton meilleur outil d’apprentissage du codebase. En lisant comment l’agent propose de structurer, tu vois vite s’il a compris tes conventions — ou s’il te manque un CLAUDE.md (Partie 3). Un plan qui viole tes conventions = signal qu’elles ne sont pas écrites.

Quand sauter le plan mode

Le plan mode a un coût (un aller-retour). On le saute pour les tâches petites et non ambiguës : « corrige ce typo », « ajoute un champ optionnel », « renomme cette variable partout ». Règle : plus l’enjeu et l’ambiguïté sont élevés, plus le plan est rentable. Un one-liner trivial n’en a pas besoin ; un nouveau module, si.

🧭 Sur TaskFlow — Dans l’atelier 2.5, on lancera le tout premier squelette de TaskFlow en plan mode. Tu verras l’agent proposer une arborescence — et on la corrigera avant qu’un seul fichier existe. C’est la démonstration concrète que « cadrer d’abord » n’est pas un slogan.

✏️ Exercices

Exercice 1 — Brief en cinq blocs. Écris le brief (objectif/stack/conventions/contrat/critère) d’une feature que tu veux vraiment faire. Vérifie que le critère est vérifiable (pas « que ça marche bien »).

Exercice 2 — Corrige un plan. Lance ta feature en plan mode. Applique la checklist. Trouve au moins une décision à corriger dans le plan et corrige-la avant l’exécution.

🧠 Quiz de révision

Chapitre suivant : Décider la stack (sans subir) — piloter les choix techniques au lieu de les laisser à l’agent.