Table des matières
- Vue d'ensemble
- Quand utiliser
- Prérequis
- Architecture du protocole
- Démarrage rapide
- Flux de coordination
- Rôles de l'équipe
- Surveillance de la santé
- Référence des modules
- Intégration avec Conjure
- Alternative d'isolation par worktree (Claude Code 2.1.49+)
- Dépannage
- Critères de complétion
Coordination des équipes d'agents
Vue d'ensemble
Claude Code Agent Teams permet à plusieurs processus Claude CLI de collaborer sur un travail partagé via un protocole de coordination basé sur le système de fichiers. Chaque membre de l'équipe s'exécute comme un processus claude indépendant dans un volet tmux, communiquant via des fichiers JSON protégés par des verrous fcntl. Aucune base de données, aucun démon, aucune couche réseau.
Cette compétence fournit les schémas pour orchestrer efficacement les équipes d'agents.
Quand utiliser
- Implémentation parallèle sur plusieurs fichiers ou modules
- Revue de code multi-agents (un agent révise, un autre implémente des corrections)
- Refactorisation importante nécessitant des changements coordonnés entre sous-systèmes
- Tâches avec parallélisme naturel qui bénéficient d'agents concurrents
Quand NE PAS utiliser
- Modifications d'un seul fichier ou petites tâches (la surcharge dépasse le bénéfice)
- Tâches nécessitant un raisonnement séquentiel strict (les agents se coordonnent de manière lâche)
- Lorsque l'interface en ligne de commande
clauden'est pas disponible ou que tmux n'est pas installé
Prérequis
# Vérifier Claude Code CLI
claude --version
# Vérifier tmux (nécessaire pour le mode à volets)
tmux -V
# Activer la fonctionnalité expérimentale (définie automatiquement par le générateur)
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
Architecture du protocole
~/.claude/
teams/<nom-de-léquipe>/
config.json # Métadonnées de l'équipe + liste des membres
inboxes/
<nom-agent>.json # File de messages par agent
.lock # Verrou exclusif fcntl
tasks/<nom-de-léquipe>/
1.json ... N.json # Fichiers de tâches auto-incrémentés
.lock # Verrou exclusif fcntl
Principes de conception :
- Le système de fichiers est la base de données : fichiers JSON, écritures atomiques via
tempfile+os.replace - Verrouillage fcntl : empêche la corruption de lecture/écriture concurrente sur les boîtes de réception et les tâches
- Tâches numérotées : identifiants auto-incrémentés avec nommage séquentiel des fichiers
- Couplage lâche : les agents interrogent leur propre boîte de réception ; pas de notifications push
Démarrage rapide
1. Créer une équipe
# Configuration programmatique de l'équipe (via MCP ou API directe)
# La configuration de l'équipe est écrite dans ~/.claude/teams/<nom-de-léquipe>/config.json
La configuration de l'équipe contient :
name,description,created_at(timestamp en ms)lead_agent_id,lead_session_idmembers[]— tableau d'objets LeadMember et TeammateMember
2. Lancer les coéquipiers
Chaque coéquipier est un processus claude CLI séparé lancé avec des indicateurs d'identité :
claude --agent-id "backend@mon-equipe" \
--agent-name "backend" \
--team-name "mon-equipe" \
--agent-color "#FF6B6B" \
--parent-session-id "$SESSION_ID" \
--agent-type "general-purpose" \
--model sonnet
Voir modules/spawning-patterns.md pour la gestion des volets tmux et l'attribution des couleurs.
3. Créer des tâches avec dépendances
{
"id": "1",
"subject": "Implémenter les points d'accès API",
"description": "Créer les points d'accès REST pour la gestion des utilisateurs",
"status": "pending",
"owner": null,
"blocks": ["3"],
"blocked_by": [],
"metadata": {}
}
Voir modules/task-coordination.md pour la machine d'état et la gestion des dépendances.
4. Coordonner via des messages
{
"from": "chef-déquipe",
"text": "Les points d'accès API sont prêts pour les tests d'intégration",
"timestamp": "2026-02-07T22:00:00Z",
"read": false,
"summary": "API prête"
}
Voir modules/messaging-protocol.md pour les types de messages et les opérations sur la boîte de réception.
Flux de coordination
agent-teams:team-created— Initialiser la configuration et les répertoires de l'équipeagent-teams:teammates-spawned— Lancer les agents dans les volets tmuxagent-teams:tasks-assigned— Créer des tâches avec dépendances, attribuer des responsablesagent-teams:coordination-active— Les agents réclament les tâches, échangent des messages, marquent l'achèvementagent-teams:team-shutdown— Arrêt progressif avec protocole d'approbation
Rôles de l'équipe
Chaque membre de l'équipe a un role qui détermine ses capacités et sa compatibilité avec les tâches. Cinq rôles sont définis : implementer (par défaut), researcher, tester, reviewer, et architect. Les rôles contraignent les niveaux de risque qu'un agent peut gérer — voir modules/crew-roles.md pour la matrice complète des capacités et le tableau de compatibilité rôle-risque.
Surveillance de la santé
Les membres de l'équipe peuvent être surveillés pour leur santé via des messages de pulsation et l'expiration des réclamations. Le chef interroge la santé de l'équipe toutes les 60 secondes avec un protocole de détection de blocage en 2 étapes (sonde health_check + attente de 30 s). Les agents bloqués voient leurs tâches libérées et sont redémarrés ou remplacés suivant la doctrine "remplacer, ne pas attendre". Voir modules/health-monitoring.md pour le protocole complet et la machine d'état.
Référence des modules
- team-management.md : Cycle de vie de l'équipe, format de configuration, gestion des membres
- messaging-protocol.md : Types de messages, opérations sur la boîte de réception, schémas de verrouillage
- task-coordination.md : CRUD des tâches, machine d'état, détection de cycles de dépendances
- spawning-patterns.md : Lancement tmux, indicateurs CLI, gestion des volets
- crew-roles.md : Taxonomie des rôles, matrice des capacités, compatibilité rôle-risque
- health-monitoring.md : Protocole de pulsation, détection de blocage, récupération automatisée
Intégration avec Conjure
Agent Teams étend le modèle de délégation conjure :
| Modèle Conjure | Équivalent Agent Teams |
|---|---|
delegation-core:task-assessed | agent-teams:team-created |
delegation-core:handoff-planned | agent-teams:tasks-assigned |
delegation-core:results-integrated | agent-teams:team-shutdown |
| Exécution LLM externe | Exécution de l'agent coéquipier |
Utilisez d'abord Skill(conjure:delegation-core) pour déterminer si la tâche bénéficie d'une coordination multi-agents par rapport à une délégation à service unique.
Alternative d'isolation par worktree (Claude Code 2.1.49+)
Pour les agents parallèles qui modifient des fichiers, isolation: worktree fournit une alternative légère à la coordination basée sur le système de fichiers. Chaque agent s'exécute dans son propre worktree git temporaire, éliminant le besoin de verrouillage fcntl ou d'évitement de conflit basé sur la boîte de réception pour les fichiers partagés.
- Quand préférer les worktrees à la messagerie des équipes d'agents : Les agents travaillent sur des fichiers qui se chevauchent mais n'ont pas besoin de communication en cours d'exécution
- Quand préférer la messagerie des équipes d'agents : Les agents doivent coordonner des découvertes ou ajuster leurs plans en fonction de la progression des autres
- Combiner les deux : Utilisez les équipes d'agents pour la coordination avec
isolation: worktreepar coéquipier pour la sécurité du système de fichiers
Dépannage
Problèmes courants
tmux introuvable
Installez via le gestionnaire de paquets : brew install tmux / apt install tmux
Fichiers de verrouillage obsolètes
Si un agent plante en cours d'opération, les fichiers de verrouillage peuvent persister. Supprimez manuellement les fichiers .lock de ~/.claude/teams/<équipe>/inboxes/ ou ~/.claude/tasks/<équipe>/
Tâches orphelines
Les tâches réclamées par un agent qui a planté restent indéfiniment in_progress. Utilisez modules/health-monitoring.md pour la détection de blocage basée sur les pulsations et la libération automatique des tâches. Le protocole de surveillance de la santé détecte les agents qui ne répondent pas dans les 60 s + 30 s de fenêtre de sonde et libère leurs tâches pour réaffectation.
Ordre des messages La résolution des horodatages du système de fichiers varie (HFS+ = granularité de 1 s). Utilisez des noms de fichiers numérotés ou triés par UUID pour éviter les collisions lors de rafales de messages rapides.
Erreurs de modèle sur Bedrock/Vertex/Foundry (avant 2.1.39) Les agents coéquipiers pouvaient utiliser des identifiants de modèle incorrects sur les fournisseurs d'entreprise, provoquant des erreurs 400. Mettez à niveau vers Claude Code 2.1.39+ pour une qualification correcte des identifiants de modèle sur tous les fournisseurs.
Protection de session imbriquée (2.1.39+)
Si claude refuse de se lancer dans une session existante, assurez-vous d'utiliser le fractionnement en volets tmux (et non un appel en sous-shell). La protection est intentionnelle — voir modules/spawning-patterns.md pour les détails.
Critères de complétion
- Équipe créée avec configuration et répertoires
- Coéquipiers lancés et enregistrés dans la configuration
- Tâches créées avec graphe de dépendances (aucun cycle)
- Agents coordonnant via des messages dans la boîte de réception
- Arrêt progressif complété