Subagents Claude Code : structure, cinq rôles et orchestration

Qu’est-ce qu’un subagent dans Claude Code, et pourquoi n’est-ce pas « juste un autre Skill » ?#

La documentation de Claude Code le définit ainsi :

Pour le dire avec des termes qu’un entrepreneur comprendrait : imaginez une agence immobilière. Il y a un directeur, un spécialiste du marketing, un juriste et des responsables commerciaux. Une personne qui passe d’un rôle à l’autre ne forme pas une équipe ; c’est une personne débordée. Une équipe se constitue lorsque chaque personne a son propre contexte et son domaine de responsabilité, tandis que le directeur se contente d’attribuer les tâches et de rassembler les résultats.

Les subagents de Claude Code fonctionnent de la même manière. Le chat principal est le directeur. Un subagent est un spécialiste chargé d’une tâche ciblée, avec son propre contexte et ses propres outils. Lorsque la description d’un spécialiste correspond à une tâche, le directeur la lui délègue sans s’enliser dans les détails.

Les 5 objectifs pour lesquels Anthropic a conçu les subagents

La documentation d’Anthropic énumère exactement cinq raisons de créer votre propre subagent :

Pour une personne qui ne programme pas, l’élément le plus pratique de cette liste est la maîtrise des coûts. Vous pouvez confier une tâche de recherche lourde au modèle Haiku, peu coûteux, tout en poursuivant la conversation principale sur Sonnet ou Opus. Les économies de tokens sont directement proportionnelles.

Vérifiez l’imbrication prise en charge par votre version

Les modèles de ce guide utilisent une session principale déléguant directement aux assistants. L’ancienne consigne « les sous-agents ne peuvent pas en lancer d’autres » n’est pas une règle intemporelle : cela dépend de la version et des outils autorisés. Le guide des sous-agents imbriqués présente une recette propre à une version. Vérifiez le support installé avant une délégation plus profonde.

En quoi un subagent diffère-t-il d’un Skill, d’une commande slash et d’un hook ?#

Le guide précédent consacré aux Skills explique que les Skills et les commandes slash dans Claude Code ont pratiquement fusionné en un seul format. Mais un subagent est une entité différente, pas simplement « un Skill plus gros ».

Voici un tableau récapitulatif des quatre mécanismes :

Pour un guide en anglais, on pourrait le formuler ainsi : les Skills sont des recettes ; les subagents, des collègues spécialisés.

Put simply: les Skills sont comme des recettes ; les subagents, comme des collègues spécialisés.

En pratique, cela fonctionne ainsi : les Skills s’activent automatiquement lorsque leur description correspond à la tâche, tandis que les subagents sont appelés explicitement — soit le chat principal décide de déléguer, soit vous en appelez un par son nom.

Arbre de décision : « Lequel choisir ? »

Lorsque vous pensez : « J’ai besoin que Claude fasse X », posez-vous ces quatre questions :

1. S’agit-il d’une connaissance qui doit toujours être disponible ? Par exemple : « Nous localisons le contenu dans la langue préférée de l’utilisateur » ou « Nous n’utilisons pas de cadratins ». Ajoutez-la à CLAUDE.md.
2. S’agit-il d’une méthode déclenchée que vous effectuez manuellement aujourd’hui ? Par exemple : « J’écris un rapport commercial tous les lundis ». Créez un Skill.
3. Cette tâche va-t-elle consommer le contexte du chat principal, ou peut-elle être exécutée en parallèle ? Par exemple : « recherche approfondie sur 30 sources » ou « audit de sécurité pendant que j’écris une nouvelle fonctionnalité ». Créez un subagent.
4. Avez-vous besoin d’une réponse automatique à un événement dans Claude Code ? Par exemple : « Exécute le linter après chaque Edit ». Écrivez un hook.

90 % des tâches d’un entrepreneur appartiennent aux deux premières catégories. Les subagents sont un outil de niveau supérieur, à utiliser lorsque vous passez de « une tâche à la fois » à l’orchestration.

Où se trouvent les subagents, et lequel est prioritaire ?#

La hiérarchie des subagents compte cinq niveaux, classés du plus prioritaire au moins prioritaire :

