Workflow multi-agent dans Claude Code : rôles, isolation et validation manuelle
Guide pratique pour structurer un workflow multi-agent dans Claude Code avec séparation des rôles, Git worktrees, carte de passation et validation humaine.
Construire des « équipes d’agents IA » entièrement autonomes avec fusion automatique du code peut introduire des défauts d’architecture discrets, des boucles de refactoring et une dégradation progressive de la base de code. Deux agents exécutés en parallèle ne constituent pas une source de vérité indépendante : si l’agent auteur commet une erreur de raisonnement, un agent relecteur reposant sur des bases de prompts similaires peut très bien ne pas la voir.
Un workflow multi-agent fiable ne repose donc pas sur l’illusion d’une autonomie totale, mais sur une séparation stricte des rôles : un agent qui implémente (Author), un vérificateur indépendant (Reviewer) et un développeur humain qui prend la décision finale de fusionner.
1. Limites des rôles : Author, Reviewer et décision humaine
Dans un workflow de développement efficace, chaque intervenant a un périmètre de responsabilité fermé et explicite :
2. Isolation du contexte et de l’espace de travail
N’exécutez jamais l’agent auteur et l’agent reviewer dans le même répertoire de travail ni dans le même fil de conversation. Isolez-les à trois niveaux :
- Contexte de session : des fils de conversation indépendants évitent les hallucinations mutuelles et les validations circulaires.
- Isolation du système de fichiers : des Git worktrees distincts garantissent que le reviewer examine uniquement un diff validé, sans état local non commité.
- Sécurité de l’environnement : les clés API et identifiants d’exécution restent dans des variables d’environnement et ne sont jamais transmis dans le texte d’un prompt.
Commandes de préparation des worktrees
[!IMPORTANT]
Configuration API : chaque session Claude Code utilise ses propres identifiants API, configurés dans les variables d’environnement du système. Consultez le guide officiel BetterToken pour Claude Code.
3. Le contrat de passation structuré
Lorsque l’agent auteur termine son implémentation, il produit une carte de passation concise. Les transcriptions brutes de chat, les secrets et les hypothèses non vérifiées en sont exclus :
Handoff Card
- Task: Add HTTP 429 retry support in payment client with exponential backoff.
- Branch:
feat/payment-retry - Changed Files:
src/client/http.ts,tests/http-retry.test.ts - Verification Command:
npm test -- tests/http-retry.test.ts(Passed) - Risks & Blockers: Exponential backoff capped at 3 attempts; socket timeout left unchanged.
- Next Step: Reviewer agent validates Retry-After header handling.
4. Protocole de validation avec humain dans la boucle
L’agent reviewer mène son évaluation de manière isolée :
- Il se place dans le worktree propre :
../agent-reviewer. - Il exécute la commande de vérification enregistrée.
- Il inspecte le diff de façon indépendante pour repérer les effets de bord et les cas limites.
- Il produit une synthèse structurée à destination du développeur responsable.
Le développeur effectue la validation finale :
- il examine les conclusions du reviewer ;
- il confirme l’absence de régression par rapport à
main; - il exécute la fusion manuellement :
git merge feat/payment-retry.
Cette chaîne de travail évite les boucles de validation mutuelle tout en laissant le contrôle de la qualité et des choix d’architecture au développeur.