Patterns d'agents

Le problème: Les sub-agents marchent, mais tu reviens toujours à la même forme. Quelques appels parallèles, les doigts croisés, de la colle manuelle sur ce qui revient. Il y a une meilleure façon d'organiser le travail des agents, et la forme que tu choisis décide si la sortie tient la route ou s'effondre.

Six patterns d'orchestration reviennent sans cesse dans le vrai travail avec Claude Code. Chacun convient à un type de job différent. Choisis mal et les tokens fuitent, les fichiers se percutent, ou les réponses dérivent. Choisis bien et une pile d'agents peut mâcher du travail difficile avec presque aucune supervision.

Sélecteur de pattern

Si tu as juste besoin d'une règle de sélection rapide, utilise ça :

L'erreur est de traiter les patterns comme une idéologie. Ce sont des formes de charge de travail. Prends celle qui correspond au problème de coordination devant toi.

Lis cette page quand la question ouverte est la forme d'orchestration. Si tu décides encore entre sub-agents, slash commands, définitions d'agents, et règles globales de repo, commence par Agent Fundamentals. Si ta charge de travail nécessite plusieurs sessions Claude collaborant directement via une liste de tâches et une boîte aux lettres partagées, passe à Claude Code Agent Teams.

Le Pattern Orchestrateur

Un fil central mène la danse et distribue le travail aux spécialistes. Il ne touche jamais le code lui-même. Son seul job : planifier, déléguer, revoir, et router.

Quand l'utiliser: Fonctionnalités qui traversent le frontend, le backend, et la base de données. Tout ce où quelqu'un doit garder la vue d'ensemble en tête.

Comment ça marche dans Claude Code: Le chat principal devient le chef d'orchestre. Il lit la spec, rédige un plan, puis spawne des spécialistes via l'outil Task. Les résultats reviennent, sont revus, et la prochaine décision est prise sur le moment.

You are the orchestrator. For this feature request, create a plan that:
1. Breaks the work into domain-specific tasks
2. Identifies dependencies between tasks
3. Dispatches each task to a sub-agent with explicit file scope
4. Reviews outputs before marking complete

Do NOT write implementation code yourself. Coordinate only.

CLAUDE.md est le foyer naturel pour ce câblage. Les règles de routage vivent dans ce fichier, et le chef d'orchestre les traite comme un contrat. Dans une bonne configuration, tout le graphe de dépendances des tâches est résolu en premier, avant qu'un sub-agent écrive la moindre ligne.

Quand NE PAS l'utiliser: Les petits jobs qu'un seul agent peut finir en une passe. Ajouter un utilitaire, corriger une faute de frappe. La comptabilité de l'orchestration coûte plus cher que la valeur qu'elle apporte.

Le Pattern Fan-Out / Fan-In

Beaucoup d'agents partent en parallèle. Tous rapportent. Un fil tire les résultats en une seule réponse.

Quand l'utiliser: Balayages de recherche. Analyse multi-fichiers. Tout où chaque agent travaille sur ses propres entrées sans chevauchement. Revues de code sur des modules indépendants. Collecte d'infos dans différents coins d'une codebase avant qu'une décision soit prise.

Comment ça marche dans Claude Code: Lance des sub-agents en parallèle en émettant plusieurs appels à l'outil Task dans le même message. Chacun ouvre ses propres fichiers ou poursuit sa propre préoccupation. Une fois que chaque agent revient, le fil central assemble les pièces.

Complete these 4 tasks using parallel sub-agents:

1. Read src/api/ and list all endpoints missing input validation
2. Read src/auth/ and identify any hardcoded secrets or weak patterns
3. Read src/db/ and check for missing indexes on frequently queried columns
4. Read src/utils/ and flag any functions with no error handling

After all agents report back, synthesize findings into a prioritized action list.

La phase fan-out est rapide parce que les agents ne partagent aucun état. La phase fan-in est là où ça se passe : l'orchestrateur attrape les liens entre les résultats qu'aucun agent seul ne pouvait voir. Un chemin d'auth faible plus un trou dans la validation des entrées peut additionner pour une faille exploitable, même si aucun rapport ne le dit clairement tout seul.

Quand NE PAS l'utiliser: Tout job où plusieurs agents doivent modifier des fichiers qui se chevauchent. Les écritures concurrentes sur du code partagé mènent droit aux conflits de merge. Quand le travail n'est pas vraiment indépendant, une chaîne séquentielle est le bon choix.

Le Pattern Chaîne de Validation

Un agent builder écrit le code. Un agent validator différent l'inspecte. Leurs rôles ne se chevauchent jamais.