La logique de priorité est la même que pour les Skills et CLAUDE.md : l’organisation prime sur la CLI, la CLI sur le projet, le projet sur le niveau personnel et le niveau personnel sur les plugins.

Ce qu’il faut savoir sur le chargement

Les subagents sont chargés au démarrage d’une session Claude Code. Si vous modifiez manuellement un fichier d’agent sur le disque, les changements ne seront pris en compte qu’après le redémarrage de la session. Les modifications effectuées dans l’interface interactive /agents s’appliquent immédiatement.

Un subagent par portée signifie un fichier. Si .claude/agents/ contient un fichier code-reviewer.md et un autre fichier du même nom à côté (par exemple, une copie provenant d’une ancienne sauvegarde), Claude Code ignorera silencieusement l’un des deux. Aucune notification ne sera affichée.

Les subagents de plugins constituent un cas à part. Ils sont soumis à des restrictions de sécurité : ils ne prennent pas en charge les champs hooks, mcpServers et permissionMode. Cela empêche l’installation d’un plugin tiers de lui donner l’autorisation d’exécuter du code arbitraire sur votre machine.

Structure d’un fichier de subagent : frontmatter et corps#

Un exemple minimal tiré de la documentation officielle — seulement 9 lignes :

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

Cela suffit. Si un utilisateur dit « examine ma PR » dans le chat principal, Claude fait correspondre « reviewer / code / quality » à la description et délègue au subagent. Celui-ci lit le diff, rédige des commentaires et renvoie un résumé au chat principal. Celui-ci n’est pas encombré de journaux et d’analyses intermédiaires.

Schéma complet du frontmatter

Le champ model: haiku correspond exactement à la « maîtrise des coûts » dans la liste des cinq objectifs. Si vous avez un agent de recherche qui lit 50 pages de documentation, faites-le tourner sur Haiku pour économiser 5 à 7 fois plus qu’avec Opus.

Le champ isolation: worktree répond à un problème important : un subagent peut effectuer des changements potentiellement dangereux (refactorisation, migration), mais vous ne voulez pas qu’il touche à votre copie de travail. Définissez isolation: worktree, et Claude Code crée une copie git temporaire du projet ; le subagent y travaille et renvoie un diff à examiner.

Le corps du fichier est le prompt système

Après le frontmatter vient du Markdown ordinaire : c’est le prompt système du subagent. Aucune structure particulière n’est obligatoire, mais le modèle suivant a fait ses preuves :

1. Qui vous êtes — une phrase : « vous êtes un réviseur de code », « vous êtes un auditeur de sécurité », « vous assurez la maintenance de la documentation ».
2. Dans quelles circonstances vous êtes appelé et ce que vous faites d’abord — les 2–3 premières actions après réception de la tâche.
3. Une liste de vérifications ou d’étapes — 5 à 10 points que le subagent suit.
4. Ce que vous renvoyez — le format du rapport final. C’est essentiel : si vous ne précisez pas de format, le subagent produira un « essai » au lieu d’un résumé structuré.
5. Ce que vous ne faites PAS — des limites explicites. Sans cette section, le subagent se met à improviser.

Limitez le corps du fichier à 200–500 lignes. S’il devient plus long, déplacez les références volumineuses vers des fichiers séparés à proximité et créez des liens vers ceux-ci dans le prompt.

Comment rédiger une description pour que Claude appelle votre subagent à coup sûr#

Un problème courant consiste à configurer un subagent pour la révision de code, puis à constater que Claude fait tout lui-même sans utiliser l’agent. La raison est généralement la même : la description se limite à « Assistant pour la révision de code ». Claude ne comprend pas quand le déclencher.

Formule pour une description efficace (3 parties)

Partie 1 — ce qu’il fait. Une phrase sur le résultat, pas sur le processus. Pas « analyse le code », mais « repère les vulnérabilités dans le code et renvoie une liste indiquant leur gravité et proposant une correction ».

Partie 2 — quand le déclencher. 3–5 expressions entre guillemets, formulées comme les vraies demandes des utilisateurs. Ne devinez pas : consultez l’historique de vos conversations et les formulations réellement employées.

Partie 3 — quand NE PAS le déclencher. 1–2 formulations indiquant des tâches similaires auxquelles ce subagent ne doit pas répondre. Sans cette section, deux agents similaires entrent constamment en conflit.

