260 lines
14 KiB
Markdown
260 lines
14 KiB
Markdown
# 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](#prérequis)
|
|
- [Installation dans un projet](#installation-dans-un-projet)
|
|
- [Les agents](#les-agents)
|
|
- [Les étapes du workflow](#les-étapes-du-workflow)
|
|
- [Utilisation](#utilisation)
|
|
- [Bonnes pratiques et pièges](#bonnes-pratiques-et-pièges)
|
|
- [Structure du dépôt](#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
|
|
|
|
```bash
|
|
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-explore` et `openspec-propose`, le développeur sur `openspec-apply-change`, et l'archivage final sur `openspec-archive-change`. Ces skills appellent la CLI `openspec`, qui doit donc être dans le `PATH`.
|
|
|
|
---
|
|
|
|
## Installation dans un projet
|
|
|
|
1. **Initialiser OpenSpec** à la racine du projet cible :
|
|
|
|
```bash
|
|
cd mon-projet
|
|
openspec init
|
|
```
|
|
|
|
Sélectionnez Claude Code et/ou OpenCode comme outils. La commande crée :
|
|
- `openspec/` : `config.yaml`, `specs/` (specs durables) et `changes/` (changements en cours et archivés) ;
|
|
- `.agents/skills/openspec-*` : les skills OpenSpec, liés dans `.claude/skills/` pour Claude Code.
|
|
|
|
2. **Copier les agents** de ce dépôt :
|
|
|
|
```bash
|
|
# Claude Code
|
|
cp -r epic-devteam/.claude/agents mon-projet/.claude/
|
|
# OpenCode
|
|
cp -r epic-devteam/.opencode/agents mon-projet/.opencode/
|
|
```
|
|
|
|
3. **(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.).
|
|
|
|
4. **(Optionnel) Ajuster les modèles** dans l'en-tête de chaque agent (voir [Les agents](#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 vers `developer`) ;
|
|
- 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
|
|
|
|
1. 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.
|
|
2. Écrit des tests **boîte noire** (via les interfaces publiques), positifs et négatifs, dont les valeurs attendues viennent de la spec.
|
|
3. Ajoute au besoin des **squelettes vides** pour que le code compile (langages typés), sans aucune logique.
|
|
4. Vérifie que chaque nouveau test échoue **pour la bonne raison** (pas pour une erreur d'import ou de syntaxe).
|
|
5. 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
|
|
|
|
1. **Contrôle bloquant** : `git diff <hash-rouge> -- <fichiers de tests>` doit être vide.
|
|
2. Vérifie la conformité au changement OpenSpec (objectifs, périmètre, non-objectifs).
|
|
3. Relit l'exactitude, la robustesse et la sécurité de base.
|
|
4. Propose des **refactors sans changement de comportement** (lisibilité, duplication, nommage).
|
|
5. 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.
|
|
|
|
```bash
|
|
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-change` et 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-writer` ne 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é : `developer` ne 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.md` exact.** Si vous changez de runner ou de commandes, demandez à l'architecte de relancer `@repo-scout`.
|
|
- **Projet sans tests ?** `repo-scout` l'indiquera dans `TDD.md`. Il faut mettre en place un runner de tests avant de pouvoir lancer la boucle TDD.
|
|
- **Permissions Claude Code** : `.claude/settings.json` active `acceptEdits` par 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
|
|
```
|