À retenir
- Un sous-agent = un fichier Markdown dans
.claude/agents/avec deux champs YAML obligatoires :nameetdescription— tout le reste est optionnel - Isolation du contexte : le sous-agent tourne dans sa propre fenêtre, seul son résumé remonte à la conversation principale — votre contexte reste propre
- Coût officiel : selon la documentation Anthropic, les équipes d'agents consomment environ 7× plus de tokens en mode plan — choisir
model: haikupour les tâches simples divise la facture sans sacrifier la qualité - Profils non-dev inclus : des sous-agents pour rédiger des emails, synthétiser des réunions ou auditer du contenu SEO sont aussi pertinents que les agents de revue de code
Un consultant indépendant utilise Claude Code depuis plusieurs mois pour générer du code. Un jour, il demande à Claude d'analyser simultanément la concurrence, de rédiger un rapport et de mettre à jour trois fichiers de documentation — tout ça dans la même conversation. Résultat : le contexte explose à mi-chemin, Claude perd le fil, et il faut recommencer de zéro. Les sous-agents Claude Code existent précisément pour éviter ça.
Ce guide vous explique comment les créer, les configurer et les utiliser — que vous soyez développeur ou non.
Ce qu'est vraiment un sous-agent Claude Code
Un sous-agent Claude Code est un assistant IA spécialisé qui s'exécute dans sa propre fenêtre de contexte isolée, avec des outils et des permissions configurables définis dans un fichier Markdown. Il permet de déléguer une tâche secondaire sans polluer la conversation principale et retourne uniquement un résumé des résultats.
Pensez-y comme à la différence entre un généraliste surchargé et une équipe de spécialistes : au lieu d'avoir une seule conversation qui cumule la recherche, l'analyse et la rédaction, vous déléguez chaque mission à un agent dédié qui travaille dans son coin. La conversation principale ne reçoit que la synthèse finale — pas les 200 lignes de logs intermédiaires.
Contexte isolé
Outils sur mesure
Optimisation des coûts
Réutilisabilité
Ce que la documentation officielle ne dit pas clairement
La doc officielle Anthropic est exhaustive sur la syntaxe, mais elliptique sur le cas d'usage non-développeur. La moitié des professionnels qui utilisent Claude Code quotidiennement ne font pas de code — ils rédigent, analysent, synthétisent. Les sous-agents sont tout aussi utiles pour eux.
💡 Bon à savoir : Les sous-agents ne nécessitent aucune compétence en programmation pour être créés. Un fichier Markdown de 10 lignes avec deux champs YAML (
nameetdescription) suffit — le reste du prompt est rédigé en langage naturel.
Claude
Claude Code est la CLI agentique d'Anthropic : lit, écrit et exécute du code, gère Git, supporte les serveurs MCP et les sous-agents. Disponible en extension VS Code et Cursor.
Créer votre premier sous-agent en 5 étapes
La méthode la plus rapide pour débuter : demander directement à Claude de créer le fichier à votre place. Tapez dans Claude Code : « Crée un sous-agent qui synthétise les notes de réunion en compte-rendu structuré, avec uniquement l'outil Read et le modèle Haiku. » Claude génère le fichier dans .claude/agents/ et vous n'avez plus qu'à vérifier.
Pour ceux qui préfèrent comprendre avant d'utiliser, voici la méthode manuelle :
Choisir la portée
Décidez si votre sous-agent est spécifique à un projet (.claude/agents/) ou disponible partout (~/.claude/agents/). Règle pratique : un agent de synthèse de réunion générique va dans ~/.claude/agents/ ; un agent de validation SQL lié à votre base de données spécifique va dans .claude/agents/ du projet.
Créer le fichier Markdown
Créez le dossier et le fichier : mkdir -p .claude/agents && touch .claude/agents/mon-agent.md. Le nom du fichier n'a pas d'importance — c'est le champ name dans le YAML qui compte.
Écrire le frontmatter YAML
Ajoutez en tête du fichier le bloc YAML entre ---. Deux champs sont obligatoires : name (identifiant unique, minuscules et tirets) et description (quand Claude doit déléguer à cet agent). Les autres champs sont optionnels mais puissants.
Écrire le prompt système
Après le bloc YAML, écrivez en Markdown le comportement attendu du sous-agent. C'est son prompt système : instructions, format de sortie attendu, règles à respecter. Plus c'est précis, plus le routage automatique est fiable.
Tester et déclencher
Vérifiez que Claude détecte votre sous-agent avec la commande /agents. Pour l'invoquer explicitement : @nom-du-sous-agent [votre instruction]. Pour le déclenchement automatique, assurez-vous que la description contient des déclencheurs clairs du type « Déclenche quand l'utilisateur demande… ».
/agents n'ouvre plus d'assistant de configuration interactif — elle affiche un message de rappel invitant à demander directement à Claude ou à éditer manuellement les fichiers dans .claude/agents/.La structure d'un fichier de sous-agent
Voici un exemple minimal fonctionnel pour un synthétiseur de réunion — cas d'usage courant pour un chef de projet ou un consultant :
---
name: synthétiseur-réunion
description: Synthétise les notes ou transcriptions de réunion en compte-rendu structuré. Déclenche quand l'utilisateur demande un résumé, un compte-rendu ou une synthèse de réunion.
tools:
- Read
model: haiku
---
Tu es un assistant de productivité spécialisé dans la synthèse de réunions. À partir des notes ou transcriptions fournies, produis un compte-rendu en 3 sections : (1) Décisions prises, (2) Actions à suivre avec responsables et délais, (3) Points ouverts à clarifier. Format : Markdown structuré, titres clairs, pas de reformulation inutile.
Les champs les plus utiles du frontmatter YAML :
5 templates prêts à copier-coller (dont 3 non-dev)
Aucun des contenus disponibles dans le SERP francophone ne propose de templates complets pour des usages métier non-techniques. Voici cinq exemples testés, avec leur frontmatter complet.
Template 1 — Analyste SEO (pour un consultant marketing ou rédacteur web) :
---
name: analyseur-seo
description: Analyse les métadonnées SEO d'une page ou d'un fichier HTML. Déclenche quand l'utilisateur demande une analyse SEO, un audit de page ou une vérification de balises.
tools:
- Read
- WebFetch
- Bash
model: haiku
---
Tu es un expert SEO. Analyse les pages demandées : title (longueur, mot-clé), meta description (longueur, accroche), structure H1-H6, densité de mots-clés, liens internes/externes. Retourne un rapport structuré avec : (1) Score global /10, (2) Points bloquants, (3) Recommandations prioritaires.
Template 2 — Rédacteur d'emails professionnels (pour un commercial ou responsable RH) :
---
name: rédacteur-email
description: Rédige ou reformule des emails professionnels dans un style clair et direct. Déclenche quand l'utilisateur demande de rédiger, améliorer ou reformuler un email.
tools:
- Read
model: haiku
---
Tu es un expert en communication écrite professionnelle. Rédige des emails clairs, directs et adaptés au contexte (relance, proposition commerciale, refus, suivi). Toujours : (1) Objet accrocheur en une ligne, (2) Corps structuré en 3 paragraphes max, (3) Appel à l'action clair en conclusion.
Template 3 — Auditeur de documents (pour un cabinet RH, juridique ou financier) :
---
name: auditeur-conformité
description: Vérifie la conformité d'un document par rapport à une liste de critères fournie. Déclenche quand l'utilisateur demande une vérification, un audit ou une revue de document.
tools:
- Read
model: sonnet
---
Tu es un auditeur rigoureux. À partir du document fourni et des critères de conformité spécifiés, produis une checklist : chaque critère = Conforme ✓ / Non-conforme ✗ / Partiel ⚠ avec citation textuelle du passage concerné. Conclus par un score de conformité global en pourcentage.
Template 4 — Relecteur de code (lecture seule) (pour un développeur) :
---
name: code-reviewer
description: Relit le code fourni pour détecter les bugs, failles de sécurité et mauvaises pratiques. Déclenche pour une revue de code, une analyse de qualité ou une détection de vulnérabilités. Ne modifie aucun fichier.
tools:
- Read
- Grep
- Glob
model: sonnet
---
Tu es un expert en qualité logicielle. Analyse le code fourni et produis un rapport : (1) Bugs identifiés avec ligne et correction suggérée, (2) Risques de sécurité (injection, XSS, secrets hardcodés…), (3) Dette technique majeure, (4) Score de maintenabilité /10.
Template 5 — Validateur de requêtes SQL (lecture seule) (pour un analyste data) :
---
name: sql-validator
description: Valide et optimise les requêtes SQL sans jamais exécuter de modification. Déclenche quand l'utilisateur demande de vérifier, optimiser ou expliquer une requête SQL.
tools:
- Read
disallowedTools:
- Bash
model: haiku
---
Tu es un DBA expert. Analyse les requêtes SQL soumises : (1) Syntaxe valide ?, (2) Risques (full scan, cartesian product, injection), (3) Suggestions d'optimisation (index, réécriture), (4) Estimation de la complexité. Ne jamais suggérer d'exécuter une requête en écriture.
Quand utiliser les sous-agents — et quand les éviter
Les sous-agents consomment environ 7× plus de tokens qu'une session standard en mode plan — le déléguer a donc un coût réel. Ce surcoût est rentable quand la tâche est volumineuse ou parallélisable ; il ne l'est pas pour une question rapide.
La documentation officielle Anthropic est honnête sur le sujet : chaque agent maintient sa propre fenêtre de contexte et s'exécute comme une instance Claude séparée. Ce n'est pas gratuit.
La réponse tient en deux cas symétriques :
Orchestration avancée : plusieurs sous-agents en parallèle
Pour les tâches complexes — une analyse concurrentielle complète, un audit de documentation ou la génération simultanée de plusieurs rapports — vous pouvez orchestrer plusieurs sous-agents en parallèle via les git worktrees.
Le principe : chaque worktree est une copie de travail isolée du dépôt qui partage la même base .git. Chaque agent Claude Code opère dans son worktree sans interférer avec les autres.
Créer les worktrees
Créez autant de worktrees que d'agents à paralléliser : git worktree add .worktrees/agent-scraping -b feat/scraping puis git worktree add .worktrees/agent-analyse -b feat/analyse. Chaque dossier devient un environnement de travail indépendant.
Lancer les agents en arrière-plan
Dans votre conversation principale, demandez à Claude de déléguer vers les sous-agents configurés avec background: true. Claude lance les agents, continue à répondre à vos questions pendant qu'ils travaillent, et vous notifie quand ils ont terminé.
Collecter et synchroniser les résultats
Chaque sous-agent écrit ses résultats dans un fichier partagé (par exemple data/results-agent-1.json). L'agent orchestrateur lit ces fichiers une fois tous les agents terminés et produit la synthèse finale.
💡 Bon à savoir : Quatre patterns d'orchestration multi-agents sont documentés par la communauté (source : SpillwaveSolutions/parallel-worktrees) : Competitive Implementation (N agents, meilleur résultat sélectionné), Divide and Conquer (chaque agent prend une piste indépendante), Exploration Sprint (plusieurs approches testées en parallèle) et Test-First Parallel (tests et implémentation en simultané).
Quatre patterns d'orchestration reconnus
Competitive Implementation
Divide and Conquer
Exploration Sprint
Test-First Parallel
Troubleshooting : les 6 erreurs fréquentes et leurs solutions
La documentation officielle couvre la syntaxe. Voici les problèmes que vous rencontrerez en pratique, d'après les issues GitHub de Claude Code :
Sous-agent qui ne se déclenche pas
Conflit de noms de sous-agents
Sous-agent avec zéro outils
Hooks de frontmatter ignorés
Modèle non disponible
Répertoire de travail persistant (bug connu)
💡 Bon à savoir : La commande
/doctorde Claude Code est votre premier réflexe de débogage. Elle détecte automatiquement les conflits de noms, les outils mal orthographiés et les problèmes de configuration — avant de passer des heures à chercher un bug dans votre prompt système.
Optimiser les coûts : choisir le bon modèle pour chaque tâche
Le champ model dans le frontmatter est votre levier principal de contrôle des coûts. La règle de base est simple : tâche simple → Haiku, tâche complexe → Sonnet, raisonnement avancé → Opus.
Autres leviers d'optimisation issus de la documentation officielle Anthropic :
- 🔌 Désactivez les serveurs MCP inutilisés : leurs définitions d'outils alourdissent le contexte de chaque agent
- 🧹 Utilisez
/clearentre les tâches sans lien entre elles pour repartir d'un contexte propre - 📝 Gardez les prompts d'initialisation ciblés : les équipiers chargent CLAUDE.md et les serveurs MCP automatiquement, inutile de les répéter dans le prompt
Dans quel contexte professionnel adopter les sous-agents ?
Les sous-agents sont particulièrement pertinents dans les entreprises qui souhaitent donner de l'autonomie à l'IA tout en gardant un contrôle précis sur ses actions. Selon l'INSEE (enquête TIC entreprises, juillet 2026), 18% des entreprises françaises de 10 salariés ou plus déclarent utiliser au moins une technologie d'intelligence artificielle en 2025 — contre 6% en 2023, soit un triplement en deux ans.
Mais 71% des entreprises déclarent ne pas encore faire pleinement confiance aux agents IA autonomes pour un usage opérationnel (Capgemini, 2025). Ce chiffre révèle le vrai enjeu : ce n'est pas la puissance technique qui freine l'adoption, c'est le manque de visibilité sur ce que l'agent fait réellement.
Les sous-agents Claude Code répondent à cette préoccupation par construction : vous définissez exactement les outils autorisés, vous pouvez les restreindre en lecture seule, et vous pouvez ajouter des hooks de validation pour intercepter chaque action avant qu'elle s'exécute.
Pour une PME industrielle ou un cabinet RH qui hésite à donner de l'autonomie à un agent IA, un sous-agent avec uniquement Read et aucun accès à Bash ou Write est techniquement incapable de modifier quoi que ce soit — une garantie structurelle que nulle politique interne ne peut offrir aussi simplement.
Pour aller plus loin sur l'utilisation de Claude Code au quotidien, consultez notre guide complet Claude Code pour débutants ou notre article sur comment utiliser Claude Code en 2026. Si vous souhaitez maîtriser Claude Code étape par étape, notre guide de formation détaillé couvre l'ensemble de l'écosystème.
Découvrez nos formations IA
Sources et références
- Create custom subagents - Claude Code Docs (2026) — Documentation officielle Anthropic sur la création et configuration des sous-agents
- Manage costs effectively - Claude Code Docs (2026) — Données officielles sur la consommation de tokens des équipes d'agents (7×)
- Créer des sous-agents personnalisés - Claude Code Docs FR (2026) — Version française de la documentation officielle
- INSEE - TIC entreprises 2025 (juillet 2026) — 18% des entreprises françaises utilisent au moins une technologie IA
- Capgemini - L'IA générative dans les entreprises en 2025 (2025) — 71% des entreprises ne font pas encore confiance aux agents autonomes
- Claude Code GitHub Issues #8501 (2026) — Bug YAML frontmatter et troubleshooting officiel
- SpillwaveSolutions/parallel-worktrees (2026) — Patterns d'orchestration multi-agents avec git worktrees
Questions fréquentes sur les sous-agents Claude Code
Quelle est la différence entre un sous-agent et une conversation normale dans Claude Code ?
Dans une conversation normale, tout le contexte (logs, données, réponses intermédiaires) s'accumule dans la même fenêtre et consomme vos tokens. Un sous-agent s'exécute dans sa propre fenêtre isolée : il traite la tâche en autonomie et ne retourne à la conversation principale qu'un résumé compact. Résultat : votre contexte principal reste propre, et vous pouvez déléguer des traitements volumineux sans risquer de le saturer.
Peut-on utiliser les sous-agents Claude Code sans être développeur ?
Oui, et c'est même l'un des angles les moins exploités. Un synthétiseur de réunion, un rédacteur d'emails ou un auditeur de conformité documentaire ne nécessitent aucune compétence en développement pour être créés — seulement un fichier Markdown avec quelques lignes de YAML et un prompt en langage naturel. Les deux seuls champs obligatoires sont name et description.
Les sous-agents Claude Code sont-ils plus chers à utiliser que la conversation principale ?
Oui. La documentation officielle Anthropic précise que les équipes d'agents consomment environ 7× plus de tokens qu'une session standard en mode plan, car chaque agent maintient sa propre fenêtre de contexte. Ce surcoût est compensé quand la tâche délégée est volumineuse (logs, documents longs) ou quand plusieurs agents tournent en parallèle pour réduire le temps total. Pour les tâches simples, mieux vaut rester en conversation principale et choisir Claude Haiku comme modèle de sous-agent pour minimiser la facture.
Comment empêcher un sous-agent de modifier des fichiers par erreur ?
Deux mécanismes complémentaires : le champ tools en whitelist (listez uniquement Read, Grep, Glob et excluez Write, Edit, Bash) et le champ disallowedTools en blacklist pour une interdiction explicite. Un sous-agent configuré avec uniquement tools: [Read] est techniquement incapable d'écrire quoi que ce soit — la contrainte est structurelle, pas comportementale.
Quelle est la différence entre un sous-agent, une équipe d'agents et un workflow dynamique dans Claude Code ?
Les trois approches diffèrent par leur niveau d'autonomie et leur structure. Un sous-agent est une unité spécialisée prédéfinie dans un fichier Markdown, invocable à la demande ou automatiquement. Une équipe d'agents (agent teams) est un groupe de sous-agents coordonnés par un orchestrateur pour une tâche complexe multi-étapes. Un workflow dynamique laisse Claude générer et coordonner ses propres agents à la volée sans fichiers prédéfinis — le niveau d'autonomie le plus élevé, mais aussi le moins prédictible et le plus coûteux en tokens.
Comment déboguer un sous-agent qui ne se déclenche pas automatiquement ?
Première vérification : la description est-elle assez précise ? Si elle est trop générique, Claude ne sait pas quand déléguer. Reformulez avec des déclencheurs explicites (« Déclenche quand l'utilisateur mentionne une réunion… »). Deuxième vérification : exécutez /doctor dans Claude Code — cette commande détecte les conflits de noms, les outils mal orthographiés et les problèmes de configuration courants. Troisième vérification : testez l'invocation explicite avec @nom-du-sous-agent pour isoler le problème (routage automatique vs configuration).
Conclusion
Les sous-agents Claude Code ne sont pas une fonctionnalité réservée aux développeurs experts. Un fichier Markdown de 10 lignes suffit à créer un assistant spécialisé qui préserve votre contexte, contrôle ses propres permissions et peut s'exécuter en parallèle avec d'autres tâches.
Le bon réflexe à avoir avant toute tâche répétitive dans Claude Code : « Est-ce que je pourrais déléguer ça à un agent dédié ? » Si la réponse est oui et que la tâche a de la profondeur — synthèse, audit, revue, extraction — un sous-agent Haiku coûtera moins cher que de laisser la conversation principale s'alourdir.
La formation Claude Code de The Intelligence Academy couvre Claude Code en profondeur, y compris la création de workflows multi-agents pour les professionnels qui veulent aller au-delà de l'usage conversationnel.