L’expression magique « Use Proactively »

La documentation officielle d’Anthropic formule une recommandation directe :

Autrement dit, Claude a tendance à ne pas appeler un subagent par défaut si sa description ne contient aucun signal clair. Ajoutez « use proactively » ou « use immediately after writing code », et le taux d’activation augmente fortement.

Exemple de description efficace

description: |
  Expert code review specialist. Proactively reviews code for quality,
  security, and maintainability. Use immediately after writing or
  modifying code. Returns prioritized list of issues with severity
  and fix recommendations.
  Do not invoke for documentation changes, README edits, or commit
  message rewrites - these are handled by doc-maintainer.

Ce qui fonctionne ici :

• Les verbes « reviews » et « returns » définissent un résultat concret, pas un processus.
• « Proactively » et « immediately after » sont des déclencheurs explicites.
• « Do not invoke for... » écarte le conflit avec un subagent similaire.
• L’anglais dans la description est la norme. Claude associe mieux les requêtes à l’anglais.

Agent IA Claude : 5 rôles de subagent prêts à l’emploi#

Chacun des rôles ci-dessous tient dans un seul fichier, .claude/agents/<name>.md. Après avoir créé le fichier, redémarrez Claude Code, ouvrez /agents et vérifiez que le nouvel agent apparaît dans la liste. Vous pourrez ensuite l’appeler avec @agent-name.

1. code-reviewer — réviser le code après chaque modification

Il s’agit de l’exemple officiel de la documentation d’Anthropic, adapté à un processus de travail :

---
name: code-reviewer
description: |
  Expert code review specialist. Proactively reviews code for quality,
  security, and maintainability. Use immediately after writing or
  modifying code.
tools: Read, Grep, Glob
model: inherit
color: blue
---

You are a senior code reviewer ensuring high standards of code quality.

À l’invocation :
1. Lis le diff et les fichiers modifiés fournis par la session principale ; demande-les s’ils manquent.
2. Inspecte les fichiers pertinents avec Read, Grep et Glob.
3. Retourne les constats sans modifier les fichiers ni exécuter de commande shell.

Review checklist:
- Code is clear and readable
- Functions and variables are well-named
- No duplicated code
- Proper error handling
- No exposed secrets or API keys
- Input validation implemented
- Test coverage adequate
- Performance considerations addressed

Provide feedback organized by priority:
- Critical issues (must fix before merge)
- Warnings (should fix)
- Suggestions (consider improving)

Format: for each issue - file:line + 1 sentence why it's a problem + concrete fix.

L’essentiel est tools: Read, Grep, Glob : lecture et recherche sans Bash, Write ni Edit. La session principale prépare et transmet le diff. Dire simplement « exécute seulement git diff » ne restreint pas un outil Bash entièrement accordé.

2. security-auditor — repérer les vulnérabilités et les fuites

Ce rôle utilise opus pour approfondir le raisonnement avec les mêmes restrictions Read, Grep et Glob. La mémoire persistante est omise du modèle en lecture seule, car l’activer accorde aussi une capacité d’écriture de mémoire :

---
name: security-auditor
description: |
  Security audit specialist. Use proactively to find OWASP Top 10
  vulnerabilities, exposed secrets, injection risks, broken auth.
  Run before any deploy or merge to main.
tools: Read, Grep, Glob
model: opus
color: red
---

You are a security auditor. Find exploitable vulnerabilities, not style issues.

Audit checklist:
- SQL / NoSQL injection
- XSS (stored, reflected, DOM-based)
- CSRF / SSRF risks
- Hardcoded secrets (API keys, tokens, passwords)
- Broken auth / session management
- Insecure deserialization
- Missing input validation
- Path traversal
- Open redirects
- Insecure direct object references (IDOR)

For each finding:
- Severity: Critical / High / Medium / Low
- File:line
- Attack scenario in 1–2 sentences
- Fix recommendation with code example

Skip linter or style noise. Report only exploitable issues.

Configuration en lecture seule pour les outils, avec model: opus pour les vérifications complexes, comme les chaînes de vulnérabilités.

3. research-agent — recherche approfondie dans plus de 8 sources