Quand l'utiliser: Changements en production. Travail sensible à la sécurité. Partout où une mauvaise réponse coûte de l'argent réel. Prends ce pattern quand shipper un bug n'est tout simplement pas une option.

Comment ça marche dans Claude Code: Deux tâches câblées par une dépendance. Le builder livre le code en premier. Une fois que c'est fait, le validator ouvre le diff, lance les tests, et produit son rapport, sans toucher un seul fichier.

TaskCreate(
  subject="Build payment webhook handler",
  description="Create Stripe webhook handler in src/api/webhooks/stripe.ts.
  Handle checkout.session.completed, payment_intent.failed events.
  Verify webhook signatures. Include error handling."
)

TaskCreate(
  subject="Validate payment webhook handler",
  description="Read src/api/webhooks/stripe.ts. Verify:
  - Webhook signature verification exists
  - Both event types handled with proper responses
  - Error handling covers malformed payloads
  - No hardcoded secrets
  Report issues only. Do NOT modify any files."
)

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

Le lien addBlockedBy est ce qui maintient le validator honnête. Il attend que le builder ait fini, et il arrive sans a priori. Pas d'hypothèses partagées. Pas d'angles morts hérités. C'est pour ça que la vérification attrape vraiment des trucs.

Si le validator repère un problème, il ouvre une tâche de correction routée vers un builder. Puis un nouveau validator s'enchaîne après cette correction. La boucle se resserre jusqu'à ce que la sortie soit correcte.

Quand NE PAS l'utiliser: Prototypage jetable où la vitesse prime sur la correction. Un validator dédié double à peu près le compute par tâche. Quand le code est un brouillon, un seul agent t'y amène plus vite, pour moins de tokens.

Le Pattern Routage par Spécialiste

Route chaque tâche vers l'expert du domaine qui connaît le job. Le travail frontend atterrit chez un spécialiste frontend. Les migrations vont chez l'expert base de données. Chaque agent tient ses propres conventions, instructions, et limites d'outils.

Quand l'utiliser: Grands repos avec plusieurs domaines clairs. Équipes avec des conventions établies par couche. Partout où des instructions génériques donnent des sorties molles et incohérentes à travers la codebase.

Comment ça marche dans Claude Code: Monte des agents spécialistes dans .claude/agents/, ou épingle des règles de routage dans ton CLAUDE.md. L'orchestrateur inspecte la tâche, identifie le domaine, et la passe au bon expert.

<!-- In CLAUDE.md -->

## Agent Routing Table

| Task Domain | Route To            | File Scope           |
| ----------- | ------------------- | -------------------- |
| React/UI    | frontend-specialist | src/components/      |
| API routes  | backend-engineer    | src/api/, src/lib/   |
| Database    | database-specialist | src/db/, migrations/ |
| Security    | security-auditor    | Any (read-only)      |
| Tests       | quality-engineer    | tests/, **tests**/   |

Chaque spécialiste défini dans .claude/agents/ hérite automatiquement de ton CLAUDE.md. Les standards de code viennent avec. Le propre fichier de l'agent ajoute le reste : les choix de framework, les règles de nommage, la gestion d'erreurs adaptée à cette couche.

La croissance est bon marché. Nouveau domaine signifie un nouveau fichier d'agent et une nouvelle ligne dans la table de routage. Rien n'est réécrit. Le guide des agents personnalisés explique comment définir des spécialistes avec du frontmatter YAML.

Quand NE PAS l'utiliser: Les petites codebases où un seul agent a déjà assez de contexte sur tout. L'overhead du routage n'apporte rien quand il n'y a qu'une destination de toute façon.

Le Pattern Raffinement Progressif

Commence avec un brouillon approximatif. Envoie-le à travers plusieurs rounds d'édition. Chaque round porte l'attention sur un seul axe de qualité.

Quand l'utiliser: Travail de contenu, architecture emmêlée, tout job où réussir du premier coup n'est pas réaliste. Marche bien sur les articles de blog, les schémas d'API, ou les fichiers de config qui doivent satisfaire plusieurs contraintes à la fois.

Comment ça marche dans Claude Code: Mets en file des agents dans une séquence où chacun lit la sortie précédente et affine un aspect spécifique.

Phase 1 - Draft: "Generate the initial API schema for a task management
system. Include all entities, relationships, and basic validation rules."

Phase 2 - Security review: "Review this schema. Add authentication
requirements, permission checks, and input sanitization rules.
Don't change the core structure."

Phase 3 - Performance review: "Review the schema for performance.
Add indexes, identify N+1 query risks, suggest denormalization
where read performance matters."

