Chapitre 2.1 — Donner la direction

⏱️ TL;DR — Avant d’écrire du code, quatre décisions déterminent la cohérence de tout le projet : le problème & le périmètre, la stack, le langage de design, les conventions. Un agent à qui tu ne donnes pas ces quatre-là les choisit à ta place — souvent raisonnablement, mais pas comme toi, et pas de façon cohérente d’un fichier à l’autre. Donner la direction, c’est prendre ces quatre décisions explicitement, en amont, puis les rendre visibles pour l’agent.

🎯 Objectifs

Nommer les quatre décisions de cadrage à figer avant tout code.
Comprendre pourquoi « laisser l’agent décider » produit de l’incohérence.
Distinguer sur-spécifier et sous-spécifier, et viser le juste milieu.
Préparer le terrain pour le brief (2.2) et l’atelier TaskFlow (2.5).

Pourquoi la direction se donne AVANT le code

Rappelle-toi la boucle agentique (1.1) : à chaque pas, l’agent choisit l’action « la plus raisonnable » vu ce qu’il sait. Si tu ne lui as pas dit quelle structure de dossiers, quel style de composant, quelle lib de formulaire, il en choisira une — la première session utilisera react-hook-form, une autre fera du state à la main, une troisième réinventera un composant Modal qui existe déjà. Chaque choix est défendable isolément ; l’ensemble est incohérent. C’est exactement ta douleur (« mes designs ne sont pas cohérents »).

La cohérence n’émerge pas toute seule d’une suite de décisions locales. Elle vient d’un cadre global posé en amont. Ton travail d’architecte : poser ce cadre, puis le rendre présent (via CLAUDE.md, fichiers-modèles, plan validé).

Les quatre décisions de cadrage

1. Le problème & le périmètre

Qu’est-ce qu’on construit, pour qui, et — surtout — qu’est-ce qu’on ne construit pas ? Le périmètre exclu est aussi important que l’inclus : sans lui, l’agent « rend service » en ajoutant des features que tu n’as pas demandées.

Pour TaskFlow : un SaaS de gestion de tâches multi-utilisateurs. Inclus : auth, projets, tâches, statuts. Exclu (v1) : temps réel, mobile natif, notifications email.

2. La stack

Les choix techniques structurants : framework, langage, styling, données, auth, tests. Tu peux co-décider avec l’agent (2.3), mais la décision doit être prise et écrite, pas laissée flotter.

Pour TaskFlow : Next.js (App Router), TypeScript strict, Tailwind, Prisma + SQLite en dev, auth par sessions, Vitest.

3. Le langage de design

Les fondations visuelles : tokens (couleurs, espacements, rayons), typographie, et surtout d’où viennent les composants (une lib ? des primitives maison ? shadcn/ui ?). Sans ça, chaque écran a son propre style.

Pour TaskFlow : design system minimal, tokens Tailwind custom, composants primitifs dans src/components/ui/, pas de lib de composants lourde.

4. Les conventions

Comment on écrit le code : structure des dossiers, nommage, alias d’import, gestion des erreurs, pattern de data-fetching, règles TypeScript. C’est le futur contenu de ton CLAUDE.md (Partie 3).

Pour TaskFlow : feature-folders sous src/features/, alias @/, pas de any, erreurs typées, server actions pour les mutations.

💡 Réflexe d’architecte — Ces quatre décisions ne demandent pas un document de 20 pages. Quelques lignes par point suffisent — mais elles doivent être prises consciemment et écrites quelque part que l’agent lit. « Dans ma tête » ne compte pas : l’agent ne lit pas ta tête.

Sur-spécifier vs sous-spécifier

Le cadrage est un curseur. Les deux extrêmes font mal :

	Sous-spécifié	Sur-spécifié
Symptôme	« fais-moi une app de tâches »	brief de 15 pages, chaque fonction détaillée
Résultat	l’agent invente tout, incohérent	tu as écrit le code toi-même, en anglais, plus lentement
Coût	correction massive après coup	temps perdu en amont + rigidité