Ce modèle est décrit par Anthropic elle-même dans son article sur le système de recherche multi-agent. L’essentiel est de définir explicitement le format de sortie et d’interdire le déversement de résultats bruts :

---
name: research-agent
description: |
  Deep web research specialist. Use proactively for fact-finding,
  competitive analysis, gathering external documentation, comparing
  approaches across multiple sources.
tools: WebFetch, WebSearch, Read, Write
model: sonnet
maxTurns: 30
color: purple
---

You are a research analyst. Goal: synthesized brief, not raw search dumps.

Process:
1. Decompose the question into 3–5 sub-queries
2. WebSearch each sub-query, fetch top 3–5 sources per query
3. Cross-verify claims across at least 2 independent sources
4. Reject SEO-farm and aggregator content; prefer primary sources
5. Quote verbatim with URL attribution for any specific claim
6. Return: TL;DR (3 bullets) + Findings + Sources (8+ domains minimum)

Anti-patterns to avoid:
- Don't cite a fact from a single source
- Don't paraphrase quotes as if they were verbatim
- Don't return raw search result dumps to the parent
- Don't include filler intro / outro ("Hope this helps")

maxTurns: 30 protège contre les recherches qui s’éternisent. Anthropic mentionne ce nombre dans son système multi-agent :

Les 90 % concernent des tâches de recherche servant de référence. En pratique, le gain est plus modeste pour les tâches professionnelles, mais l’ordre de grandeur reste similaire.

4. doc-maintainer — synchroniser la documentation avec le code

Ce rôle utilise model: haiku, un exemple type de « maîtrise des coûts ». La documentation ne nécessite pas Opus ; Haiku fait le travail pour un tiers du prix :

---
name: doc-maintainer
description: |
  Documentation sync specialist. Use after merging features to update
  README, API docs, CHANGELOG. Reads recent commits, identifies
  undocumented changes, updates docs proactively.
tools: Read, Write, Edit, Glob, Grep, Bash
model: haiku
memory: project
color: green
---

You maintain documentation in sync with code.

When invoked:
1. Run `git log --since="last release"` to see recent changes
2. Read README.md, docs/, CHANGELOG.md
3. Identify gaps: new features without docs, removed APIs still
   documented, version mismatches

Output:
- Updated files (use Edit, not Write - preserve existing structure)
- CHANGELOG.md entry in Keep-A-Changelog format
- List of changes you made (actual diff summary, not paraphrase)

Style rules:
- Active voice, present tense
- Code examples must be copy-pasteable
- No marketing language ("powerful", "robust", "seamless")
- No filler ("This guide will help you...")

5. refactor-agent — refactoriser en toute sécurité dans un worktree

Ce rôle utilise isolation: worktree : le subagent travaille dans une copie séparée du dépôt, et vous ne fusionnez ses changements que s’ils conviennent :

---
name: refactor-agent
description: |
  Safe refactor specialist. Use for renames, extracts, inlines that
  shouldn't touch your working copy until reviewed. Runs in a
  temporary git worktree.
tools: Read, Edit, Write, Bash, Grep, Glob
model: sonnet
isolation: worktree
permissionMode: acceptEdits
color: yellow
---

You refactor code without changing behavior.

Strict rules:
1. Tests must pass BEFORE and AFTER the refactor.
   If pre-refactor tests fail, STOP and report.
2. One atomic refactor per commit (extract, rename, inline).
3. Never change public APIs without explicit instruction.
4. Never modify tests unless they test the refactored implementation
   directly.

Process:
- Run test suite -> baseline
- Make atomic refactor
- Run test suite -> verify
- Commit with conventional message: refactor(scope): what

Return: summary of changes + worktree path so user can diff and merge.

Avec ce rôle, le problème de refactorisation le plus pénible — « j’ai tout cassé et je ne sais pas comment revenir en arrière » — disparaît : la copie d’origine reste intacte, et le subagent travaille dans un worktree isolé.

Vous voulez non seulement copier des subagents prêts à l’emploi, mais aussi assembler une combinaison qui fait de Claude un outil fiable ? Les subagents font partie de votre clone IA : ils permettent de fournir à Claude une équipe spécialisée qui travaille selon votre logique. Les trois piliers de la méthode sont : clone IA (Skills + subagents) + Second Brain + Context Engineering. Cette combinaison transforme Claude, d’un assistant qui devine, en un outil qui réfléchit selon votre logique.

