BriarForge/dev-grill-spec-driven

Grillade, puis développement piloté par spécifications

Deux workflows exécutés l'un après l'autre, avec une seule transition entre eux :

1. Grillade (Matt Pocock, grill-me → to-spec) : interrogez l'utilisateur sous forme d'arbre de conception, tour par tour, jusqu'à ce que rien ne soit supposé silencieusement. Synthétisez ensuite la compréhension convenue dans une spécification sans poser de nouvelles questions.
2. Construction (DeepLearning.AI + JetBrains, Développement piloté par spécifications avec des agents de codage) : la spécification atterrit dans le dépôt sous forme de requirements.md, plan.md et validation.md dans un dossier daté, est implémentée groupe de tâches par groupe de tâches sur sa propre branche, validée par rapport à validation.md, enregistrée dans le journal des modifications, fusionnée, et la feuille de route est replanifiée.

La grillade remplace l'entretien fixe à trois questions du cours SDD (Périmètre / Décisions / Contexte) par un entretien complet en arbre de conception. Le cours SDD remplace la « publication dans le gestionnaire de tickets » de to-spec par des fichiers de spécifications qui vivent à côté du code et évoluent avec lui.

Aperçu

À utiliser lorsqu'un changement est suffisamment important pour qu'écrire d'abord soit moins coûteux que de le refaire : une nouvelle fonctionnalité, une phase de feuille de route, un sprint MVP, ou l'ajout de SDD à une base de code existante. Ignorez-le pour les corrections d'une seule ligne, et pour les simples chasses aux bugs (utilisez pstack-engineering pour les causes profondes).

Phrases de déclenchement : « grill me then spec it », « grill to spec », « spec-driven », « SDD », « feature spec », « work on the next phase », « start the next feature ».

Barrières strictes (ne jamais sauter) :

• Aucun fichier de spécification n'est écrit tant que l'utilisateur n'a pas confirmé que la grillade a atteint une compréhension partagée (Porte A).
• Aucun code n'est écrit tant que l'utilisateur n'a pas approuvé les fichiers de spécification (Porte B).
• Rien n'est fusionné jusqu'à ce que chaque élément de validation.md soit validé (Porte C).

Instructions d'exécution

Résolvez SPECS=${SDD_SPECS_DIR:-specs} et BASE=${SDD_BASE_BRANCH:-<branche par défaut du dépôt>} au début. Les chemins ci-dessous sont relatifs à la racine du projet.

Étape 0 — S'orienter (les faits sont votre devoir)

1. Lisez les fichiers AGENTS.md / CLAUDE.md, README.md du projet, ainsi que tout glossaire ou ADR. Suivez les propres règles git du dépôt (wrappers, nommage des branches, pas de force-push).
2. Vérifiez l'existence d'une constitution : $SPECS/mission.md, $SPECS/tech-stack.md, $SPECS/roadmap.md.
   • Tous présents → passez à l'étape 1 pour la prochaine fonctionnalité.
   • Manquants, nouveau projet → la première grillade porte sur la constitution elle-même (mission, public cible, lacunes de la pile technique). Son résultat est les trois fichiers, avec roadmap.md divisé en phases très petites, chacune livrable indépendamment.
   • Manquants, base de code existante (héritée) → explorez d'abord le code et rédigez la constitution à partir de ce qui existe réellement (pile, conventions, fonctionnalités livrées comme phases achevées), puis grillez uniquement les lacunes et la feuille de route future.
3. Si l'utilisateur n'a pas nommé de fonctionnalité, la cible est la phase suivante : la première section de la feuille de route dont tous les éléments sont décochés ([ ]).
4. Explorez le code que la fonctionnalité touchera. Ne posez jamais à l'utilisateur une question à laquelle le dépôt, les outils ou la documentation peuvent répondre. Déléguez l'exploration large à un sous-agent frais si le harnais en possède un, et ne bloquez pas les questions sans rapport.

Étape 1 — Grillade (entretien en arbre de conception)

Interviewez l'utilisateur sans relâche jusqu'à la compréhension partagée. Traitez le plan comme un arbre de conception : chaque décision bifurque vers les décisions qui en dépendent.

