Processus de fonctionnalité
Principe principal : moins l'agent prend de décisions par lui-même, plus le résultat est stable. Chaque phase se termine par un artefact dans docs/features/<slug>/ et une vérification (une « porte »). Là où c'est indiqué, la transition vers l'étape suivante nécessite la confirmation humaine.
Comment écrire le code lui-même — fsd-frontend ; vérification des déchets — anti-slop-review ; entrée et session — frontend-auth-session.
1. Phases
| # | Phase | Artefact | Approuvé par | Porte |
|---|---|---|---|---|
| 0 | Préparation | branche | — | Arbre de travail propre ; après installation des dépendances et migrations — /clear |
| 1 | PRD | prd.md | humain | Non-Goals remplis ; critères vérifiables ; aucune solution technique |
| 2 | Spécification | spec.md, jusqu'à 150 lignes | humain | Couvre tous les critères du PRD et rien de plus |
| 3 | Tâches | tasks.md | humain | Une tâche = un commit ; la première est un tracer bullet |
| 4 | Investigation | journal dans tasks.md | — | Lecture seule ; trouve ce qui peut être réutilisé |
| 5 | Tracer bullet | commit | — | Un scénario traverse tout et est visible dans le navigateur |
| 6 | Construction | commit par tâche | — | Test d'abord pour la logique ; pnpm check vert |
| 7 | Revue | rapport reviewer | humain sur les trouvailles | Corrections des trouvailles confirmées |
| 8 | Navigateur | e2e sur le chemin critique | — | Les scénarios du PRD passent sans erreur dans la console |
Une petite tâche (un commit, sans nouveau comportement pour l'utilisateur) saute les phases 1 à 3, mais les Non-Goals sont tout de même notés dans la description de la tâche. Le saut de phase est annoncé verbalement, pas effectué silencieusement.
2. PRD
Modèle — docs/features/_template/prd.md.
- L'agent rédige un brouillon à partir de la demande et ne pose que les questions sans lesquelles il ne peut pas continuer. Le reste est consigné dans les « Questions ouvertes », que l'humain confirme lors de l'approbation.
- Les Non-Goals sont obligatoires. Énumère ce que l'agent aura envie de faire « en passant » : responsive pour de nouvelles tailles, animations, i18n, mise en cache, panneau d'administration, refactorisation du code voisin. Sans cette liste, la fonctionnalité s'étend.
- Les critères de complétude sont vérifiables : « Étant donné / Quand / Alors », pas « pratique » ou « rapide ».
- Aucune bibliothèque, fichier ou schéma : il s'agit de « quoi et pourquoi », pas de « comment ».
3. Spécification
Modèle — docs/features/_template/spec.md.
- Jusqu'à 150 lignes. Rédigée par l'agent, approuvée par l'humain. Une spécification générée trop longue est pire que pas de spécification : elle encombre le contexte et dilue les décisions.
- Avant la rédaction — une courte analyse en lecture seule des couches concernées : ce qui existe déjà, ce qui peut être réutilisé.
- Contient : où vit le code (couches, slices), contrats de données (schémas zod, mapping DTO), API (entrée, sortie, erreurs →
kind), états UI, cas limites, scénarios d'acceptation avec niveau de test. - La spécification vit avec le code. Un changement de comportement corrige
spec.mddans le même commit. Un code qui diverge de la spécification est un défaut de l'un ou l'autre.
4. Tâches
Modèle — docs/features/_template/tasks.md.
- Une tâche = un commit, après quoi le projet se construit et les vérifications passent. Si l'agent se retrouve dans une impasse, un retour au commit précédent coûte moins cher qu'un débat avec le modèle.
- La tâche tient en une session ; chacune a un « fait quand ».
- La première tâche est un tracer bullet, ensuite viennent les états, les cas limites, le polissage.
5. Investigation (lecture seule)
Avant chaque tâche, sans modifier les fichiers :
AGENTS.mddes dossiers concernés ;- le code existant qui résout quelque chose de similaire (
rgpar noms et contrats) ; - les contrats et types sur lesquels la tâche s'appuie.
Si ce qui a été trouvé sera utile plus tard — 2–3 lignes dans le journal tasks.md.
6. Tracer bullet
Un scénario complet : route → page → fonctionnalité ou entité → request() → route handler ou backend → résultat à l'écran.
- C'est du code de production, pas un prototype : couches correctes, vrais contrats issus de la spécification.
- Volontairement sans : validation détaillée, polissage des états de chargement et d'erreur, styles, cas limites.
- Backend pas prêt — un handler MSW ou route handler qui renvoie des données selon le contrat de la spécification ; cela est noté dans
tasks.md. - Vérification — dans le navigateur : le scénario passe et il n'y a pas d'erreur dans la console.
7. Construction
- Logique — test d'abord : fonctions pures, stores, mapping de réponses, hooks avec branchements. Le test doit échouer pour la raison attendue, puis le code. Un test écrit après le code a tendance à vérifier ce que le code fait, pas ce qui est requis.
- Mise en page et styles — pas de test à l'avance : ils sont vérifiés par le navigateur (phase 8), le chemin critique est couvert par les e2e.
- Après la tâche :
pnpm check, commit (lint-staged vérifie les fichiers modifiés). - Arrêt : trois tentatives échouées pour corriger la même chose — stop. Décris à l'humain ce qui a été essayé et l'hypothèse. N'adapte pas les tests au code, ne désactive pas les règles du linter, n'affaiblis pas les types.
- Tout ce qui est hors tâche va dans le journal « plus tard », pas dans ce commit.
8. Revue
- Sous-agent
reviewer(.claude/agents/reviewer.md) avec un contexte vierge : transmets le chemin versprd.mdetspec.mdet la plage de commits ; il lit lui-même le diff. L'auteur du code voit moins bien ses propres erreurs : dans son contexte, il a des arguments pour justifier que sa solution est correcte. - Les trouvailles confirmées sont corrigées, les controversées sont tranchées par l'humain.
- La sécurité est aussi vérifiée par l'humain : connexion, sessions, redirections, cookies, saisie utilisateur dans HTML. Des vérifications vertes ne garantissent pas cela : en pratique, une redirection ouverte a passé les tests, et une page d'erreur illisible — le linter.
9. Navigateur
- Next.js : skill
next-dev-loopavecagent-browsersi installé ; sinon Playwright ou Chrome DevTools MCP. - Parcours les scénarios du PRD, y compris les négatifs : données vides, erreur réseau, double soumission. Regarde la console et les statuts des requêtes.
- Pour l'UI — thème clair et sombre, largeur de téléphone.
- Chemin critique — test e2e dans
e2e/. - Fait, lorsque chaque critère du PRD est vérifié ; dans le message final — la liste des critères et comment chacun a été vérifié.
10. Contexte
- L'état du travail vit dans
docs/features/<slug>/, pas dans la correspondance : une nouvelle session commence par la lecture deprd.md,spec.md,tasks.md. - Après les étapes bruyantes (installation, migrations, longs logs) —
/clear. - Les expériences parallèles — dans
git worktree, pas dans la branche de travail.
11. Ce qu'il ne faut pas faire
- Questions de clarification infinies : demande ce qui bloque, le reste est consigné dans les hypothèses du PRD.
- Orchestrateurs composés de nombreux agents : un exécutant et un réviseur suffisent.
- Spécifications et documentation que personne n'a approuvées ni lues.
- Sauts de phase silencieux et corrections « en passant ».