Le développement
Ce que fait go-dev d'une user story, des questions du départ jusqu'à la pull request. Et les seuls moments où il s'arrête pour vous demander.
En amont : la préparation technique
tech-shaperune fois par feature, avant la création des fichesAvant la moindre ligne de code, tech-shaper écrit ce qu'il faut savoir pour coder la feature, et vous le fait valider. go-dev ne décide presque rien seul : il exécute ce document. tech-shaper part du cadrage découpé en user stories et des écrans validés (voir la chaîne).
ACe qu'il litLe cadrage découpé en user stories, les écrans, les codemaps, le code réel et la politique de test de la stack. Rien n'est deviné.clédocs/feature-shaper/project/*.dc.htmldocs/CODEMAPS/<stack>-tests-and-gates
| Ce qu'il lit | Pour en tirer |
|---|---|
docs/feature-shaper/<ID>-*.md | Les user stories : critères AC-n, recette, périmètre fermé, dépendances. |
project/*.dc.html · donnees.json | Les données affichées et leur origine, les états à produire, les composants employés. |
docs/CODEMAPS/ · CLAUDE.md | L'architecture du repo, ses commandes, ses zones sensibles, ses règles (Fabrique comprise). |
Le code (Glob / Read, sinon gh api) | Ce qui existe vraiment : modules, patterns, schéma, migrations, versions du lockfile. |
.claude/skills/<stack>-tests-and-gates | La politique de test du repo : les règles « déclencheur → test dû ». |
BCe qu'il fait trancherCe que la lecture n'a pas tranché devient une question, avec sa réponse recommandée. Aucune contrainte n'est inventée.cléAskUserQuestion[NON VÉRIFIÉ]
Par rounds, avec AskUserQuestion, huit questions au plus, chacune avec une réponse recommandée et argumentée. Seulement ce que la lecture n'a pas tranché :
- l'architecture retenue ;
- le contrat d'API : existe-t-il déjà ?
- le schéma : change-t-il ? migration additive ou destructive ?
- les risques : données personnelles, paiement, performance ;
- les points de test proposés ;
- les règles de la politique de test qui se déclenchent, US par US.
Zéro contrainte inventée : une affirmation non vérifiée dans le repo porte [NON VÉRIFIÉ]. En run, ce qui repose sur le RFC d'une feature pas encore codée porte [ANTICIPÉ — RFC SVU-13].
CLes points de testLes endroits du code où la feature sera testée : les plus hauts, les moins nombreux, existants plutôt que nouveaux.cléout/backlog.htmlchargerBacklog()
Les endroits du code où la feature sera testée. Trois règles : les plus hauts possible (une page générée, une route, une action, plutôt qu'une fonction interne), les moins nombreux possible, existants plutôt que nouveaux. Exemple réel, SVU-14 :
| Point de test | Où, dans le code | Ce qu'il vérifie |
|---|---|---|
| Page générée (existant) | out/backlog.html via tests/page-backlog.test.ts | La frise, les pastilles, les liens, le HTML produit par next build |
| Chargement du contenu (existant) | chargerBacklog() avec fixtures | Fichier valide ; fichier incomplet → erreur nommée |
| Rendu de la fiche (nouveau) | FicheUS via renderToStaticMarkup | L'état par défaut, les six définitions cachées |
DLa politique de test de la stackChaque règle dit quel test est dû quand un fichier précis change. Seules les règles déclenchées entrent dans le plan de test.clédéclencheur → test dûnextjs-tests-and-gates
Une skill de stack, posée par bootstrap-agents, une par stack : nextjs-tests-and-gates, dotnet-tests-and-gates… Chaque règle a la forme déclencheur observable → test dû. tech-shaper croise les déclencheurs avec les fichiers que la feature touchera, et vous fait valider la liste. Extrait de la politique Next.js :
| Déclencheur | Test dû |
|---|---|
Un fichier 'use server' lit la session | Un test du chemin refusé : non authentifié, et sans le droit |
| Une Server Action écrit en base | Une entrée malformée, rejetée avant tout effet de bord |
Un nouveau fichier 'use client' | Un test de rendu de l'état par défaut, un par branche. Jamais un E2E |
Un app/**/route.ts change de signature | Un test du contrat d'erreur : méthode non supportée, corps invalide |
Seules les règles déclenchées sont recopiées dans le plan de test de l'US. La politique entière reste dans le repo, en un seul exemplaire.
ELe document qu'il écritUn RFC pour la feature, puis une section par user story, validés par vous puis recopiés dans les fiches Notion.clédocs/tech-shaper/SVU-14-backlog-notion.md
docs/tech-shaper/SVU-14-backlog-notion.md# Partie 1 — RFC de la feature ## En bref ## Contexte système ## Repos impactés ## Décisions d'architecture « La page suit le trio contenu / chargeur / composant. La skill nextjs-app-router-scaffold s'applique à la nouvelle route. » ## Points de test ## Contraintes transverses ## Politique de test ## Questions ouvertes ❓ # Partie 2 — une section par user story ## US1 — Le backlog Notion se lit sur le site ### Contraintes techniques ### Contexte technique fichiers touchés + raison, patterns ### Plan de test AC-n → point de test ### Definition of Done - [ ] npm run check passe — sortie collée - [ ] out/backlog.html est produit — sortie de ls ### Definition of Ready ## US2 — …
Validé par vous, puis recopié par boucle-backlog-builder dans chaque fiche Notion. C'est ce que go-dev lit.
FComment go-dev est tenu par ce documentgo-dev exécute ce document phase par phase. Chaque écart se consigne et se voit dans la PR.cléphases 0, 2, 4, 5, 6journal d'écarts
go-dev ne réinterprète pas la préparation technique : il l'exécute, et chaque écart se voit.
- 0 · Pré-vol
- Les questions ❓ du RFC rejoignent son unique lot de questions. Plus rien ne se demande ensuite.
- 2 · Le plan
- Le plan part des « Décisions d'architecture » et du « Contexte technique ». go-dev ne choisit pas une autre architecture.
- 4 · Le TDD
- Chaque test s'écrit au point de test validé. Un test écrit ailleurs est consigné au journal d'écarts et signalé dans la PR. Les tests dus par la politique s'écrivent même si aucun critère ne les demande.
- 5 · La DoD
- go-dev coche la Definition of Done écrite par tech-shaper, preuve collée : une sortie de commande, un test, une capture. Une case qu'il ne peut pas prouver reste vide.
- 6 · La revue
- Le relecteur de conformité reçoit les critères, le périmètre fermé et la DoD, recopiés mot pour mot, sans le plan de l'auteur.
Pré-vol
une fois par lot0Le pré-volHuit contrôles, puis un seul lot de questions. Un contrôle qui échoue arrête tout, avant la première branche.cléAskUserQuestion ×1.claude/state/go-dev-SVU-8.json
- Les agents
ticket-tracker-notion:read-backlogetwrite-backlogsont chargés. go-dev n'appelle jamais Notion en direct. gh auth status --hostname github.comrépond, pour le repo nommé dans leCLAUDE.md.- L'ordre du lot : les US de la Feature en
Prête (DoR)ouBacklog, triées parBloqué par. Un cycle de dépendances arrête tout. Une US bloquée hors du lot sort du lot. - Chaque fiche relue (
get_ticket). Des critèresAC-nnumérotés sont la seule exigence dure. Sans DoD, la story prend la DoD minimale. Des sections techniques vides disent que tech-shaper n'est pas passé. docs/feature-shaper/SVU-8-*.mdetdocs/tech-shaper/SVU-8-*.mdsont présents. Absents, c'est une question, pas un arrêt.git status: seulsdocs/et.claude/state/peuvent être modifiés. Le reste bloque la création des branches.- Un seul appel
AskUserQuestion: l'ordre du lot, les documents manquants, le dossier sale, la base, les questions ❓ du RFC, les agents de revue, les valeurs non tranchées. Ensuite, plus aucune question. - Première écriture de
.claude/state/go-dev-SVU-8.json: l'ordre, les titres, les US écartées.
.claude/state/go-dev-SVU-8.json, lot du 2026-10-21"feature": "SVU-8",
"base": "dev",
"ordre": ["SVU-21", "SVU-22"],
"documents": ["docs/feature-shaper/SVU-8-guide-installation.md",
"docs/tech-shaper/SVU-8-guide-installation.md"]Cycle d'une story
rejoué pour chaque story — l'exemple suit SVU-221La branche, puis la ficheLa branche se crée avant tout, plan compris. La fiche se lit ensuite en entier, depuis le résultat du pré-vol.clégit switch -c feat/svu-22-… origin/dev
git fetch origin dev && git switch -c feat/svu-22-copier-une-commande-d-un-clic origin/dev- Le préfixe
feat/est imposé par la règle de push. Le slug ne porte que des minuscules, des chiffres et des tirets. Une branche qui existe déjà est reprise. - Dans la fiche : le TL;DR, chaque
AC-n, la recette, le périmètre fermé, les contraintes et le contexte technique, le plan de test, la DoD, l'UX concernée.
Story 2/2 — SVU-22 — branche feat/svu-22-copier-une-commande-d-un-clic créée.
5 ACs à couvrir. Hors-scope : bouton « tout copier », message de confirmation, mesure d'usage.
develop, jamais main, qui part en production. Les règles du module (Zod, Server Actions, @@schema, aucun secret) se lisent dans le CLAUDE.md avant le plan.2Le planskills de stackgarde-fougo-dev lit le RFC, le code, les skills et les écrans, puis affiche son plan. Il ne vous le soumet pas.clédocs/tech-shaper/docs/CODEMAPS/.claude/skills/project/*.dc.html
- Le RFC (partie 1 de
docs/tech-shaper/SVU-8-*.md), une fois par lot : architecture, points de test, contrats, contraintes. - Le code, avec
GlobetRead: les fichiers à créer et à modifier, les conventions de la zone, les risques (auth, migrations, chemins critiques). - Les skills de stack : la
descriptionde chaque skill de.claude/skills/. Il retient celles que le plan touche, sans charger leur corps. - Les écrans : chaque planche de « UX concernée », lue par l'outil
Artifact(path=project/svu-8-guide-installation-copie.dc.html), pluscanvas.jsonetdonnees.json. Il traduit la maquette avec les composants du projet. Il ne recopie pas le HTML. - Le plan affiché : 3 à 7 étapes, les fichiers de chaque étape, les tests rattachés aux
AC-net aux points de test, les skills retenues, les risques, la complexité.
3En coursLe statut change avant la première ligne de code, et remonte jusqu'à l'Epic.cléstatus = "En cours"
write-backlog·save_ticket:status = "En cours"sur la fiche.write-backlog·add_comment: la branche, le plan en deux ou trois lignes, les AC à couvrir.- La remontée :
list_ticketssur la Feature, puis sur l'Epic. Un enfant démarré met le conteneurEn cours. Tous les enfantsTerminéle mettentTerminé. Un conteneur n'est jamaisEn revue, et n'est réécrit que si son statut change. .claude/state/backlog.jsonest fusionné avec les statuts relus.
4Le TDD, critère par critèreskills de stackgarde-fouPour chaque AC-n, dans l'ordre : un test rouge, le code minimal, un commit.clétest rouge → code → commit (AC-n)
- Écrire le test au point de test du RFC. « Étant donné / Quand / Alors » devient « préparer / agir / vérifier ».
- Le lancer et le voir échouer. Un test qui passe d'emblée est faux : il se corrige avant tout code.
- Écrire le minimum de code pour le faire passer. Rien d'autre : ni fonctionnalité en plus, ni refactoring.
- Relancer le test, puis toute la suite.
- Un commit par AC. Le format vient du
CLAUDE.md, ici la skillcommit-conventions. Un refactoring se commite à part. - Les tests dus par la politique (
nextjs-tests-and-gates) s'écrivent aussi, même si aucun critère ne les demande. - Avant d'écrire dans une zone couverte par une skill de stack, go-dev lit la règle précise qui la couvre.
git log de la branche de SVU-22a153b1a feat(copier): ajouter la logique de copie dans le presse-papiers (AC-2, AC-4) 71340cb feat(copier): ajouter le bouton Copier, seul composant client (AC-1, AC-5) 52cc434 feat(copier): poser un bouton Copier sur chaque bloc de commandes (AC-2) journal d'écarts : - Transitions d'état non testées automatiquement (dérogation RFC), vérifiées à la main
5La Definition of Donegarde-fouChaque case se coche avec sa preuve collée à côté. Celui qui a écrit les critères n'est pas celui qui les coche.clénpm run check
- Deux garanties que rien ne désactive : chaque AC a un test qui passe, et le corps de la fiche décrit ce qui est livré.
- La DoD écrite par tech-shaper, ligne à ligne : une sortie de commande, un test, une capture.
- Les contrôles du projet, lus dans le
CLAUDE.md:npm run check(eslint, tsc,next build, vitest). Aucun seuil inventé : go-dev donne la valeur mesurée. - Une case qu'il ne peut pas corriger dans le périmètre reste non cochée, expliquée dans la PR et au journal.
- [x] npm run check vert — 4 fichiers de test, 34 tests passés - [x] Le seul 'use client' du projet est dans BoutonCopier — grep -rn "use client" app components lib : components/BoutonCopier.tsx:1 - [x] Poids de la route /installation, sans seuil — +499 octets de JavaScript
npm run verifier (typage, lint, tests, build, conformité), la même que la CI. Si la conformité refuse du code, c'est le code qui change : jamais le contrôle, ni src/proxy.ts, Dockerfile*, deploy/, .github/.6La revue, avant la PRskills de stackgarde-fouDeux sous-agents à contexte neuf relisent le diff en parallèle. Ils ne voient jamais le plan de l'auteur.clégit diff dev...HEAD2 sous-agents
- Le diff fixé :
git rev-parse devrésout,git diff dev...HEAD --statn'est pas vide. Les sous-agents lisent eux-mêmesgit diff dev...HEADetgit log dev..HEAD --oneline. - Conventions : le diff contre le
CLAUDE.md, les skills de stack retenues (par leur chemin) et la liste de défautscode-review-baseline.md. Moins de 400 mots. Ses retours vont dans la PR, sans correction. - Conformité : le diff contre les
AC-n, le périmètre fermé et la DoD, collés mot pour mot. Moins de 400 mots. - La recette de la PR part de la
## Recettede la fiche. Elle ajoute la commande de lancement exacte, l'AC de chaque étape et le test qui la couvre déjà, puis ce qui doit rester inchangé. - Les zones sensibles :
git diff dev...HEAD --name-onlycomparé à la ligneZones sensibles :duCLAUDE.md. Dans le doute, la PR est sensible.
En cours.CLAUDE.md (ici : hébergement, CI/CD, secrets) se comparent au diff, par chemin et par contenu. Dans le doute, la PR est sensible : un faux positif coûte une lecture.7La pull requestgarde-fouUne PR par story, vers la base. Son titre est la clé qui la relie à sa fiche.clégh pr create[SVU-22] Copier une commande d'un clic
git push -u origin HEAD, puisgh pr create --base dev, avec le modèlepr-template.md: Ticket, Pourquoi, Ce qui est livré, Couverture des AC, DoD, À vérifier sur l'app, Périmètre fermé, Risques.- Le titre commence par
[SVU-22], casse comprise.[svu-22]ne serait pas retrouvé en phase 10. - PR en draft (
--draft) si un retour de conformité a survécu. PR sensible : un encart en tête et--label revue-humaine-requise, créé une fois s'il manque. save_ticket:status = "En revue"(une PR en draft laisseEn cours) etpr_url, ajoutée à la colonnePR. Puis la remontée, puis un commentaire avec l'URL.- Si le
CLAUDE.mddéclare un agent de revue externe (CodeRabbit), un sous-agent l'attend 15 minutes en arrière-plan, dans son propregit worktree. Il corrige le trivial et laisse le reste à un humain. Le lot n'attend pas.
[SVU-22] Copier une commande d'un clic ## À vérifier fonctionnellement sur l'app Pour lancer : npm run dev, puis http://localhost:3000/installation 2. (AC-2) Cliquer l'icône du bloc « Installer », coller : 5 lignes, sans $ (texte exact couvert par tests/bouton-copier.test.tsx)
develop.8La story suivanteL'état du lot est réécrit sur disque, puis go-dev repart sans le contexte de la story précédente.clé.claude/state/go-dev-SVU-8.json
.claude/state/go-dev-SVU-8.jsonest réécrit en entier : par story, la branche, la PR, le draft, le statut, la DoD X/Y, les zones sensibles, l'agent de revue lancé, le journal d'écarts,debut,finetpasses_correction.- Ce qui se garde : les réponses du pré-vol, le RFC, les conventions, les skills retenues, la politique de test. Ce qui se jette : le plan, les AC, les fichiers et les retours de revue de la story finie.
- La suivante est-elle encore éligible ? Un bloquant du lot compte dès que sa PR est ouverte. La PR suivante est alors empilée sur la sienne.
- Le lot s'arrête sur l'un des trois arrêts, sur deux stories de suite en draft, ou si vous l'interrompez. Le fichier d'état permet de reprendre à la story suivante.
"pr": ".../pull/13", "base_pr": "feat/svu-21-… (PR empilée)", "dod": "8/8", "journal_ecarts": ["PR empilée sur #12 car dépendance US1 non encore mergée dans dev", …]
Clôture
une fois le lot fini9Le rapport de lotLe seul moment où go-dev vous rend la main. Le rapport se lit dans le fichier d'état, rien n'est reconstruit de mémoire.clérapport de lot
- Trois lignes d'abord : ce qui est livré, ce qui demande une décision, ce que vous devez faire.
- Le statut de la Feature et de l'Epic, relu dans Notion. Un conteneur en retard est rattrapé ici.
- Le tableau du lot : Story, Titre, PR, Statut, DoD, Sensible, Revue de code, Écarts.
- Les stories écartées, le journal d'écarts consolidé, puis les décisions, en commençant par les PR sensibles.
- La suite est nommée, jamais lancée : relire chaque PR en suivant sa recette, merger, puis la phase 10.
| SVU-22 | Copier une commande d'un clic | #13 | En revue | 8/8 | — | lancée | PR empilée sur #12 |
10La réconciliationgarde-fougo-dev ne merge pas. Après vos merges, cette phase aligne Notion sur GitHub. Elle se lance aussi seule.clégh pr list --search "SVU-22 in:title"
gh pr list --search "SVU-22 in:title" --state all --json number,title,state,isDraft,url. C'est GitHub qui fait foi, pas le fichier d'état.- PR mergée →
Terminé. Ouverte →En revue. Draft →En cours. Fermée sans merge →En cours, et c'est signalé. Aucune PR → rien n'est écrit. Une story à plusieurs PR n'estTerminéque si toutes sont mergées. - Une fiche
TerminéouDémontréne recule jamais. La remontée est recalculée même si aucune US n'a bougé. - Les codemaps :
git checkout -b chore/codemaps-svu-8 origin/dev, l'agentboucle:codemap-updater, puis la PR[SVU-8] Codemaps à jour. - Un Epic qui vient de passer
Terminé: go-dev propose la revue de sécurité, sans jamais la lancer.Démontrése pose à la main, après la démo.
git log de devdc0fd26 docs: codemaps à jour après SVU-8
revue-humaine-requise, la proposition nomme les zones touchées.11La revue de sessionUne revue par lot, pour la rétro. Elle ne bloque jamais.clédocs/kaizen/sessions/…
- L'agent
meta:kaizen-reviewerreçoit une checklist fermée et le journal d'écarts consolidé. - Sa réponse est écrite telle quelle dans
docs/kaizen/sessions/2026-10-21-go-dev-SVU-8.md. /kaizenlit ces fichiers pour proposer des changements auCLAUDE.mdet aux skills du projet.
Qui relit le code
Le TDD se certifie lui-même : le même agent a écrit le test et le code. Aucun de ces relecteurs n'est l'agent qui a écrit le code, et seul un humain merge.
| Qui | Quand | Ce qu'il regarde | S'il trouve un écart |
|---|---|---|---|
| Le relecteur de conformitéun sous-agent neuf | phase 6 | Le diff contre la fiche : les critères AC-n, le périmètre fermé et la DoD, collés mot pour mot. Il ne voit jamais le plan de l'auteur. | Bloquant. Retour en phase 4 sur l'AC, test rouge d'abord. Deux passes au plus, puis la PR part en draft et la fiche reste En cours. |
| Le relecteur des conventionsun sous-agent neuf | phase 6 | Le diff contre le CLAUDE.md, les skills de stack retenues en phase 2 et une liste de défauts de conception (Refactoring, de Martin Fowler). Ce que le lint vérifie déjà est ignoré. | Consultatif. Chaque retour devient une ligne « Risques et points d'attention » de la PR. Sauf un secret, une donnée personnelle ou une dépendance non déclarée : corrigés tout de suite. |
| L'agent de revue externeCodeRabbit, si le repo l'a | phase 7arrière-plan | La PR ouverte, comme il le fait sur toute PR du repo. Un sous-agent attend ses retours 15 minutes, dans son propre git worktree. | Le trivial est corrigé et son fil résolu. Le reste, et tout fichier sensible, reste ouvert pour vous. Jamais sur une PR en draft. |
| Vousle Builder, sur chaque PR | après la phase 9 | La PR en suivant sa recette : la commande pour lancer, les étapes à observer, ce qui doit rester inchangé. go-dev ne merge jamais. | Une PR sensible porte le label revue-humaine-requise et un encart en tête qui nomme les zones et les fichiers : celle-là se lit de près. |
La revue de sécurité de l'Epicepic-security-review | phase 10proposée | Toutes les PR mergées de l'Epic, par deux sous-agents neufs : le code applicatif, puis la surface (secrets, dépendances, configuration, CI/CD). | Seuls les findings sûrs, au chemin tracé, vous sont soumis un par un. Chacun retenu devient une user story, sous une Feature « Sécurité — <Epic> ». |
La revue de sécurité a sa propre étape dans la chaîne : voir sa carte.
Ce qui change en mode epic-run
Avec epic-run, go-dev développe toute une Epic sans vous, la nuit par exemple. Les phases restent les mêmes : seuls ces six points changent. Vous reprenez la main le lendemain, sur une seule PR.
- Une branche d'EpicLe run crée
feat/epic-svu-38-focus-developpementdepuisdev. Chaque story part de cette branche, et sa PR la vise, au lieu dedev. - go-dev merge lui-mêmeRevue et DoD au vert, il fusionne la PR de story dans la branche d'Epic, en squash. Jamais ailleurs, et jamais une PR en draft.
- Le contrat de run remplace les questionsLe Builder a tout tranché la veille dans
docs/run/SVU-38-….md: le périmètre, l'ordre, les réponses, le budget de 8 heures. Le pré-vol ne fait plus que vérifier, en une minute. - Les arrêts deviennent des mises de côtéLa story s'arrête avec sa question écrite, et le run passe à la suivante. Seuls une connexion perdue, deux drafts de suite ou le budget épuisé arrêtent tout.
- La revue de sécurité se lance seuleSi le contrat le dit, elle tourne en fin de run sur la branche d'Epic. Ses findings attendent votre validation : rien ne s'écrit dans Notion sans vous.
- La PR de l'Epic est la porte humaineElle vise
dev, jamais en draft, jamais mergée par l'agent. Sa description est un guide de revue, un fil de relecture est ancré sur chaque zone sensible, et le cahier de test s'ouvre sur le compte-rendu du run.
dev est le vôtre.