Lancer 5 subagents en parallèle : orchestrateur + exécutants#

L’orchestration parallèle fonctionne comme un « chef d’orchestre + orchestre ». Le chef garde le plan, n’écrit pas les notes et vérifie ce que jouent les musiciens. Si quelqu’un joue une fausse note, le chef lui demande de la rejouer au lieu d’essayer de terminer à sa place.

Pour un entrepreneur, une comparaison plus parlante est celle d’une agence de marketing qui prépare une stratégie pour un nouveau client. Un analyste réalise une analyse SWOT, un autre étudie les concurrents, un troisième établit un profil de l’audience, un analyste senior élimine les hypothèses incompatibles avec le budget et le chef de projet assemble la présentation finale. Dans Claude Code, ce processus commence par une phrase, et le critique y est intégré au lieu d’intervenir après coup.

Prompt d’orchestration minimal

Une phrase dans le chat principal suffit :

Launch five subagents in parallel: three research-agents on different sources
(Anthropic docs, GitHub repos, AI bloggers), one critic-agent to filter out
weak conclusions, and one summary-agent for the final document.

Context: I am writing a guide about X. Target length: 2,000 words with sources.
Before starting, each one reads CLAUDE.md.

Claude délègue ensuite les tâches aux cinq agents. Chacun travaille dans son propre contexte : les agents de recherche utilisent leurs sources respectives, le critique filtre les résultats et l’agent de synthèse assemble le document. Seuls les résumés finaux sont renvoyés au chat principal.

Quand le travail en parallèle est-il utile ?

Pas dans tous les cas. L’exécution parallèle n’a de sens que si :

1. Les tâches sont indépendantes. Si research-agent #2 attend le résultat de research-agent #1, il n’y aura pas de travail en parallèle : les agents travailleront de fait l’un après l’autre.
2. Les tâches prennent du temps. Paralléliser une tâche comme « supprimer les espaces de fin de ligne » est inutile ; le lancement des subagents absorbera le gain obtenu.
3. Vos limites sont suffisantes. La section consacrée aux limites se trouve plus loin : les subagents parallèles consomment vite des tokens.

Multi-Agent v2 d’Anthropic : une nouvelle étape

En mai 2026, Anthropic a lancé Multi-Agent Orchestration v2, qui présente trois différences importantes par rapport à l’approche classique consistant à lancer des subagents en parallèle. Nous y reviendrons dans la section suivante.

Les nouveautés de Multi-Agent v2 : orchestration, Outcomes et Dreaming#

Multi-Agent Orchestration : système de fichiers partagé et points d’étape en cours de travail

Anthropic décrit cette fonctionnalité ainsi :

La différence essentielle avec les subagents classiques tient au système de fichiers partagé. Auparavant, chaque subagent travaillait en totale isolation et les échanges se limitaient au résumé renvoyé. Désormais, les spécialistes peuvent écrire dans un dossier partagé, et l’agent principal peut lire les résultats au fur et à mesure, pas seulement à la fin. Cela résout le problème de « tout le monde a travaillé toute la journée, mais on découvre à la fin que deux personnes ont suivi des approches incompatibles ».

Viennent ensuite les points d’étape en cours de travail. L’agent principal peut s’interrompre pour demander à n’importe quel spécialiste « où en es-tu ? », puis ajuster le plan d’ensemble. Cela se rapproche du travail d’un véritable responsable d’équipe.

Outcomes : des critères plutôt que des instructions étape par étape

Avec Outcomes, vous définissez les critères de réussite, et l’agent trouve comment les atteindre. Un évaluateur distinct vérifie le résultat dans son propre contexte, afin qu’il ne soit pas « contaminé » par le raisonnement de l’agent principal.

Dix pour cent de gain sur des tâches difficiles, c’est considérable. Surtout lorsque la tâche est formulée ainsi : « rédige un article long qui respecte ces critères de qualité », plutôt que « suis les étapes 1 à 7 ».

Dreaming : les agents accumulent de l’expérience entre les sessions

