Tech & Performance
Sous-agents Claude Code : auditer une boutique
Sous-agents Claude Code : trois auditeurs en lecture seule (tracking, flux produits, Google Ads), lancés en parallèle puis fusionnés en un seul rapport.
Un audit de boutique e-commerce fait lire trois familles de fichiers de natures différentes : la configuration du tracking, le flux produits et les résultats publicitaires. Dans une seule conversation, les trois lectures s'empilent dans le même contexte. Claude Code permet de les confier à des sous-agents, des assistants spécialisés qui travaillent chacun dans leur propre fenêtre de contexte et ne renvoient qu'un résumé. Ce guide décrit comment en définir trois en lecture seule, les lancer en parallèle, fusionner leurs constats et borner le coût.
Les faits cités viennent de la documentation de Claude Code (sous-agents, skills, mode non interactif, permissions) et de la spécification des données produit de Google Merchant Center, consultées le 11 octobre 2026. Les trois auditeurs d'exemple sont notre assemblage de ces pages : aucune n'en publie de semblables.
Ce qu'un sous-agent change
D'après la documentation des sous-agents, on en utilise un quand une tâche annexe inonderait la conversation de résultats de recherche, de journaux ou de contenus de fichiers que l'on ne relira pas : le sous-agent fait ce travail dans son propre contexte et ne renvoie que le résumé. Chacun a son prompt système, ses outils et ses permissions propres. Claude choisit de lui déléguer une tâche d'après le champ description de sa définition.
La même page recommande la conversation principale quand la tâche demande des allers-retours fréquents ou que plusieurs phases partagent beaucoup de contexte. Un audit en trois volets indépendants coche les critères inverses : chaque volet est autonome et se résume en quelques constats.
Le dossier de travail
audit-client-a/
CLAUDE.md contexte du client (marché, marges, objectifs)
.claude/agents/
tracking-auditor.md
feed-auditor.md
ads-auditor.md
data/
gtm/ exports JSON du conteneur Tag Manager
merchant/ fichier de la source de données produits
ads/ rapports Google Ads datés
rapports/ rapport d'audit fusionnéLes données arrivent par les méthodes décrites dans nos guides : l'export JSON de la version publiée d'un conteneur avec l'API Tag Manager, les rapports hebdomadaires produits par un skill de reporting, et le fichier de votre source de données produits (texte ou XML) ou un export obtenu avec le serveur Merchant Center. Les auditeurs ne lisent que des fichiers locaux : ils n'ont aucun accès direct aux comptes.
Définir un sous-agent en lecture seule
Un sous-agent est un fichier Markdown de .claude/agents/ (projet) ou de ~/.claude/agents/ (tous vos projets). L'en-tête YAML exige seulement name et description ; le corps devient son prompt système. La documentation précise que le sous-agent ne reçoit que ce prompt et des informations de base sur l'environnement, pas le prompt système de Claude Code, et qu'il charge tout de même les fichiers CLAUDE.md : le contexte du client lui parvient.
---
name: tracking-auditor
description: Audite l'export JSON d'un conteneur Google Tag Manager rangé dans data/gtm. À utiliser pour les questions sur les balises, les déclencheurs et les consentements.
tools: Read, Grep, Glob
model: sonnet
maxTurns: 20
---
Tu audites uniquement les fichiers de data/gtm. Tu ne modifies aucun fichier.
Contrôles :
1. Balises dont "paused" vaut true.
2. Balises dont "firingTriggerId" est vide.
3. Balises dont "scheduleEndMs" correspond à une date passée.
4. Balises dont "consentStatus" vaut "notSet".
5. Balises dont "tagFiringOption" vaut "unlimited".
Pour chaque constat, cite le fichier, le nom de la balise et le champ lu.
Si une information n'est pas dans les fichiers, écris NA. N'estime rien.
Réponds par une liste courte, du plus au moins important.Quatre champs méritent une explication, d'après la table de référence de la documentation :
toolsest une liste d'autorisation. Omis, le sous-agent hérite de tous les outils disponibles pour les sous-agents. AvecRead, Grep, Glob, il lit et cherche, sans modifier ni écrire de fichier et sans outil MCP. Nous n'avons pas ajouté Bash : un shell ouvert aurait permis à l'auditeur d'écrire ou d'exécuter n'importe quoi.modelacceptesonnet,opus,haiku,fable, un identifiant complet ouinherit. Sans valeur, Claude Code applique l'ordre de résolution de la documentation, qui finit par le modèle de la conversation principale. La documentation range le choix d'un modèle plus léger parmi les moyens de maîtriser le coût.maxTurnsfixe le nombre maximal de tours avant l'arrêt du sous-agent. À la limite, Claude Code renvoie sa sortie marquée comme partielle et Claude peut le reprendre (le marquage demande Claude Code v2.1.246 ou plus). La valeur 20 est un choix de départ de notre part.descriptionpilote la délégation automatique. La documentation conseille de la garder courte, car les descriptions occupent du contexte, et d'y inclure « use proactively » pour encourager une délégation spontanée. Nous préférons une description qui nomme précisément le dossier lu.
Claude Code surveille .claude/agents/ : un fichier ajouté ou modifié est pris en compte en quelques secondes, sauf pour un dossier agents créé après le début de la session, qui demande un redémarrage. Un fichier sans name ou sans description est ignoré sans message dans la session ; la commande claude plugin validate .claude/agents repère ceux dont l'en-tête ne s'analyse pas (Claude Code v2.1.233 ou plus).
Les deux autres auditeurs
Les deux fichiers suivent le même modèle, avec un dossier, des contrôles et la même consigne de citer ses sources. Les contrôles du flux s'appuient sur la spécification des données produit de Google Merchant Center ; ceux de Google Ads sur les colonnes du rapport produit par le skill.
| Sous-agent | Dossier lu | Contrôles |
|---|---|---|
feed-auditor | data/merchant | Attribut id unique et de 50 caractères au plus ; title de 150 caractères au plus ; description de 5 000 caractères au plus, sans texte promotionnel du type « free shipping » ni majuscules intégrales ; link et image_link renseignés ; brand rempli pour les produits neufs, vide pour un produit réellement sans marque, jamais avec « N/A » ou « Generic » |
ads-auditor | data/ads | Campagnes dont le coût monte sur la semaine alors que la valeur de conversion baisse ; campagnes dépensières sans conversion ; écarts entre deux rapports successifs |
Les valeurs du tableau viennent de la spécification : l'identifiant est requis, unique et limité à 50 caractères ; le titre est requis et limité à 150 caractères ; la description est limitée à 5 000 caractères et ne doit pas contenir de texte promotionnel comme « free shipping » ni de majuscules intégrales ; le lien et l'image principale sont requis ; la marque est requise pour tous les nouveaux produits sauf films, livres et enregistrements musicaux, et Google demande de ne pas soumettre de valeurs comme « N/A », « Generic », « No brand » ou « Does not exist » ; pour un produit réellement sans marque, le champ reste vide. La page annonce aussi une exigence de taille d'image d'au moins 500 x 500 pixels, dont l'application commence le 31 janvier 2027 : un fichier de flux ne contient, à notre lecture, que l'adresse de l'image et pas ses dimensions, ce contrôle demande donc un autre outil. Un auditeur de flux ne lit que des attributs de fichier : il ne voit ni le statut d'approbation dans Merchant Center ni les diagnostics du compte.
Les lancer en parallèle et fusionner
La documentation donne le schéma de la recherche parallèle : demander à Claude de traiter des modules distincts avec des sous-agents séparés. Chaque sous-agent explore son périmètre, puis Claude synthétise. Le schéma convient quand les pistes ne dépendent pas les unes des autres, ce qui est le cas ici. Une demande type, depuis le dossier du client :
Lance en parallèle tracking-auditor, feed-auditor et ads-auditor, chacun sur son dossier.
Fusionne leurs constats dans rapports/audit-AAAA-MM-JJ.md : un tableau trié par impact,
avec pour chaque ligne le sous-agent source, le fichier et le champ cités.
Signale les contrôles revenus en NA. N'ajoute aucun constat qu'un sous-agent n'a pas cité.Pour garantir qu'un sous-agent précis intervienne, la documentation propose le @-mention, qui impose le sous-agent au lieu de laisser Claude décider. En session interactive, les sous-agents tournent par défaut en arrière-plan ; une invite d'autorisation qu'ils déclenchent apparaît dans la session principale avec le nom du sous-agent demandeur.
Le rapport fusionné est écrit par la conversation principale : c'est elle qui a besoin de l'autorisation d'écrire dans rapports/, pas les auditeurs. Un lancement sans interface, avec un plafond de dépense qui inclut celle des sous-agents :
cd audit-client-a
claude -p "Lance en parallèle tracking-auditor, feed-auditor et ads-auditor, puis écris la synthèse dans rapports/audit.md" \
--allowedTools "Edit(rapports/**)" \
--max-budget-usd 5Trois précisions tirées de la documentation. Sans --bare, une session -p charge les sous-agents de .claude/agents/ ; avec --bare, ils sont ignorés. La dépense peut dépasser le plafond, et l'estimation se fait côté client. Enfin, pour des définitions trop longues à passer en ligne de commande, --agents accepte avec -p le chemin d'un fichier JSON (Claude Code v2.1.281 ou plus).
Ce qui peut mal tourner
- Un flux produit contient du texte rédigé par d'autres que vous : titres, descriptions, avis éventuels. D'après la documentation, Claude Code analyse le rapport final de chaque sous-agent avant que Claude le lise, pour neutraliser les textes qui imitent la sortie de Claude Code (balises système, lignes « Human: »), sans changer ce qu'une instruction peut déclencher ; elle précise que cette analyse ne remplace pas la restriction de ce que le sous-agent peut atteindre. Nos auditeurs n'ont ni shell, ni écriture, ni MCP : un texte piégé ne leur fait exécuter aucune commande. Il peut en revanche fausser leur rapport, d'où l'obligation de citer la source de chaque constat.
- Ce qui revient dans la conversation principale est un résumé. D'où la consigne de citer fichier et champ à chaque constat : sans référence, vous ne pouvez pas vérifier la ligne.
- La documentation avertit que de nombreux sous-agents renvoyant des résultats détaillés consomment du contexte dans la conversation principale, et que chacun dépense des jetons pendant son exécution.
- Vingt sous-agents en même temps par défaut : trois auditeurs sont loin du plafond, mais un script qui en lancerait un par produit s'y heurterait.
Aller plus loin avec un skill
Un skill peut déléguer son exécution à un sous-agent : avec context: fork, Claude Code démarre un sous-agent du type désigné par le champ agent (un agent intégré ou n'importe quel sous-agent de .claude/agents/) et lui donne le contenu du skill comme prompt. Ce sous-agent ne voit pas l'historique de votre conversation, donc les consignes du skill doivent se suffire à elles-mêmes. La documentation prévient aussi qu'un skill de ce type n'a de sens que s'il contient une tâche explicite, pas de simples lignes directrices. Notre guide sur le choix de skills pour le marketing détaille leur périmètre.
Par où commencer
- Créer le dossier du client, son
CLAUDE.mdet les trois sous-dossiers de données. - Écrire un seul sous-agent, par exemple
tracking-auditor, avectools: Read, Grep, Glob. - Le lancer seul, vérifier chaque constat à la source dans le fichier, et corriger son prompt.
- Ajouter les deux autres, puis demander l'exécution en parallèle et la fusion.
- Fixer un plafond avec
--max-budget-usdavant tout lancement sans interface.
Questions fréquentes sur les sous-agents Claude Code
Un sous-agent peut-il utiliser les outils MCP ?
Par défaut, un sous-agent hérite des outils intégrés et des outils MCP de la conversation principale. D’après la documentation de Claude Code, un champ tools qui ne liste que Read, Grep, Glob et Bash retire au sous-agent les outils d’édition et d’écriture de fichiers et tous les outils MCP. Bash reste un shell qui peut écrire par commande : c’est pourquoi nos auditeurs n’ont pas Bash. Le champ mcpServers donne en plus accès à des serveurs absents de la conversation principale.
Combien de sous-agents peuvent tourner en même temps ?
Par défaut, quand 20 sous-agents tournent dans une session, en lancer un de plus échoue avec l’erreur « Concurrent subagent limit reached ». La variable d’environnement CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS change cette limite. Le nombre total de sous-agents sur une session n’est pas plafonné, et un sous-agent peut en lancer d’autres jusqu’à trois niveaux sous la conversation principale, valeur modifiable.
Les sous-agents coûtent-ils plus cher qu’une seule conversation ?
Chaque sous-agent envoie ses propres requêtes, qui comptent dans les mêmes limites d’usage que la conversation principale, et la documentation avertit que lancer beaucoup de sous-agents qui renvoient des résultats détaillés consomme du contexte et des jetons. Leur dépense compte dans le plafond de --max-budget-usd. Le champ model permet d’affecter un modèle plus léger, par exemple haiku, à une tâche mécanique.
Sous-agent ou skill : lequel choisir ?
La documentation recommande les sous-agents pour une tâche qui produit beaucoup de sortie dont vous n’avez pas besoin dans la conversation, qui exige des restrictions d’outils, ou qui est autonome et renvoie un résumé. Elle renvoie vers les skills pour des prompts ou workflows réutilisables qui s’exécutent dans le contexte de la conversation principale. Les deux se combinent : un skill avec context: fork et un champ agent s’exécute dans le sous-agent désigné.