Chapitre 2.5 — Atelier : kickoff de TaskFlow

⏱️ TL;DR — On déroule un vrai kickoff, du dossier vide au premier composant-modèle, en appliquant tout ce qu’on vient de voir : brief structuré → plan mode → corrections dans le plan → squelette → premier CLAUDE.md (graine) → un Button soigné comme référence. À la fin, TaskFlow a une direction, un cadre et un exemple vivant — l’agent est prêt à produire du cohérent par défaut. C’est le patron que tu réutiliseras sur chacun de tes projets.

🎯 Objectifs

• Exécuter un kickoff complet de bout en bout.
• Voir concrètement brief → plan → correction → exécution.
• Produire la graine de CLAUDE.md et le fichier-modèle.
• Repartir avec un patron reproductible.

Étape 0 — Le terrain

Dossier vide, terminal à la racine :

mkdir taskflow && cd taskflow
git init
claude

On lance en modèle fort (décisions d’archi) et on ne code encore rien. Premier réflexe : plan mode.

Étape 1 — Le brief

On envoie le brief structuré vu en 2.2 :

OBJECTIF : Amorcer TaskFlow, un SaaS de gestion de tâches multi-utilisateurs.
  Cette session : le SQUELETTE only (pas de features). Exclu : temps réel, mobile.
STACK : Next.js App Router, TypeScript strict, Tailwind, Prisma + SQLite (dev),
  auth par sessions (plus tard), Vitest.
CONVENTIONS :
  - feature-folders sous src/features/<feature>/
  - alias @/ (pas de ../../..)
  - TS strict, any interdit, erreurs typées
  - data : queries.ts (lecture) + actions.ts (server actions) par feature
  - UI : composants réutilisables dans src/components/ui/ uniquement
  - validation : un schéma Zod par entité, partagé client/serveur
DESIGN : tokens Tailwind custom (couleurs sémantiques), pas de lib de composants.
CRITÈRE : le projet build (npm run build), lint OK, une page d'accueil sobre,
  l'arborescence des dossiers en place, un composant Button modèle.
CONTRAINTE : reste en plan mode, ne crée rien avant que je valide le plan.

Étape 2 — Le plan (et ses corrections)

L’agent propose (extrait) :

PLAN
1. create-next-app (App Router, TS, Tailwind, ESLint)
2. Config : tsconfig strict + alias @/, tailwind tokens dans globals.css
3. Prisma init (datasource sqlite), schema vide + script db
4. Arbo : src/app, src/components/ui, src/features, src/lib
5. src/components/ui/button.tsx (variantes: primary/ghost/danger, tailles)
6. Page src/app/page.tsx sobre (titre + CTA Button)
7. Vitest config + 1 test smoke sur Button
8. README + scripts npm (dev/build/lint/test/db)

On lit avec la checklist (2.2) et on corrige dans le plan :

• « Ajoute src/components/ui/index.ts comme point d’export unique. »
• « Le Button : pas de any sur les props, étends ButtonHTMLAttributes, gère disabled et le focus visible (a11y). »
• « Tokens : définis-les en CSS variables sémantiques (--color-brand, --color-surface), pas des couleurs Tailwind brutes dans le composant. »
• « Ajoute un fichier CONVENTIONS court à la racine, on le transformera en CLAUDE.md. »

Chaque correction = une phrase. Sur du code déjà écrit, c’eût été un refactor.

⚠️ Piège — Se dire « le plan est bon à 90 %, je laisse filer les 10 % ». Ces 10 % (le token sémantique, l’export unique, l’a11y du Button) sont précisément ce qui fait la cohérence plus tard. Le fichier-modèle doit être exemplaire, pas « ok » : tout le reste va l’imiter.

Étape 3 — Exécution encadrée

On valide le plan corrigé. L’agent exécute. On garde deux réflexes :

• Critère de fin vérifiable : à la fin, on lui demande de lancer npm run build, npm run lint, npm test et de montrer que tout est vert. Pas « je pense que ça marche » — la preuve.
• On lit la diff du fichier-modèle (button.tsx) avec soin, puisque c’est la référence. Le reste (config, page d’accueil) mérite un survol.

Résultat : un squelette qui build, une arbo propre, un Button soigné.

Étape 4 — La graine de CLAUDE.md

On transforme le fichier CONVENTIONS en premier CLAUDE.md (on l’étoffera en Partie 3). Version graine :

# TaskFlow — Guide pour l'agent
 
## Stack
Next.js (App Router), TypeScript strict, Tailwind, Prisma (SQLite dev / Postgres prod),
auth sessions, Zod, Vitest. Pas de lib de state global, pas de lib de composants lourde.
 
## Conventions (non négociables)
- Organisation : `src/features/<feature>/` (queries.ts = lecture, actions.ts = mutations server actions).
- Imports : alias `@/`. Jamais de `../../..`.
- TypeScript strict : `any` interdit ; erreurs typées.
- UI : composants réutilisables **uniquement** dans `src/components/ui/`, importés via `@/components/ui`.
  Suivre le style de `src/components/ui/button.tsx` (le modèle).
- Couleurs : tokens sémantiques CSS (`--color-brand`…), jamais de hex/couleur Tailwind brute dans un composant.
- Validation : un schéma Zod par entité, dans `schema.ts`, partagé client/serveur.
 
## Vérification
Avant de conclure une tâche : `npm run lint`, `npm test`, `npm run build` doivent passer.

💡 Réflexe d’architecte — Remarque la dernière section, « Vérification ». Elle dit à l’agent comment prouver que c’est fini. En Partie 7, on rendra ça automatique (hook) au lieu de compter dessus. Ici, on l’écrit ; plus tard, on le garantit.

Étape 5 — Ce qu’on a gagné

En ~30 minutes, sans écrire une ligne de feature, TaskFlow a :

• une direction (les 4 décisions de cadrage, prises et écrites) ;
• un cadre (la graine de CLAUDE.md, présente à chaque session future) ;
• un exemple vivant (le Button modèle que tout imitera) ;
• un critère de vérification explicite.

La prochaine session qui ajoutera une feature partira sur des rails. C’est ça, « donner la bonne direction dès le départ ».

🧭 Sur TaskFlow — On reprendra ce projet en Partie 3 pour muscler le CLAUDE.md, en Partie 4 pour le design system, puis on lui ajoutera sa première vraie feature (le CRUD des tâches) une fois le terrain solide. Le kickoff n’est pas un rituel : c’est l’investissement qui rend tout le reste cohérent.

✏️ Exercices

Exercice 1 — Ton propre kickoff. Applique les 4 étapes (brief → plan → exécution encadrée → graine de CLAUDE.md) sur un projet réel ou un bac à sable. Chronomètre : vise 30-40 minutes.

Exercice 2 — Le fichier-modèle exemplaire. Sur ton kickoff, prends UN composant et rends-le vraiment exemplaire (types stricts, tokens, a11y, pas de couleur en dur). Puis demande à l’agent d’en créer un second « dans le même style » et compare : imite-t-il correctement ?

🧠 Quiz de révision

Fin de la Partie 2. TaskFlow a une direction et un cadre. On va maintenant rendre ces conventions vraiment durables et efficaces : Partie 3 — CLAUDE.md, mémoire & conventions.