14 KiB
epic-devteam — Workflow TDD multi-agent piloté par OpenSpec
epic-devteam est une équipe d'agents IA qui transforme un besoin exprimé en langage naturel en code testé et relu. Le workflow suit deux principes :
- OpenSpec comme source de vérité : chaque évolution commence par un changement OpenSpec (proposition, spécifications, conception, tâches) validé par vous avant toute ligne de code.
- TDD strict (Red → Green → Refactor) : les tests sont écrits d'abord, à partir de la spécification, par un agent dédié. Ils sont ensuite figés par un commit, et l'implémentation n'a pas le droit d'y toucher.
Chaque rôle (concevoir, tester, implémenter, relire) est tenu par un agent distinct, avec des permissions limitées. Ce cloisonnement empêche un agent de « tricher », par exemple en modifiant un test pour le faire passer.
Le workflow fonctionne avec Claude Code (.claude/agents/) et OpenCode (.opencode/agents/). Les deux jeux d'agents ont les mêmes instructions ; seuls les en-têtes (modèle, permissions) changent.
Sommaire
- Prérequis
- Installation dans un projet
- Les agents
- Les étapes du workflow
- Utilisation
- Bonnes pratiques et pièges
- Structure du dépôt
Prérequis
| Dépendance | Rôle | Vérification |
|---|---|---|
| OpenSpec CLI (v2.x) | Gestion des changements et des specs, utilisée par les skills openspec-* |
openspec --version |
| git | Commit de la phase rouge et contrôle d'intégrité des tests | git --version |
| Claude Code ou OpenCode | Exécution des agents | claude --version / opencode --version |
Installer OpenSpec
npm install -g @fission-ai/openspec@latest
openspec --version
Important
: les agents ne fonctionnent pas sans OpenSpec. L'architecte s'appuie sur les skills
openspec-exploreetopenspec-propose, le développeur suropenspec-apply-change, et l'archivage final suropenspec-archive-change. Ces skills appellent la CLIopenspec, qui doit donc être dans lePATH.
Installation dans un projet
-
Initialiser OpenSpec à la racine du projet cible :
cd mon-projet openspec initSélectionnez Claude Code et/ou OpenCode comme outils. La commande crée :
openspec/:config.yaml,specs/(specs durables) etchanges/(changements en cours et archivés) ;.agents/skills/openspec-*: les skills OpenSpec, liés dans.claude/skills/pour Claude Code.
-
Copier les agents de ce dépôt :
# Claude Code cp -r epic-devteam/.claude/agents mon-projet/.claude/ # OpenCode cp -r epic-devteam/.opencode/agents mon-projet/.opencode/ -
(Optionnel) Renseigner
openspec/config.yaml: ajoutez les contraintes que les agents ne peuvent pas déduire du code (langue des artefacts, plateformes cibles, règles par artefact, etc.). -
(Optionnel) Ajuster les modèles dans l'en-tête de chaque agent (voir Les agents).
Vous n'avez pas besoin de créer ARCHITECTURE.md ni TDD.md vous-même : l'architecte les fait générer par @repo-scout au premier lancement.
Les agents
| Agent | Rôle | Phase | Peut modifier | Modèle Claude Code | Modèle OpenCode |
|---|---|---|---|---|---|
architect |
Chef d'orchestre : spécifie avec vous, délègue, valide lui-même chaque phase en lançant les tests | Toutes | Specs OpenSpec, AGENTS.md |
inherit |
glm-5.3 |
repo-scout |
Analyse le dépôt : pile, conventions, commandes | Préparation | ARCHITECTURE.md, TDD.md uniquement |
sonnet |
glm-5.3 |
test-writer |
Écrit les tests rouges à partir de la spec, puis les commite | Rouge | Tests + squelettes vides | haiku |
glm-5.3-flash |
developer |
Implémente le code de production jusqu'au vert | Vert / Refactor | Code de production (jamais les tests) | haiku |
glm-5.3-flash |
code-reviewer |
Vérifie l'intégrité des tests, relit le code et propose des refactors | Refactor | Rien (lecture seule) | sonnet |
glm-5.3 |
diff-summarizer |
Résume un diff existant pour une prise de contexte rapide | Au besoin | Rien | haiku |
glm-5.3-flash |
architect — l'orchestrateur
C'est le seul agent avec lequel vous dialoguez. Il :
- explore le besoin avec vous (
openspec-explore), puis rédige le changement (openspec-propose) ; - n'écrit jamais de code, mais exécute lui-même les tests pour constater le rouge, le vert et le maintien du vert ;
- conserve le hash du commit de la phase rouge, qui sert de référence d'intégrité des tests ;
- arbitre les désaccords (un test jugé incorrect par le développeur repart vers
test-writer, jamais versdeveloper) ; - propose l'archivage du changement à la fin.
Il doit tourner en session principale, car seul l'agent principal peut déléguer à des sous-agents.
repo-scout — la cartographie
Il produit et tient à jour deux fichiers à la racine du dépôt, que tous les autres agents utilisent :
ARCHITECTURE.md: pile détectée (avec fichiers de preuve), conventions, points chauds, patterns à faire et à éviter ;TDD.md: commandes exactes pour lancer toute la suite, un test isolé, les linters et vérificateurs de types, plus l'organisation des tests.
Il n'installe rien et n'accède pas au réseau.
test-writer — la phase rouge
- Vérifie que la base est verte (tous les tests existants passent). Si elle ne l'est pas, il n'écrit rien et alerte l'architecte.
- Écrit des tests boîte noire (via les interfaces publiques), positifs et négatifs, dont les valeurs attendues viennent de la spec.
- Ajoute au besoin des squelettes vides pour que le code compile (langages typés), sans aucune logique.
- Vérifie que chaque nouveau test échoue pour la bonne raison (pas pour une erreur d'import ou de syntaxe).
- Commite uniquement ses fichiers avec un message
test: …et transmet le hash.
developer — la phase verte
- Implémente via le skill
openspec-apply-change, en prenant les tests comme critère d'acceptation. - Interdiction absolue d'ajouter, modifier, désactiver ou affaiblir un test.
- Pas de triche : il ne doit ni détecter les tests, ni coder en dur les valeurs attendues.
- Respecte YAGNI et les conventions du dépôt, et lance linters et vérificateurs de types avant de déclarer avoir terminé.
- Ne commite pas : c'est vous qui gérez les commits d'implémentation.
code-reviewer — la phase refactor
- Contrôle bloquant :
git diff <hash-rouge> -- <fichiers de tests>doit être vide. - Vérifie la conformité au changement OpenSpec (objectifs, périmètre, non-objectifs).
- Relit l'exactitude, la robustesse et la sécurité de base.
- Propose des refactors sans changement de comportement (lisibilité, duplication, nommage).
- Signale les scénarios à risque qui ne sont pas couverts, pour qu'un test complémentaire soit écrit.
Il ne produit que des demandes de modification actionnables (quoi, pourquoi, où) ou une approbation.
diff-summarizer — l'utilitaire
Appelé par l'architecte quand des modifications existent déjà (copie de travail, diff de PR). Il renvoie un résumé court au format type / scope / summary / files.
Les étapes du workflow
Vous ──► @architect
│
A. Skills │ chargement des skills pertinents pour la pile
│
B. Spec │ openspec-explore ⇄ openspec-propose
│ ──► openspec/changes/<nom-du-changement>/
│ (proposal.md, specs/, design.md, tasks.md)
│
▼ ⛔ attend le mot « approuvé »
C.0 Prép. │ @repo-scout ──► ARCHITECTURE.md + TDD.md
│
C.1 ROUGE │ @test-writer : base verte ? ─non─► stop, décision avec vous
│ └─oui─► tests rouges ──► commit `test: …` (hash H)
│ @architect vérifie lui-même le rouge
│
C.2 VERT │ @developer : implémente jusqu'au vert (tests intouchables)
│ @architect vérifie le vert + aucun test modifié depuis H
│
C.3 REFAC │ @code-reviewer : intégrité vs H, revue, demandes de refactor
│ └─► @developer applique ──► @architect revérifie le vert
│ (boucle jusqu'à l'approbation du reviewer)
│ (test manquant ? ──► retour à @test-writer, puis C.2)
│
D. Retour │ résumé, compromis, suggestion d'archivage
▼
openspec-archive-change ──► openspec/specs/ mis à jour
A. Découverte des skills
Chaque agent charge les skills disponibles qui correspondent à la pile du projet et indique lesquels il a chargés. S'il n'en trouve aucun, il continue avec ses connaissances générales.
B. Spécification (OpenSpec)
- Exploration quand le besoin est flou : questions ciblées, une ou deux à la fois.
- Proposition quand l'intention est claire : création de
openspec/changes/<nom>/avec proposition, delta de specs, conception et tâches. - L'architecte peut passer d'un mode à l'autre et vous dit toujours dans lequel il se trouve.
- Porte de validation : l'implémentation ne démarre que sur le mot exact « approuvé ». Une formule comme « ok » ou « vas-y » ne suffit pas.
C. Boucle TDD
| Étape | Qui agit | Qui valide | Condition de sortie |
|---|---|---|---|
| 0. Préparation | repo-scout |
architect |
ARCHITECTURE.md et TDD.md existent et sont fiables |
| 1. Rouge | test-writer |
architect (exécute les tests) |
Nouveaux tests en échec, anciens au vert, commit test: créé |
| 2. Vert | developer |
architect (exécute les tests + contrôle du diff des tests) |
Suite entièrement verte, tests inchangés depuis le hash rouge |
| 3. Refactor | code-reviewer → developer |
architect (revalide après chaque application) |
Approbation du reviewer, vert maintenu |
D. Retour et archivage
L'architecte résume ce qui a été fait et les éventuels écarts, puis propose openspec-archive-change. Cette commande fusionne le delta de specs dans openspec/specs/ et déplace le changement dans openspec/changes/archive/.
Utilisation
Lancer l'architecte
Claude Code : l'architecte doit être l'agent principal de la session.
claude --agent architect
OpenCode : architect est déclaré mode: primary. Sélectionnez-le comme agent principal au démarrage de la session.
Exemple de session
Vous > Je veux ajouter un export CSV des factures, filtrable par date.
architect > [explore] Quelques questions avant de proposer :
1. L'export doit-il inclure les factures annulées ?
2. Quel format de date en entrée ?
Vous > Non. ISO 8601.
architect > [propose] Changement `add-invoice-csv-export` créé :
proposal.md, specs/invoices/spec.md, design.md, tasks.md.
Relisez-le. Répondez « approuvé » pour lancer l'implémentation.
Vous > approuvé
architect > TDD.md absent → @repo-scout…
Phase rouge → @test-writer… 6 tests rouges, commit a1b2c3d.
Rouge vérifié. Phase verte → @developer…
Vert vérifié, tests intacts depuis a1b2c3d.
Revue → @code-reviewer : 2 refactors demandés… appliqués, vert maintenu.
Approuvé par le reviewer. Résumé : … Archiver le changement ?
Reprendre ou ajuster un changement
- Pour modifier la spec en cours de route, demandez-le à l'architecte. Il utilisera
openspec-update-changeet redemandera votre approbation si les décisions changent. - Pour synchroniser les specs sans archiver : skill
openspec-sync-specs. - Les changements en cours se trouvent dans
openspec/changes/et peuvent être repris dans une nouvelle session.
Bonnes pratiques et pièges
- Démarrez sur une copie de travail propre.
test-writerne commite que ses propres fichiers, mais une base propre rend le contrôle d'intégrité (git diff <hash>) beaucoup plus lisible. - Ne réécrivez pas l'historique (rebase, amend, squash) pendant un cycle : le hash du commit rouge doit rester valide jusqu'à la fin de la revue.
- Commitez l'implémentation vous-même une fois le cycle terminé :
developerne commite pas. - Ayez une base verte. Si des tests échouent déjà, la phase rouge est bloquée et l'architecte vous demandera de choisir : réparer d'abord, ignorer les échecs en le justifiant, ou abandonner.
- Relisez la proposition OpenSpec avant d'écrire « approuvé » : les tests en découlent directement, et une spec floue donne des tests flous.
- Gardez
TDD.mdexact. Si vous changez de runner ou de commandes, demandez à l'architecte de relancer@repo-scout. - Projet sans tests ?
repo-scoutl'indiquera dansTDD.md. Il faut mettre en place un runner de tests avant de pouvoir lancer la boucle TDD. - Permissions Claude Code :
.claude/settings.jsonactiveacceptEditspar défaut pour fluidifier la boucle. Adaptez ce réglage à votre niveau de confiance.
Structure du dépôt
.
├── .claude/
│ ├── agents/ # Agents pour Claude Code
│ ├── skills/ # Liens symboliques vers .agents/skills/
│ └── settings.json # Permissions par défaut (acceptEdits)
├── .opencode/
│ └── agents/ # Mêmes agents pour OpenCode (modèles OpenRouter)
├── .agents/
│ └── skills/ # Skills OpenSpec générés par `openspec init`
└── openspec/
├── config.yaml # Schéma `spec-driven` + contexte/règles optionnels
├── specs/ # Specs durables (alimentées par l'archivage)
└── changes/ # Changements en cours
└── archive/ # Changements archivés