Phase 4 - Final validation: "Verify the schema is consistent.
Check that all referenced entities exist, foreign keys are valid,
and naming conventions are uniform."

Chaque phase a un regard étroit. L'agent de brouillon se soucie de la complétude. La sécurité ajoute des garde-fous. La performance ajuste. La validation vérifie la cohérence. Aucun agent ne doit jongler avec toutes les préoccupations à la fois.

Ça reflète comment les vrais développeurs travaillent. Le code n'atterrit jamais prêt pour la production dès la première passe. Tu fais un brouillon, tu corriges la justesse, tu optimises la performance, tu peaufines. Ce pattern confie chaque passe à un agent fait pour elle.

Quand NE PAS l'utiliser: Tout job qui doit atterrir en une seule fois, où l'amélioration par couches n'est pas possible. Aussi inutile sur du travail simple où le premier brouillon passe déjà la barre.

Le Pattern Watchdog

Un agent en arrière-plan surveille une condition. Quand elle se déclenche, le watchdog rapporte ou agit. Il tourne à côté de ton travail principal, jamais dans le chemin.

Quand l'utiliser: Les longues sessions où la dérive s'installe. Surveiller la santé du contexte, repérer des régressions pendant un refactor, ou regarder les builds passer au rouge pendant que ton attention est ailleurs.

Comment ça marche dans Claude Code: Passe un watchdog en arrière-plan avec Ctrl+B et reprends ce que tu faisais. L'agent vérifie son déclencheur sur une cadence. Quand quelque chose s'active, les résultats remontent directement dans ta liste de tâches.

Background task: Monitor the test suite while I refactor the auth module.
Every time I complete a change, run the test suite for src/auth/.
If any test fails, immediately create a task with:
- Which test failed
- The assertion error
- Which file I likely broke based on the test name

Un bon exemple vit dans le hook de récupération de contexte. C'est un watchdog câblé dans l'infrastructure elle-même, qui suit l'utilisation du contexte et déclenche la récupération dès que la fenêtre commence à se remplir. Les hooks d'état des agents et de progression marchent pareil.

Les watchdogs paient le plus quand ils sont associés aux workflows asynchrones, où des agents en arrière-plan tournent seuls et affichent les résultats devant toi quand tu es prêt.

Quand NE PAS l'utiliser: Les sessions courtes où le coût de la surveillance dépasse la valeur de ce qui est surveillé. Une tâche de deux minutes avec un watchdog qui surveille toutes les trente secondes, c'est nul.

Combiner les patterns

Les projets réels ne restent presque jamais dans un seul pattern. Une fonctionnalité non triviale finit souvent câblée comme ça :

1. Orchestrateur lit la spec et rédige le plan
2. Routage par spécialiste distribue les tâches aux experts du domaine
3. Fan-out lance les pièces indépendantes en parallèle
4. Chaînes de validation vérifient le travail de chaque spécialiste
5. Raffinement progressif peaufine le résultat fusionné
6. Watchdog surveille la suite de tests tout le temps

La compétence n'est pas de mémoriser la liste. C'est de lire la tâche devant toi et de la faire correspondre à la bonne forme. Prends le pattern le plus simple qui peut porter la charge. Ajoute plus de structure seulement quand celui-là casse.

Trois combinaisons qui marchent bien

1. Orchestrateur + routage par spécialiste

Idéal pour :

• fonctionnalités full-stack
• refactors cross-couches
• changements qui ont besoin d'un cerveau coordinateur

Pourquoi ça marche : l'orchestrateur tient le plan, tandis que le routage garde chaque tâche d'implémentation dans les bonnes mains.

2. Fan-out + chaîne de validation

Idéal pour :

• audits larges
• balayages de sécurité ou de qualité
• workflows avec beaucoup de revues

Pourquoi ça marche : des agents indépendants rassemblent des résultats en parallèle, puis un validator séparé attrape les conclusions faibles avant qu'on leur fasse confiance.

3. Raffinement progressif + watchdog

Idéal pour :

• longs workflows de contenu
• ébauches d'architecture
• tout ce où la qualité monte sur plusieurs passes

Pourquoi ça marche : une chaîne améliore l'artefact, pendant que le watchdog surveille l'état du système environnant, les tests, ou les régressions.

Prochaines étapes :

• Agent Fundamentals, pour comprendre comment sub-agents et slash commands s'articulent
• Sub-Agent Best Practices, pour les appels parallèles vs séquentiels
• Team Orchestration, pour la boucle complète builder et validator
• Task Distribution, pour garder le travail multi-agents organisé
• Custom Agents, pour écrire tes propres définitions de spécialistes