Chapitre 3.5 — Atelier : le CLAUDE.md de TaskFlow

⏱️ TL;DR — On passe de la graine de CLAUDE.md (2.5) à un fichier solide mais mince, en appliquant les quatre qualités (court/priorisé/prescriptif/tranchable) et le modèle en couches (énoncer/montrer/imposer/rattraper). On ajoute un CLAUDE.md de dossier pour src/features/ là où un contrat local le justifie, et on note ce qui partira plus tard en hook. Résultat : un guide que l’agent suit vraiment.

🎯 Objectifs

• Faire mûrir un CLAUDE.md sans le faire gonfler.
• Répartir les règles entre racine et dossier.
• Marquer explicitement ce qui deviendra un hook (Partie 7).
• Repartir avec un CLAUDE.md réutilisable comme modèle.

Point de départ : la graine

Rappel de la graine (2.5) — correcte mais minimale :

# TaskFlow — Guide pour l'agent
## Stack
Next.js (App Router), TS strict, Tailwind, Prisma (SQLite dev / Postgres prod),
auth sessions, Zod, Vitest. Pas de lib de state global ni de composants lourde.
## Conventions (non négociables)
- src/features/<feature>/ (queries.ts, actions.ts)
- alias @/ ; jamais ../../..
- any interdit ; erreurs typées
- UI dans src/components/ui/ ; style de button.tsx
- tokens couleurs sémantiques ; pas de hex en dur
- un schéma Zod par entité, partagé
## Vérification
lint + test + build verts avant de conclure.

Maintenant qu’on a de l’expérience sur le projet, on la fait mûrir — en gardant la discipline de concision.

Le CLAUDE.md racine, version mûre

# TaskFlow — Guide agent
 
> But de ce fichier : ce que l'agent doit savoir en PERMANENCE pour TaskFlow.
> Court par choix. Détails d'archi → docs/. Décisions → docs/adr/.
 
## Non négociable (violé = ça casse)
- **TypeScript strict.** `any` interdit → `unknown` + narrowing. [futur hook: lint bloquant]
- **Mutations** : uniquement via server actions dans `src/features/<f>/actions.ts`.
  Jamais de mutation dans un composant client.
- **Validation** : chaque entrée serveur passe par son schéma Zod (`schema.ts`),
  partagé avec le form côté client. Pas de données non validées en base.
- **UI réutilisable** : uniquement `src/components/ui/`, importée via `@/components/ui`.
  Toute nouvelle primitive suit `src/components/ui/button.tsx` (le modèle).
 
## Conventions
- **Dossiers** : `src/features/<feature>/` = { queries.ts (lecture),
  actions.ts (mutations), schema.ts (Zod), components/ }.
- **Imports** : alias `@/`. Interdit : `../../..`.
- **Couleurs/espacements** : tokens sémantiques (`--color-*`) ; jamais de hex/valeur en dur.
- **Erreurs** : typées (pas de `throw "string"`), remontées à l'appelant, jamais avalées.
 
## Data
- Lecture serveur via `queries.ts` (fonctions pures autour de Prisma).
- Pas de requête Prisma directe dans un composant/route ; passe par la feature.
 
## Vérifier avant de conclure une tâche
- `npm run lint` · `npm test` · `npm run build` doivent passer. [sera imposé par hook, P7]
 
## Ce qu'on N'utilise PAS (ne pas introduire sans validation)
- Pas de lib de state global (Redux/Zustand…). Pas de lib de composants lourde.
- Pas de temps réel en v1. Pas d'UI optimiste en v1.

Points de méthode :

• Priorisé : « Non négociable » d’abord, « bon à savoir » ensuite.
• Tranchable : chaque ligne est vérifiable sur un exemple.
• Marqueurs [futur hook] : on signale ce qui migrera en garantie mécanique (Partie 7) sans encore l’automatiser. Ça documente l’intention.
• Section « Ce qu’on N’utilise PAS » : les non-choix (2.3) bornent les défauts de l’agent.
• Toujours court : ~30 lignes utiles, zéro description déductible.

⚠️ Piège — La tentation, à ce stade, d’ajouter « pendant qu’on y est » : l’historique du projet, la liste des features, des explications d’archi. Non : ça va dans docs/. Le CLAUDE.md reste le « toujours vrai », pas la doc du projet.

Un CLAUDE.md de dossier

src/features/ a un contrat local fort (le triptyque queries/actions/schema). On peut le rappeler là où l’agent travaille, dans src/features/CLAUDE.md :

# Règles des features
 
Chaque feature = un dossier `src/features/<nom>/` avec :
- `queries.ts` — lecture seule (fonctions pures autour de Prisma). AUCUN effet de bord.
- `actions.ts` — mutations, en server actions. Valident via `schema.ts` avant d'écrire.
- `schema.ts` — schémas Zod de l'entité, exportés pour le client.
- `components/` — UI propre à la feature ; le réutilisable monte dans `@/components/ui`.
 
Interdit : importer Prisma directement depuis un composant ou une route.

Ce fichier n’est chargé que quand l’agent touche à src/features/ — donc il n’alourdit pas les tâches qui n’y touchent pas. C’est la hiérarchie de 3.1 mise à profit.

💡 Réflexe d’architecte — N’ajoute un CLAUDE.md de dossier que si le contrat local est assez fort et spécifique pour le justifier. Sinon, une règle de plus à la racine suffit. Trop de fichiers de dossier = une hiérarchie que personne ne relit. Ici, le triptyque des features le mérite ; peu d’autres dossiers en auraient besoin.

Ce qu’on a construit

• Un CLAUDE.md racine mûr mais mince (~30 lignes), priorisé, tranchable, avec ses non-choix et ses marqueurs de futurs hooks.
• Un CLAUDE.md de dossier pour le contrat des features.
• Une intention claire pour la Partie 7 (ce qui deviendra mécanique).

TaskFlow a maintenant une mémoire projet solide, versionnée. Toute reprise — la tienne, une autre machine, un collègue — démarre sur les mêmes rails. C’est le socle sur lequel la Partie 4 va bâtir la cohérence visuelle.

✏️ Exercices

Exercice 1 — Fais mûrir le tien. Reprends le CLAUDE.md de ton kickoff (Partie 2). Fais-le mûrir avec la même méthode : priorise, ajoute une section « Ce qu’on N’utilise PAS », marque [futur hook] les règles mécaniques. Reste sous ~35 lignes utiles.

Exercice 2 — Un dossier mérite-t-il son fichier ? Repère dans ton projet un dossier au contrat local fort. Écris-lui un CLAUDE.md de dossier. Puis vérifie qu’il est bien chargé quand l’agent y travaille (chapitre 3.1).

🧠 Quiz de révision

Fin de la Partie 3. La mémoire et les conventions tiennent. On attaque la cohérence visuelle : Partie 4 — Design cohérent & anti-dérive.