Équipes d'agents Builder-Validator

Le problème: Les agents Claude Code en parallèle vont vite. Mais sans rôles clairs, ils te rendent un travail inégal et tu te retrouves à tout vérifier toi-même. Ce qu'on veut, c'est des agents qui notent le travail des autres.

Tu cherches les Agent Teams natifs ? Claude Code intègre maintenant une fonctionnalité Agent Teams pour la collaboration multi-agents. Cet article couvre l'approche DIY avec les outils Task, qui marche sans activer de fonctionnalités expérimentales.

Gain rapide: Colle cette chaîne builder-validator dans ta prochaine tâche multi-fichiers. Le validator tourne en lecture seule, juste après la fin du builder :

TaskCreate(subject="Build auth middleware", description="Create JWT validation middleware in src/middleware/auth.ts. Export verifyToken and requireAuth functions.")
TaskCreate(subject="Validate auth middleware", description="Read src/middleware/auth.ts. Verify: exports exist, error handling covers expired/malformed tokens, no hardcoded secrets. Report issues only. Do NOT modify files.")
TaskUpdate(taskId="2", addBlockedBy=["1"])

La tâche 2 attend la fin de la tâche 1. Le validator lit, il n'écrit jamais. Deux agents. Un résultat en lequel tu peux avoir confiance.

Pourquoi les paires battent les agents seuls

Les fondamentaux des agents couvrent ce que sont les sub-agents. La distribution de tâches couvre leur exécution en parallèle pour gagner en vitesse. Les bonnes pratiques des sub-agents couvrent le routage. Cet article couvre autre chose : donner des rôles aux agents et les regrouper en équipes.

Les agents seuls ont un défaut simple. Un agent qui a écrit le code est le pire choix pour le relire. Mêmes angles morts, mêmes hypothèses, mêmes raccourcis. Ajoute un validator indépendant et tu attrapes ce que le builder a raté, parce que le validator commence à zéro.

C'est la même raison pour laquelle les équipes humaines ne laissent pas l'auteur être le seul relecteur. Tu amènes un autre regard.

Le Pattern Builder-Validator

Les builders écrivent le code. Les validators lisent le code. Les deux jobs ne se chevauchent jamais.

Prompt builder - centré sur la création :

You are a builder agent. Your job:
 
1. Read the task description carefully
2. Implement the solution in the specified files
3. Run any relevant tests
4. Mark your task complete
 
Rules:
 
- Only modify files listed in your task
- Do not modify test files (validators handle test verification)
- If you hit a blocker, document it in the task description and mark complete

Prompt validator - centré sur la vérification :

You are a validator agent. Your job:
 
1. Read all files the builder created or modified
2. Check against the acceptance criteria in the task description
3. Run the test suite
4. Report findings as a new task if issues exist
 
Rules:
 
- Do NOT modify any source files
- Do NOT create new implementation code
- You may only create or update task entries to report issues
- Use Read and Bash (for tests) only - never Edit or Write

La contrainte clé : les validators ne peuvent pas écrire de code. Ça les force à remonter les vrais problèmes, plutôt que de les corriger discrètement et de sauter la revue. Quand un validator repère un problème, il crée une nouvelle tâche qui revient vers un builder. Tu peux durcir ça au niveau des outils avec des définitions d'agents personnalisées et disallowedTools, qui retire Edit et Write des validators.

Chaînes de dépendances pour Build-Then-Validate

Le paramètre addBlockedBy sur TaskUpdate, c'est ce qui colle ce pattern ensemble. Les validators attendent leur builder sans aucun câblage supplémentaire :

// Phase 1: Parallel builders
TaskCreate(subject="Build user API routes", description="Create CRUD endpoints in src/api/users.ts...")
TaskCreate(subject="Build user database schema", description="Create migration in src/db/migrations/...")