C’est la fonctionnalité la plus nouvelle sur le plan conceptuel. Un agent passe en revue les sessions passées, repère des tendances dans les réussites et les erreurs, puis met à jour le magasin de mémoire. Vous pouvez configurer une vérification manuelle avant l’application des changements, ou le laisser modifier la mémoire lui-même.

Anthropic rapporte que Harvey, une entreprise de technologie juridique, a vu le taux de réussite des tâches de rédaction juridique multiplié par environ six après l’implémentation de Dreaming. La fonctionnalité fonctionne déjà en production ; ce n’est pas qu’une démonstration.

Ce que cela signifie pour les entrepreneurs qui ne programment pas

Multi-Agent Orchestration est actuellement accessible via le Claude Agent SDK, et non directement dans la CLI de Claude Code. Mais la tendance est claire : l’orchestration passe de « vous lancez manuellement N subagents » à « vous décrivez la tâche, et l’agent principal décide à qui déléguer et comment ». Si vous débutez avec les subagents, ne vous préoccupez pas encore de la v2. Apprenez le modèle classique « 1 chat principal + 3–5 subagents aux rôles différents », puis, dans 3–6 mois, vous pourrez passer naturellement à Managed Agents.

7 erreurs qui empêchent les subagents de fonctionner#

Erreur 1. Les descriptions du type « Assistant pour X » ne déclenchent rien

Symptôme : vous avez écrit un subagent, vérifié sa structure et constaté que tout est valide, mais Claude ne l’appelle pas en réponse aux demandes des utilisateurs. La raison est presque toujours la même : la description est abstraite, comme « Assistant pour la révision de code ». La solution : ajoutez directement dans la description 3–5 formulations réelles des utilisateurs entre guillemets, ainsi que « use proactively » / « use immediately after ».

Erreur 2. Créer un subagent alors qu’il faut un Skill

Un subagent coûte plus cher qu’un Skill : il crée son propre contexte, charge son propre prompt système et consomme davantage de tokens. Si une tâche est courte, ne consomme pas le contexte principal et peut être réalisée en une seule passe, elle devrait être confiée à un Skill, pas à un subagent. Exemple d’anti-pattern : un subagent format-validator vérifie qu’un schéma JSON respecte 20 règles. Il devrait s’agir d’un Skill : un seul modèle, aucune isolation nécessaire et aucun contexte supplémentaire à charger.

Erreur 3. Lancer « 60 agents en parallèle » dès le départ

C’est l’illusion la plus répandue. Vous voyez un tweet disant « J’ai 1 500 agents en cours de travail » et vous pensez : « Je devrais faire pareil. » En réalité, 60 agents épuisent les limites d’un forfait Pro en une heure, génèrent une pile de résultats contradictoires et, à la fin de la journée, rien n’est terminé.

Un professionnel sur Medium le formule ainsi :

La solution : commencez par un subagent pour une tâche. Une fois cela maîtrisé, ajoutez-en un second avec un rôle différent. Lorsque vous maîtrisez l’orchestration de deux agents, passez à une équipe de 3–5. Passer de « j’ai installé Claude Code hier » à « j’en lance 20 en parallèle aujourd’hui » garantit des erreurs de code et l’épuisement des limites.

Erreur 4. Donner tous les outils à chaque agent

Si votre réviseur de code a accès à Bash, Write et WebFetch, cela crée une énorme faille de sécurité et de coûts. Un réviseur ne devrait pas pouvoir écrire des fichiers, encore moins accéder à Internet.

La solution : limitez strictement tools. Un réviseur de code ne reçoit que Read, Grep, Glob. Un auditeur de sécurité reçoit les mêmes outils de lecture/recherche et un diff fourni par la session principale. Bash accorde un shell, sans le limiter automatiquement à git diff. Un agent de recherche reçoit WebFetch, WebSearch, Read, Write. Ne donnez pas à un subagent plus d’autorisations que nécessaire pour une tâche précise.

Erreur 5. Un subagent renvoie des résultats bruts au contexte principal