• Travaillez par tours. La frontière est chaque décision ouverte dont les prérequis sont déjà réglés. Posez toute la frontière en un tour, puis attendez.
• Numérotez chaque question et donnez votre réponse recommandée. Formulez-la de sorte que « oui » accepte la recommandation.
• Une question qui dépend d'une autre question encore ouverte ce tour appartient à un tour ultérieur.
• Couvrez, à travers les tours, au moins les axes SDD : Périmètre (ce qu'il collecte, expose, fait ; forme des données), Décisions (stockage, visibilité, validation, motif UX, architecture), Contexte (ton, contraintes, limites de la pile, questions ouvertes) et Points de test : où la fonctionnalité sera testée. Préférez les points de test existants et le plus haut possible ; l'idéal est un seul.
• Les nouvelles dépendances, les changements de schéma et les changements d'API publique sont toujours des questions explicites, jamais des hypothèses (tech-stack.md est l'autorité).

Format du tour :

❓ **Q1** - **<titre>** : <question, options le cas échéant>

➡️ <réponse recommandée>

---

❓ **Q2** - ...

Si le harnais dispose d'un outil de question structuré (Claude Code AskUserQuestion), vous pouvez l'utiliser pour des tours allant jusqu'à quatre questions à choix multiples ; sinon, utilisez le format texte ci-dessus.

La grillade se termine lorsque la frontière est vide. Résumez les décisions arrêtées dans une courte liste et demandez à l'utilisateur de confirmer.

Porte A : ne continuez pas tant que l'utilisateur n'a pas confirmé le résumé.

Étape 2 — Vers la spécification (synthèse, pas de nouvelles questions)

Convertissez la conversation en spécification. N'interviewez pas à nouveau ; si un véritable écart apparaît, cela signifie que la grillade a manqué une branche : posez uniquement cette question, puis reprenez.

