Chapitre 2.3 — Décider la stack (sans subir)
⏱️ TL;DR — L’agent a des stacks par défaut dans les mains : demande-lui une app sans préciser, et il sortira sa combinaison habituelle. Parfois c’est bien ; souvent ce n’est pas ton choix, et surtout ce n’est pas reproductible d’un projet à l’autre. Le bon usage : te servir de l’agent comme d’un sparring-partner pour décider (comparer des options selon tes contraintes), puis figer la décision — versions comprises — pour qu’elle ne dérive plus.
🎯 Objectifs
- Reconnaître la dérive de stack par défaut et pourquoi elle nuit à la cohérence.
- Utiliser l’agent comme aide à la décision sans lui déléguer la décision.
- Figer une stack (choix + versions) de façon durable.
- Poser la stack de TaskFlow avec ses raisons.
La dérive de stack par défaut
Quand tu dis « fais-moi un formulaire de connexion », l’agent doit bien choisir quelque chose : une lib de form, une approche de validation, un style. Il prendra un défaut raisonnable. Le problème n’est pas la qualité du défaut — c’est que :
- il varie d’une session à l’autre (rien ne le fixe) ;
- il n’est pas le tien (tu as peut-être des préférences ou des contraintes d’équipe) ;
- il est invisible : tu le découvres dans le code, après coup.
Résultat : trois écrans, trois approches de formulaire. Encore l’incohérence — mais cette fois au niveau des outils, pas seulement du style.
⚠️ Piège — « L’agent a mis
react-hook-form, c’est très bien, je garde. » Peut-être. Mais si tu ne l’as pas décidé et écrit, le prochain écran utilisera peut-être du state manuel. Le problème n’est jamais un bon défaut isolé ; c’est l’absence de décision figée.
L’agent comme sparring-partner de décision
Tu n’as pas à tout savoir d’avance. Sers-toi de l’agent pour décider mieux, sans lui abandonner la décision. La bonne question n’est pas « choisis une lib de form », c’est :
« Je veux gérer les formulaires de TaskFlow. Contraintes : TS strict, validation partagée client/serveur avec Zod, pas de dépendance lourde, SSR-friendly (App Router). Compare 2-3 approches et recommande, avec les compromis. »
Tu obtiens une comparaison argumentée selon tes contraintes, puis tu tranches. La différence avec « choisis » : tu gardes le volant, et tu comprends pourquoi — donc tu pourras défendre et reproduire le choix.
💡 Réflexe d’architecte — Demande toujours les compromis, pas juste une reco. « Recommande X » te donne un choix ; « compare X/Y/Z avec les compromis » te donne le raisonnement, qui vaut bien plus : tu réutiliseras le raisonnement, pas juste la conclusion.
Figer la décision (choix + versions)
Une décision de stack non figée n’existe qu’à moitié. « Figer » veut dire :
- Écrire le choix ET la raison (dans le
CLAUDE.md, Partie 3, ou un ADR si c’est structurant et coûteux à changer). - Épingler les versions critiques (
package.json) — l’écosystème JS bouge, et une version majeure surprise peut casser le build (les cours frères de ce playbook en ont fait les frais avec une lib mal épinglée). - Donner un fichier-modèle dès que possible : le premier formulaire bien fait devient la référence que l’agent imitera pour les suivants (Partie 4).
📚 Aller plus loin — Pour les choix vraiment structurants et durs à inverser (base de données, framework, stratégie d’auth), un ADR (Architecture Decision Record) d’un paragraphe suffit : contexte, décision, pourquoi. Ça évite qu’on « refixe » six mois plus tard une décision déjà tranchée. On en reparle en Partie 3.
Faire réviser un choix par un contre-argument
Astuce de pilote : une fois que tu penses avoir décidé, demande à l’agent de plaider contre.
« J’ai choisi SQLite en dev et Postgres en prod pour TaskFlow. Donne-moi les meilleurs arguments contre ce choix, et les pièges concrets de la parité dev/prod. »
Tu ne cherches pas à changer d’avis systématiquement — tu cherches à connaître les angles morts avant qu’ils te tombent dessus. Un bon architecte décide puis stress-teste sa décision.
La stack de TaskFlow (et pourquoi)
Pour le fil rouge, on fige :
| Choix | Décision | Pourquoi (en une ligne) |
|---|---|---|
| Framework | Next.js (App Router) | ton terrain ; server actions + RSC utiles pour un SaaS |
| Langage | TypeScript strict | contrats explicites, any banni |
| Styling | Tailwind + tokens custom | cohérence par tokens, pas de lib lourde |
| Données | Prisma + SQLite (dev) / Postgres (prod) | DX rapide en dev, robuste en prod |
| Auth | sessions serveur | simple, adapté v1, pas de sur-ingénierie |
| Validation | Zod, partagée client/serveur | un seul schéma, deux usages |
| Tests | Vitest | rapide, intégré à l’écosystème |
Chaque ligne est une décision prise, pas un défaut subi. On la déposera dans le CLAUDE.md de TaskFlow à la partie suivante.
🧭 Sur TaskFlow — Remarque qu’on n’a pas choisi de lib de state global, de lib de composants lourde, ni de solution temps réel. Ces non-choix sont aussi des décisions de cadrage : ils bornent ce que l’agent va tirer par défaut. « Ce qu’on n’utilise pas » mérite sa place dans le
CLAUDE.md.
✏️ Exercices
Exercice 1 — Compare, ne délègue pas. Prends un vrai choix ouvert de ton projet (lib de form, ORM, gestion d’état). Formule la demande « compare 2-3 options selon MES contraintes + compromis ». Tranche toi-même et écris la raison.
✅ Solution
La clé est d’expliciter tes contraintes dans la demande (TS strict, SSR, taille du bundle, préférences d’équipe). Sans elles, la comparaison est générique et inutile. Avec elles, tu obtiens un raisonnement applicable — et tu gardes la décision. Note la raison : elle ira dans le CLAUDE.md ou un ADR.
Exercice 2 — Plaide contre. Reprends une décision de stack que tu as déjà prise. Demande à l’agent les meilleurs arguments contre. Note un angle mort que tu ignorais.
✅ Solution
L’exercice révèle presque toujours un piège concret (parité dev/prod, coûts de migration, limites de la lib à l’échelle). Tu n’es pas obligé de changer d’avis : tu es maintenant conscient du compromis, ce qui est le but. Décider puis stress-tester, c’est du pilotage d’architecte.
🧠 Quiz de révision
1. Qu’est-ce que la « dérive de stack par défaut » ?
Quand, faute de décision explicite, l’agent utilise ses défauts — qui varient d’une session à l’autre, ne sont pas les tiens, et sont invisibles jusqu’à la relecture. Source d’incohérence au niveau des outils.
2. Différence entre « choisis une lib » et « compare avec compromis » ?
« Choisis » délègue la décision (et son raisonnement). « Compare X/Y/Z selon mes contraintes avec les compromis » te rend le raisonnement et te laisse trancher — tu comprends et tu peux reproduire.
3. Que veut dire « figer » une décision de stack ?
Écrire le choix + la raison (CLAUDE.md ou ADR), épingler les versions critiques, et fournir un fichier-modèle de référence. Une décision non figée dérive.
4. Pourquoi demander à l’agent de « plaider contre » ta décision ?
Pour découvrir les angles morts (pièges, compromis) avant qu’ils ne te tombent dessus. On décide puis on stress-teste ; ça ne force pas à changer d’avis, ça rend le compromis conscient.
5. En quoi les « non-choix » sont-ils des décisions de cadrage ?
Dire « pas de lib de state global, pas de lib de composants lourde » borne les défauts que l’agent tirerait sinon. Ce qu’on n’utilise pas oriente autant le code que ce qu’on utilise — donc ça s’écrit aussi.
Chapitre suivant : Poser design & conventions au départ — le socle concret qui empêche la dérive visuelle et de code.