Le bon niveau : décris les contraintes et les contrats, pas l’implémentation. « Les mutations passent par des server actions, les erreurs sont typées » (contrat) plutôt que « crée un fichier actions.ts avec une fonction createTask qui fait try/catch… » (implémentation — laisse-le faire).

⚠️ Piège — Le réflexe de sur-spécifier vient souvent de la peur de perdre le contrôle. Mais le contrôle ne vient pas du détail des instructions ; il vient du cadre (contrats, conventions, plan validé) + de la vérification (tests, revue). Cadre + vérifie, ne micro-manage pas.

Où « vivent » ces décisions

Prendre les décisions ne suffit pas : il faut les rendre présentes pour l’agent. On a trois véhicules, détaillés plus loin :

Dans le brief de kickoff (cette partie) — pour cette session.
Dans le CLAUDE.md (Partie 3) — pour toutes les sessions à venir.
Dans des fichiers-modèles et un plan validé (Parties 2 et 4) — comme exemples vivants.

🧭 Sur TaskFlow — Dans l’atelier 2.5, on prendra ces quatre décisions à voix haute, puis on les déposera : les grandes lignes dans le brief de la session, et les conventions durables dans un premier CLAUDE.md. Tu verras la différence de cohérence sur la première feature.

✏️ Exercices

Exercice 1 — Cadre en quatre lignes. Prends une idée de projet (la tienne, ou « un clone de Linear en petit »). Écris une ligne pour chacune des quatre décisions. Contrainte : pas plus d’une ligne chacune.

✅ Solution

Exemple : Problème — outil de suivi de bugs pour une équipe de 3, exclu : facturation. Stack — Next.js + TS + Tailwind + Prisma/Postgres. Design — shadcn/ui + tokens neutres, dark par défaut. Conventions — feature-folders, @/ alias, server actions, pas de any. Si tu n’arrives pas à tenir en une ligne, c’est souvent que la décision n’est pas encore prise.

Exercice 2 — Repère le curseur. Relis un ancien prompt de démarrage de projet. Était-il sous- ou sur-spécifié ? Réécris-le au bon niveau (contrats, pas implémentation).

✅ Solution

Sous-spécifié se reconnaît à l’absence de stack/conventions ; sur-spécifié, à la présence de noms de fonctions et de détails d’implémentation. La version « juste » énonce le problème, la stack, 3-4 conventions, et le critère de succès — et laisse l’agent proposer l’implémentation (qu’on validera en plan mode).

🧠 Quiz de révision

1. Pourquoi une suite de décisions locales « raisonnables » produit-elle de l’incohérence ?

Parce que chaque décision est prise isolément, sans vue d’ensemble : une session choisit une lib de formulaire, une autre en choisit une différente, une troisième réinvente un composant existant. La cohérence exige un cadre global posé en amont, pas une somme d’optimums locaux.

2. Quelles sont les quatre décisions de cadrage ?

Le problème & périmètre (dont l’exclu), la stack, le langage de design, les conventions de code. Prises explicitement, écrites, et rendues visibles à l’agent.

3. « Dans ma tête, je sais comment je veux le code. » Suffisant ?

Non : l’agent ne lit pas ta tête. Une décision de cadrage ne compte que si elle est écrite dans un endroit que l’agent lit (brief, CLAUDE.md, fichier-modèle).

4. Comment viser le bon niveau de spécification ?

Décrire les contraintes et contrats (« mutations via server actions, erreurs typées ») plutôt que l’implémentation ligne à ligne. Le contrôle vient du cadre + de la vérification, pas du micro-management.

5. Pourquoi le périmètre EXCLU est-il aussi important que l’inclus ?

Parce qu’un agent « rend service » : sans exclusions explicites, il ajoute des features non demandées (temps réel, i18n…), qui gonflent le scope et l’incohérence. Dire ce qu’on ne fait pas borne son initiative.

Chapitre suivant : Le brief & le plan mode — transformer ces décisions en un démarrage concret et validé.