1. Créez la branche à partir de $BASE : phase-<N>-<nom-en-kebab> pour une phase de la feuille de route, sinon feature/<nom-en-kebab> (ou la propre convention du dépôt).
2. Relisez $SPECS/mission.md et $SPECS/tech-stack.md, ainsi que les spécifications de fonctionnalités existantes pour le style de la maison.
3. Créez $SPECS/YYYY-MM-DD-<nom-de-la-fonctionnalité>/ avec la date du jour et rédigez les trois fichiers à partir de references/spec-templates.md :
   • requirements.md — le contenu to-spec (problème, solution, une liste numérotée exhaustive de récits utilisateur, décisions d'implémentation, décisions de test, hors périmètre) plus les sections SDD Périmètre / Décisions / Contexte. Pas de chemins de fichiers ni d'extraits de code, sauf un extrait de prototype réduit qui ancre une décision plus précisément qu'en prose.
   • plan.md — groupes de tâches numérotés, chacun implémentable et testable indépendamment, avec des sous-tâches numérotées.
   • validation.md — vérifications automatisées (commandes exactes), procédure manuelle, cas limites, vérification du ton pour le texte destiné à l'utilisateur, et une Définition du Terminé.
4. Optionnellement, si l'utilisateur le demande ou si le dépôt suit le travail dans des tickets : publiez également les exigences sous forme de ticket (gh issue create) et liez-le depuis requirements.md.
5. Montrez à l'utilisateur les trois fichiers (chemins plus un court résumé).

Porte B : attendez l'approbation. Les retours (« ajouter un groupe de tâches pour X », « les composants vont dans leurs propres fichiers ») sont appliqués à la spécification d'abord, et chaque fichier est maintenu synchronisé.

Étape 3 — Implémenter

1. Implémentez les groupes de tâches dans l'ordre. Après chaque groupe : exécutez les tests du projet et la vérification de types, validez avec un message nommant le groupe, cochez ses cases dans plan.md.
2. Si l'implémentation montre que la spécification était erronée ou incomplète, mettez à jour la spécification dans le même commit que le code qui s'en écarte. Les spécifications et le code ne dérivent jamais.
3. Les groupes sans dépendance entre eux peuvent être confiés à des sous-agents parallèles (chacun dans son propre répertoire de travail ; suivez les règles du répertoire de travail de l'hôte), fusionnés par vous.
4. Pas de nouvelles dépendances sans l'approbation de l'utilisateur, même si un groupe en « a besoin ».

Étape 4 — Valider

1. Exécutez chaque vérification automatisée dans validation.md et collez la sortie réelle.
2. Parcourez les vérifications manuelles (pour une UI, pilotez-la réellement : automatisation du navigateur ou captures d'écran, pas « devrait fonctionner »).
3. Révision approfondie optionnelle : générez des réviseurs de trois perspectives (exactitude, conformité à la spécification, maintenabilité) sur le diff de la branche, puis corrigez ce qui bloque.
4. Demandez à l'utilisateur si la spécification doit être clarifiée à la lumière de ce qui a été construit.

Porte C : chaque élément de la Définition du Terminé est validé, ou l'utilisateur en renonce explicitement à un (enregistrez la renonciation dans validation.md).

Étape 5 — Boucler la boucle

1. Marquez la phase comme terminée dans $SPECS/roadmap.md ([x]).
2. Mettez à jour CHANGELOG.md (# Changelog, en-têtes ## YYYY-MM-DD avec les plus récents en premier, une puce par changement significatif depuis la dernière date enregistrée). Utilisez une compétence changelog du projet si elle existe.
3. Validez, passez à $BASE, fusionnez la branche, supprimez-la, poussez selon les règles du dépôt.
4. Replanifiez : demandez si quoi que ce soit appris modifie mission.md, tech-stack.md ou la feuille de route (fusionnez, divisez ou réordonnez les phases). Les décisions transversales (par exemple « utiliser Vitest », « UI réactive ») vont dans tech-stack.md / mission.md et sont rétroportées dans les spécifications existantes.
5. Proposez la phase suivante : elle recommence à l'étape 1.

Variables d'environnement

Variable	Défaut	Description
SDD_SPECS_DIR	specs	Répertoire de la constitution et des spécifications de fonctionnalité, relatif à la racine du projet
SDD_BASE_BRANCH	branche par défaut du dépôt	Branche à partir de laquelle les fonctionnalités sont créées et dans laquelle elles sont fusionnées

Liste de vérification

• La constitution existe (mission.md, tech-stack.md, roadmap.md) avant toute spécification de fonctionnalité
• Chaque question de grillade a été posée avec une réponse recommandée ; aucun fait n'a été demandé auquel le dépôt pouvait répondre
• L'utilisateur a confirmé le résumé des décisions (Porte A) avant l'écriture de tout fichier de spécification
• requirements.md, plan.md, validation.md existent sous $SPECS/YYYY-MM-DD-<nom>/ sur une branche de fonctionnalité
• L'utilisateur a approuvé la spécification (Porte B) avant l'écriture du code
• Chaque groupe de tâches validé avec les tests réussis ; cases du plan cochées
• Spécification mise à jour chaque fois que l'implémentation s'en est écartée
• Toutes les vérifications de validation.md exécutées avec une sortie réelle (Porte C)
• Phase de la feuille de route cochée, journal des modifications mis à jour, branche fusionnée et supprimée
• Question de replanification posée

Pièges connus

• Griller indéfiniment. La grillade se termine lorsque la frontière est vide, pas quand vous manquez de curiosité. Ne reposez pas les décisions réglées ; ne demandez pas de détails qui relèvent de la revue de code.
• Interviewer pendant la phase vers la spécification. L'étape 2 synthétise ; de nouvelles questions signifient que la grillade était incomplète. Posez la question manquante, pas une deuxième interview.
• Écrire avant les Portes A/B. Le cours SDD est explicite : rien n'est écrit sur le disque tant que l'entretien n'est pas répondu. Le code avant l'approbation des spécifications défait la méthode.
• Phases trop grandes. Une phase qui ne peut pas être revue en une seule séance devrait être divisée dans la feuille de route avant la spécification.
• Dérive des spécifications. Un changement demandé pendant l'implémentation est appliqué d'abord à la spécification, puis au code. Une spécification qui ne correspond plus au code est pire qu'absente.
• Chemins de fichiers dans les exigences. Ils pourrissent vite ; décrivez plutôt les modules et les interfaces (les chemins appartiennent tout au plus aux sous-tâches de plan.md).
• Les règles du dépôt priment. Les noms de branches, les wrappers de push, les emplacements des répertoires de travail et les règles d'attribution provenant de AGENTS.md du dépôt remplacent les valeurs par défaut ici.

Voir references/spec-templates.md pour les modèles de fichiers et references/sources.md pour l'origine de chaque partie.