Distribution d'Agents en Parallèle

Vue d'ensemble

Vous déléguez des tâches à des agents spécialisés avec un contexte isolé. En formulant précisément leurs instructions et contexte, vous garantissez qu'ils restent concentrés et réussissent leur tâche. Ils ne doivent jamais hériter du contexte ou historique de votre session — vous construisez exactement ce dont ils ont besoin. Cela préserve aussi votre propre contexte pour le travail de coordination.

Lorsque vous avez plusieurs défaillances non liées (fichiers de test différents, sous-systèmes différents, bugs différents), les investiguer séquentiellement gaspille du temps. Chaque investigation est indépendante et peut se faire en parallèle.

Principe fondamental : Dispatchez un agent par domaine de problème indépendant. Laissez-les travailler concurremment.

Quand utiliser

digraph when_to_use {
    "Multiple failures?" [shape=diamond];
    "Are they independent?" [shape=diamond];
    "Single agent investigates all" [shape=box];
    "One agent per problem domain" [shape=box];
    "Can they work in parallel?" [shape=diamond];
    "Sequential agents" [shape=box];
    "Parallel dispatch" [shape=box];

    "Multiple failures?" -> "Are they independent?" [label="yes"];
    "Are they independent?" -> "Single agent investigates all" [label="no - related"];
    "Are they independent?" -> "Can they work in parallel?" [label="yes"];
    "Can they work in parallel?" -> "Parallel dispatch" [label="yes"];
    "Can they work in parallel?" -> "Sequential agents" [label="no - shared state"];
}

À utiliser quand :

3+ fichiers de test échouent avec des causes racines différentes
Plusieurs sous-systèmes cassés indépendamment
Chaque problème peut être compris sans contexte des autres
Aucun état partagé entre les investigations

À ne pas utiliser quand :

Les défaillances sont liées (fixer l'une peut fixer les autres)
Besoin de comprendre l'état complet du système
Les agents s'interfèreraient mutuellement

Le pattern

1. Identifier les Domaines Indépendants

Groupez les défaillances par ce qui est cassé :

Tests du fichier A : Flow d'approbation d'outils
Tests du fichier B : Comportement de complètion par batch
Tests du fichier C : Fonctionnalité d'abandon

Chaque domaine est indépendant — fixer l'approbation des outils n'affecte pas les tests d'abandon.

2. Créer des Tâches d'Agent Focalisées

Chaque agent reçoit :

Scope spécifique : Un fichier de test ou sous-système
Objectif clair : Faire passer ces tests
Contraintes : Ne pas changer autre code
Résultat attendu : Résumé de ce que vous avez trouvé et fixé

3. Dispatcher en Parallèle

// In Claude Code / AI environment
Task("Fix agent-tool-abort.test.ts failures")
Task("Fix batch-completion-behavior.test.ts failures")
Task("Fix tool-approval-race-conditions.test.ts failures")
// All three run concurrently

4. Examiner et Intégrer

Quand les agents reviennent :

Lisez chaque résumé
Vérifiez que les fixes ne rentrent pas en conflit
Lancez la suite de tests complète
Intégrez tous les changements

Structure du Prompt d'Agent

Les bons prompts d'agent sont :

Focalisés - Un domaine de problème clair
Autosuffisants - Tout le contexte nécessaire pour comprendre le problème
Spécifiques sur la sortie - Que doit retourner l'agent ?

Fix the 3 failing tests in src/agents/agent-tool-abort.test.ts:

1. "should abort tool with partial output capture" - expects 'interrupted at' in message
2. "should handle mixed completed and aborted tools" - fast tool aborted instead of completed
3. "should properly track pendingToolCount" - expects 3 results but gets 0

These are timing/race condition issues. Your task:

1. Read the test file and understand what each test verifies
2. Identify root cause - timing issues or actual bugs?
3. Fix by:
   - Replacing arbitrary timeouts with event-based waiting
   - Fixing bugs in abort implementation if found
   - Adjusting test expectations if testing changed behavior

Do NOT just increase timeouts - find the real issue.

Return: Summary of what you found and what you fixed.

Erreurs Courantes

❌ Trop large : "Fixez tous les tests" - l'agent s'égare ✅ Spécifique : "Fixez agent-tool-abort.test.ts" - scope focalisé

❌ Pas de contexte : "Fixez la race condition" - l'agent ne sait pas où ✅ Contexte : Collez les messages d'erreur et noms de tests

❌ Pas de contraintes : L'agent pourrait tout refactoriser ✅ Contraintes : "Ne modifiez PAS le code de production" ou "Fixez les tests seulement"

❌ Sortie vague : "Fixez-le" - vous ne savez pas ce qui a changé ✅ Spécifique : "Retournez un résumé de la cause racine et des changements"

Quand NE PAS Utiliser

Défaillances liées : Fixer l'une peut fixer les autres — investiguer ensemble d'abord Besoin du contexte complet : La compréhension nécessite de voir l'ensemble du système Debugging exploratoire : Vous ne savez pas ce qui est cassé encore État partagé : Les agents s'interfèreraient (édition des mêmes fichiers, utilisation des mêmes ressources)

Exemple Réel de Session

Scénario : 6 tests échouent sur 3 fichiers après refactoring majeur

Défaillances :

agent-tool-abort.test.ts : 3 défaillances (problèmes de timing)
batch-completion-behavior.test.ts : 2 défaillances (outils non exécutés)
tool-approval-race-conditions.test.ts : 1 défaillance (nombre d'exécutions = 0)

Décision : Domaines indépendants — logique d'abandon séparée de la complètion par batch séparée des race conditions

Dispatch :

Agent 1 → Fix agent-tool-abort.test.ts
Agent 2 → Fix batch-completion-behavior.test.ts
Agent 3 → Fix tool-approval-race-conditions.test.ts

Résultats :

Agent 1 : Remplacement des timeouts par une attente basée sur événements
Agent 2 : Fixation du bug de structure d'événement (threadId au mauvais endroit)
Agent 3 : Ajout d'attente pour que l'exécution asynchrone des outils se complète

Intégration : Tous les fixes indépendants, aucun conflit, suite complète au vert

Temps économisé : 3 problèmes résolus en parallèle vs séquentiellement

Bénéfices Clés

Parallélisation - Plusieurs investigations se font simultanément
Focus - Chaque agent a un scope étroit, moins de contexte à gérer
Indépendance - Les agents ne s'interfèrent pas mutuellement
Vitesse - 3 problèmes résolus dans le temps d'1

Vérification

Après le retour des agents :

Examinez chaque résumé - Comprenez ce qui a changé
Vérifiez les conflits - Les agents ont-ils édité le même code ?
Lancez la suite complète - Vérifiez que tous les fixes fonctionnent ensemble
Vérification ciblée - Les agents peuvent faire des erreurs systématiques

Impact dans le Monde Réel

Depuis une session de debugging (2025-10-03) :

6 défaillances sur 3 fichiers
3 agents dispatchés en parallèle
Toutes les investigations complétées concurremment
Tous les fixes intégrés avec succès
Zéro conflits entre les changements d'agents

dispatching-parallel-agents