Si un agent de recherche répond « voici les 30 pages que j’ai trouvées ; débrouille-toi » au chat principal, vous perdez le principal avantage des subagents : l’isolation du bruit. La solution : imposez explicitement un format de sortie dans le prompt système du subagent. « Renvoyez UNIQUEMENT : un TL;DR de 3 puces + une liste de 5 sources. PAS de dumps de code, PAS de résultats de recherche bruts. » Ce format doit être strict : le subagent ne doit pas pouvoir « transformer le tout en essai » comme bon lui semble.

Erreur 6. Consignes vagues : demandes de délégation imprécises

Un subagent ne peut pas voir l’historique du dialogue principal. Il démarre avec un contexte vierge + CLAUDE.md + ce que vous lui avez explicitement indiqué. Si vous écrivez « corrige l’authentification », il inventera des éléments. Précisez plutôt : « Corrige la boucle de redirection OAuth qui, après une connexion réussie, renvoie l’utilisateur vers /login au lieu de /dashboard. Fichier : src/lib/auth.ts. »

Une règle simple : lorsque vous déléguez, donnez au subagent autant de contexte qu’à un nouveau prestataire qui vient de rejoindre le projet.

Erreur 7. Des agents définis par rôle plutôt que par tâche

Un modèle tentant consiste à dire : « Créons un développeur front-end, un développeur back-end et un ingénieur QA, et faisons-les travailler en équipe. » Cela ne fonctionne pas. Chaque « rôle » perd le contexte du projet dans son ensemble, et les agents ne peuvent pas se mettre d’accord sur les détails parce qu’ils ne peuvent pas se voir.

La solution : un subagent doit prendre en charge une tâche récurrente avec un résultat clair, pas un rôle. Pas « développeur front-end », mais « explore-ui-tree », « refactor-component », « audit-accessibility ». Chaque subagent défini par tâche effectue un travail précis et renvoie un résultat précis.

Combien coûtent les subagents parallèles, et quand sont-ils rentables ?#

Un forfait Pro sera épuisé en moins d’une heure si vous lancez 5 subagents en parallèle sur des tâches complexes. Max 5x ($100) est le minimum réaliste pour un travail parallèle régulier. Pour les équipes et les entreprises, la question du coût est déjà traitée au niveau du budget des outils.

Pour découvrir d’autres moyens d’économiser des tokens dans Claude Code, consultez le guide distinct sur les limites. Pour les subagents, la règle essentielle est qu’ils sont rentables pour une tâche qui demande au moins 10 minutes de travail concentré. Si la tâche est plus courte, ne créez pas de subagent : faites-la dans le chat principal ou avec un Skill.

Comment intégrer les subagents à votre clone IA et à votre Second Brain ?#

Avant de créer votre premier spécialiste, votre projet devrait déjà disposer de trois éléments dont dépend un subagent :

1. Un CLAUDE.md adapté. Un subagent lit CLAUDE.md avant de commencer : c’est son « contrat de travail ». Sans ce fichier, il ne connaît ni le contexte du projet, ni ses restrictions, ni son ton. Il inventera des éléments.

2. Des Skills de base. Un Skill est une méthode intégrée. Un subagent ne charge que les Skills dont il a besoin, pas tous les Skills d’un coup. Sans eux, il recommence chaque fois le même travail à partir de zéro.

3. Second Brain : une structure de connaissances. Le dossier business/ (ou son équivalent dans votre domaine) est une bibliothèque consultée par tous les subagents. Sans elle, un subagent donnera une réponse moyenne de ChatGPT, impossible à distinguer de celle de n’importe qui d’autre.

Inverser cet ordre revient à obtenir du battage médiatique sans résultats. « J’ai 60 subagents en parallèle » avec un dossier business/ vide, cela revient à avoir 60 sessions ChatGPT moyennes utilisant la même approche.

La combinaison complète — clone IA + Second Brain + Context Engineering — forme les trois piliers qui rendent Claude cohérent. Les subagents font partie du clone IA : ils permettent de donner à Claude une équipe spécialisée qui travaille selon votre logique.

Pour commencer au plus vite, copiez code-reviewer du premier exemple ci-dessus dans .claude/agents/code-reviewer.md, redémarrez Claude Code et appelez @agent-code-reviewer lors de votre prochain commit. En 5 minutes, vous saurez si vous avez besoin de subagents ou si le chat principal suffit.