// Phase 2: Validators blocked by their builders
TaskCreate(subject="Validate API routes", description="Read src/api/users.ts. Verify REST conventions, error handling, input validation...")
TaskCreate(subject="Validate database schema", description="Read migration files. Verify column types, indexes, foreign keys...")

TaskUpdate(taskId="3", addBlockedBy=["1"])
TaskUpdate(taskId="4", addBlockedBy=["2"])

Les tâches 1 et 2 tournent en parallèle parce qu'elles touchent des fichiers différents. Les tâches 3 et 4 attendent chacune leur propre builder. Vitesse parallèle sur la phase de build. Vérifications indépendantes sur chaque sortie.

Les vérifications transversales qui nécessitent que tout soit construit en premier empilent simplement plusieurs blockers :

TaskCreate(subject="Integration validation", description="Verify API routes correctly reference the database schema. Check that all referenced tables and columns exist.")
TaskUpdate(taskId="5", addBlockedBy=["1", "2"])

Un meta-prompt qui construit tout le plan

Assembler des chaînes de tâches à la main, ça devient vite fastidieux. Un meta-prompt dans CLAUDE.md peut transformer une demande de fonctionnalité en plan d'équipe complet sur le moment :

## Team Plan Generation
 
When I say "team plan: [feature]", generate a task structure:
 
For each component:
 
1. TaskCreate a builder task with specific files and acceptance criteria
2. TaskCreate a validator task scoped to read-only verification
3. TaskUpdate to chain validator behind its builder
 
After all component pairs, add one integration validator blocked by ALL builders.
 
Format each task description with:
 
- **Files**: exact paths to create or read
- **Criteria**: measurable acceptance conditions
- **Constraints**: what this agent must NOT do

Maintenant tu peux juste dire : "team plan: add Stripe webhook handler." Claude retourne le graphe de dépendances complet, associe chaque composant à son validator, et ajoute un validator d'intégration à la fin. Tu lis le plan, tu dis go, les agents tournent.

C'est le pattern orchestrateur, en direct. Ta session Claude principale coordonne. Elle écrit le plan, câble les blockers, et envoie les agents. Elle n'écrit pas elle-même le code de l'application.

Quand une validation échoue

La boucle continue quand un validator signale un problème :

Le validator ouvre une tâche de correction qui explique ce qui est cassé
Un agent builder prend en charge la tâche de correction
Une nouvelle tâche validator s'enchaîne après la correction

// Validator found missing error handling
TaskCreate(subject="Fix: add error handling to user API", description="The GET /users/:id endpoint returns 500 on invalid ID format. Add input validation and return 400 for malformed IDs.")
TaskCreate(subject="Re-validate user API error handling", description="Verify GET /users/:id returns 400 for non-UUID strings, 404 for valid UUID not found, 200 for valid existing user.")
TaskUpdate(taskId="7", addBlockedBy=["6"])

Chaque cycle resserre la portée. Le premier builder gère toute la fonctionnalité. Les builders suivants gèrent un bug chacun. La boucle fait avancer le code vers le bon résultat sans que tu aies à déboguer les étapes intermédiaires.

Pour les vérifications plus poussées, les hooks peuvent faire tourner des règles automatisées à chaque changement de fichier, pour attraper les problèmes avant même que l'agent validator se réveille. Tu peux aller plus loin en intégrant la validation directement dans les définitions d'agents, ce qui fait du contrôle qualité une partie de l'identité de l'agent.

Commence avec une seule paire

Ne remets pas tout ton workflow à plat. Prends la prochaine fonctionnalité qui touche deux fichiers ou plus. Fais une tâche builder. Fais une tâche validator avec addBlockedBy. Regarde le validator signaler quelque chose que le builder a laissé passer.

Une fois que tu as vu que ça marche, empile : builders parallèles avec validators enchaînés, meta-prompts qui écrivent le plan, validators d'intégration qui relient tout. Construis ta configuration d'agents autour de frontières de rôles claires. Laisse le système de tâches gérer l'ordre. Toi, tu gardes les décisions.