Subagents Claude Code 2026 : ton équipe IA en parallèle

Mardi soir. Tu refactor 17 composants à la main avec Claude Code. Au 8e, ton contexte sature. Claude commence à oublier ce qu'il a vu au début. Tu redémarres une session. Tu repars de zéro. C'est exactement ce qu'Anthropic a voulu tuer avec son premier deep-dive officiel sur les subagents, publié le 7 avril 2026. Le mental model qu'ils proposent, c'est neuf : un subagent, c'est un onglet de navigateur dans Claude Code. Tu en ouvres un, tu creuses, tu reviens avec juste la conclusion. Voici les 3 patterns que je tourne sur le repo VibesMoney depuis 6 semaines.

Avant de déléguer à un subagent, il faut savoir packager un workflow. Si tu n'as jamais touché aux skills, commence par packager une Claude Skill en 30 minutes. Skill et subagent sont les deux jambes de Claude Code en 2026. Confondre les deux, c'est le piège numéro un.

C'est quoi un subagent Claude Code, expliqué simple ?

Un subagent Claude Code, c'est une instance Claude isolée. Son propre contexte, ses propres outils, ses propres permissions. Anthropic les compare aux browser tabs depuis le post officiel du 7 avril 2026 : tu ouvres un onglet, tu creuses, tu reviens à l'onglet principal avec juste la conclusion. Le contexte de ta conversation principale reste propre. Trois subagents sont fournis built-in : Explore, Plan, et general-purpose.

Concrètement, voici ce qui se passe quand un subagent est appelé. Tu demandes à Claude "audite la stack de mon backend, 47 fichiers". Claude reconnaît la tâche, déclenche le subagent Explore. Le subagent ouvre sa propre fenêtre de mémoire, lit les 47 fichiers, fait sa synthèse. Il revient à ton Claude principal avec un résumé de 10 lignes. Le contenu brut des 47 fichiers ne pollue jamais ton contexte principal.

L'analogie des browser tabs est juste. Quand tu cherches une info pour un projet, tu n'as pas besoin de garder 30 onglets ouverts en permanence. Tu en ouvres un, tu lis, tu fermes, tu reviens à ton onglet principal. Le subagent fait pareil. Il préserve la qualité du contexte qui existe déjà, plutôt que de rendre Claude plus intelligent.

Anecdote concrète. Un founder qu'on accompagne dans le programme VibesMoney tournait 6 onglets Claude Code en même temps pour découper son repo en modules. Chaque onglet avait son propre fil de conversation, et il devait copier-coller les conclusions à la main entre les onglets. Avec 1 seule fenêtre Claude Code et 4 subagents en parallèle, il a fait le même travail dans une seule conversation. Temps gagné : 40%. Et plus important, zéro perte de contexte au moment de la synthèse finale.

Les subagents sont stockés dans .claude/agents/ à la racine de ton repo (niveau projet) ou dans ~/.claude/agents/ (niveau user, dispo sur tous tes projets). Format : un fichier markdown par subagent, avec un frontmatter YAML en haut. La doc officielle d'Anthropic insiste sur la scope : un subagent doit avoir un job précis, pas une mission floue.

Subagent, skill, slash command : la matrice qui clarifie 90% des bugs

Subagent, skill, slash command : 3 outils proches, radicalement différents. Skill = workflow répété, déclenché par toi via /skill-name. Subagent = délégation autonome, déclenché par Claude tout seul quand la description matche. Slash command = simple raccourci de prompt manuel. Confondre les 3 = bug d'activation garanti. Sur les founders qu'on observe dans le programme, beaucoup créent un subagent qui n'est jamais appelé.

Le piège classique du débutant : tu vois un thread Twitter qui dit "j'ai créé un subagent code-reviewer", tu te dis "je vais faire pareil pour mes briefs blog". Sauf que tu drafts toi-même tes briefs 3 fois par semaine, à des moments choisis. Une skill aurait suffi. Le subagent ajoute de la complexité (contexte isolé, auto-routing, frontmatter spécifique) qui ne sert que quand TU veux que Claude délègue tout seul.

Voici la matrice qu'on enseigne dans le programme VibesMoney. Cinq lignes, cinq déclencheurs, cinq usages distincts. Lis-la lentement, c'est ce qui clarifie 90% des bugs d'activation :

Définition rapide. Une slash command, c'est une commande qui commence par / que tu tapes toi-même. Une skill et un subagent peuvent tous les deux être déclenchés par Claude, mais la skill reste un workflow répétitif que tu lances en général à la main, alors que le subagent est conçu pour la délégation totale. La règle simple : si tu décides quand l'invoquer, c'est une skill. Si Claude décide tout seul, c'est un subagent.

Anecdote du programme. J'ai mis 3 jours à comprendre cette différence quand j'ai démarré sur Claude Code en 2026. J'ai packagé draft-article en skill, puis voulu en faire un subagent pour automatiser plus. Mauvaise décision : moi je veux décider quand drafter un article, pas laisser Claude le faire dès qu'il pense que c'est pertinent. La skill était la bonne réponse. C'est ce qu'on creuse en détail dans écrire une spec qui décuple Claude Code : tu cadres l'output ET le déclencheur.

Quand un subagent gagne, et quand il fait perdre du temps

Anthropic a posé la règle officielle dans le post du 7 avril 2026 : un subagent vaut le coup quand la tâche touche 10+ fichiers OU implique 3+ tâches indépendantes en parallèle. En dessous, l'overhead (ouvrir le subagent, lui passer le contexte, attendre le retour) coûte plus que le gain. Cas réussis : recherche large dans le repo, review pré-commit, fix bug en parallèle. Cas ratés : tâche séquentielle où l'étape 2 a besoin du contexte complet de l'étape 1.

Voici les 4 cas typiques où un subagent te fait gagner du temps :

• Recherche large dans un repo. Tu veux comprendre comment l'auth est structurée dans 30 fichiers. Le subagent Explore lit, synthétise, te rend 10 lignes. Ton main Claude n'est jamais saturé.
• Refactor parallèle sur fichiers indépendants. 3 subagents qui travaillent chacun sur 5 composants sans conflit. Total : 3× plus rapide qu'en séquentiel.
• Fresh-eyes review. Un subagent vierge qui review ton code sans le contexte du main Claude. Il attrape ce que ton agent principal rate par habitude de session.
• Pre-commit verification. Un subagent code-reviewer qui passe sur les diffs avant que tu commit, sans polluer ton contexte de feature.

Et voici les 3 cas où un subagent te ralentit :

1. Tâche séquentielle dépendante. L'étape 2 a besoin du contexte complet de l'étape 1. Le subagent ne te rend qu'un résumé. Tu perds des nuances critiques.
2. Édition parallèle du même fichier. Deux subagents qui modifient le même fichier en même temps, conflit garanti. Anthropic le dit noir sur blanc dans la doc.
3. Tâche petite et focalisée. Si la tâche prend 3 minutes en main Claude, le coût d'invocation du subagent (description, attente, parsing du retour) dépasse le gain.

Anecdote concrète. Pour refactor 17 composants React de WhatSetter, j'ai split en 3 subagents : 5 composants chacun, fichiers totalement indépendants. Total : 11 minutes. Sans subagent, le main Claude aurait perdu son contexte à mi-parcours, j'aurais dû redémarrer une session, recharger le mental model du projet. Test fait : 1h05 sans subagent, 11 minutes avec. Le ratio s'effondre dès qu'il y a 10+ fichiers à toucher.

L'anatomie d'un subagent : YAML frontmatter + system prompt

Un subagent tient en 1 fichier .md dans .claude/agents/<nom>.md. Deux champs obligatoires : name et description. Quatre champs optionnels critiques : tools (whitelist d'outils), model (sonnet/opus/haiku), maxTurns (limite de tours), skills (skills pré-chargées). Le body du fichier devient le system prompt qui guide le comportement. Mon subagent bug-analyzer fait 28 lignes au total.

Décortiquons un subagent réel. Voici à quoi ressemble bug-analyzer, l'un des deux subagents que je tourne sur le repo VibesMoney depuis 6 semaines :

---
name: bug-analyzer
description: Expert debugger specialized in deep code execution
  flow analysis and root cause investigation. Use PROACTIVELY
  when you need to analyze code execution paths, build execution
  chain diagrams, trace variable state changes, or perform deep
  root cause analysis.
tools: read_file, write_file, run_bash_command, search_files, grep
model: haiku
---

# Bug Analyzer

Tu es un debugger expert. Ta mission : analyser le bug, isoler
la cause racine, proposer 1 ou 2 fixes ciblés.

## Méthode (toujours dans cet ordre)

1. Reproduire le bug en isolant les variables d'entrée
2. Tracer le flow d'exécution avec des prints ciblés
3. Identifier la ligne précise où l'état diverge
4. Proposer 2 fixes : un minimal, un structurel

## Output attendu

- 1 paragraphe : la cause racine en français simple
- 2 propositions de fix avec leur trade-off
- Aucun code généré tant que je n'ai pas validé l'analyse

Trois choses à noter sur ce frontmatter. Premièrement, la description contient "Use PROACTIVELY" : c'est la phrase-trigger officielle qui dit à Claude "déclenche-moi quand tu rencontres ce besoin". Sans elle, le subagent ne sera invoqué que si tu le demandes explicitement. Deuxièmement, j'ai whitelisté tools : le subagent n'a accès qu'aux outils dont il a besoin. Pas d'accès aux APIs externes, pas de risque qu'il commit ou déploie. Troisièmement, j'utilise le modèle haiku : pour du debug ciblé, Haiku suffit, et coûte 70% moins cher qu'Opus.

Le body du fichier (en dessous du frontmatter) devient le system prompt, c'est-à-dire les instructions cadres invisibles que le subagent suit toujours. Le mien fait 22 lignes. Il dit comment méthodiquement analyser un bug, et ce qu'il doit produire en sortie. Pas de jargon, pas de fioriture. Juste la procédure.

Anecdote chiffrée. Mon bug-analyzer a tourné 14 fois sur la dernière cohorte VibesMoney pour fixer des erreurs Codex. Coût total : 0,80 € sur 14 invocations en Haiku. Sans subagent, le même travail en Opus aurait coûté entre 3 € et 4 €. Et surtout, le main Claude aurait gardé toute la trace des 14 bugs, ce qui aurait fini par dégrader la qualité de ses réponses sur les tâches suivantes. Le subagent évacue le bruit. C'est exactement ce que orchestrer plutôt que coder veut dire en 2026 : tu fais bosser des outils spécialisés, tu gardes la vue d'ensemble.

Les 3 patterns testés sur WhatSetter et le programme VibesMoney

Trois patterns que j'utilise en production depuis 6 semaines. Pattern 1 : recherche/audit (subagent read-only qui scrute 20 fichiers et rend une synthèse). Pattern 2 : parallélisation indépendante (3 subagents sur 3 fichiers différents). Pattern 3 : fresh-eyes review (un subagent vierge sans biais de contexte). Sur 47 fichiers backend audités sur WhatSetter, le pattern 1 a rendu sa synthèse en 3 minutes.

Pattern 1 : le subagent audit read-only

Tu lances le subagent Explore ou un custom repo-explorer sur un dossier large. Il lit, ne touche à rien, te rend une synthèse de 10 à 20 lignes. Use case sur WhatSetter : audit de 47 fichiers backend pour identifier les couches qui parlent à Stripe. Synthèse rendue en 3 minutes. Sans subagent, mon main Claude saturait son contexte à 60% rien qu'avec les 47 fichiers ouverts. Avec le subagent, le contexte principal est à 5% à la fin.

Pattern 2 : la parallélisation indépendante

Tu lances 3 subagents en même temps, chacun sur un fichier ou un module différent. Règle absolue : aucun ne touche au même fichier qu'un autre, sinon conflit. Cas concret : un founder qu'on accompagne devait migrer 9 endpoints API d'Express vers Fastify. 3 subagents, 3 endpoints chacun. Total : 12 minutes. Sans parallélisation, le séquentiel aurait pris 40 minutes minimum, avec des oublis de contexte entre endpoints.

Pattern 3 : le fresh-eyes review

Tu lances un subagent code-reviewer vierge, sans le contexte de ta session. Il review ton diff comme s'il découvrait le code. Il attrape ce que ton main Claude rate par habitude. Cas concret : un founder qu'on accompagne, bloqué sur un bug Stripe depuis 40 minutes. J'ai lancé un fresh-eyes review. Le subagent a trouvé en 2 minutes que le webhook signait avec la mauvaise clé d'environnement. Le main Claude n'avait pas vu le pattern parce qu'il tournait dans le bug depuis trop longtemps.

Le point commun des 3 patterns : ils préservent le contexte de ton main Claude. Tu ne lui demandes jamais de tout porter. Tu lui demandes d'orchestrer, et de déléguer la grosse charge cognitive aux subagents. C'est cette discipline qu'on transfère en accélérant le calendrier de lancer un SaaS rentable en 12 semaines : dès la phase build du programme, on bosse en mode 1 main + 2 subagents par défaut.

Les 4 erreurs qui font qu'un subagent n'est jamais appelé

Quatre failure modes documentés par la communauté en 2026 : threads Hacker News août 2025, blog staff engineer Anthropic mars 2026 (Shrivu Shankar), retours r/ClaudeAI. La cause numéro un : description vague, qui plombe 60% des subagents non appelés. La numéro deux, peu connue : le context gatekeeping, où le subagent cache du contexte essentiel au main Claude et le rend moins précis.

Erreur 1 : description vague — 60% des cas

Tu écris "Analyze bugs" dans la description. Claude ne déclenche jamais ton subagent. Pourquoi ? "Bugs" est trop générique, aucune phrase-trigger reconnaissable. Fix : réécris avec des phrases précises. "Expert debugger specialized in deep code execution flow analysis. Use PROACTIVELY when you need to trace variable state changes or perform deep root cause analysis." Activation : 100% des cas pertinents. La leçon : la description n'est pas un résumé, c'est un signal d'invocation.

Erreur 2 : trop de subagents — au-delà de 5, dégradation auto-routing

Tu en crées 8 par enthousiasme la première semaine. Claude n'arrive plus à choisir lequel invoquer, et finit par faire le travail lui-même par défaut. Les threads HN documentent cette dégradation au-delà de 5 subagents perso. Fix : commence par 1, prouve qu'il est invoqué régulièrement, ajoute le suivant uniquement quand un nouveau pattern de répétition apparaît dans tes sessions. Sweet spot 2026 : 3 subagents perso max.

Erreur 3 : context gatekeeping — le piège invisible

Le plus traître des 4. Documenté par Shrivu Shankar (staff engineer, blog mars 2026). Tu crées un subagent python-tester qui sait tout sur tes tests Python. Conséquence : ton main Claude n'a plus accès à cette connaissance directement. Il est forcé d'invoquer le subagent juste pour valider son propre code. Tu as caché du contexte au main Claude. Fix : ne crée un subagent que si l'isolation du contexte est plus précieuse que sa disponibilité directe.

Erreur 4 : subagents pour tâche séquentielle dépendante

Tu lances un subagent pour l'étape 1 d'un workflow, un autre pour l'étape 2. L'étape 2 a besoin du contexte complet de l'étape 1. Mais le subagent étape 1 ne te rend qu'un résumé. Tu perds 30% de la nuance. Fix : pour les workflows séquentiels, garde tout dans le main Claude. Les subagents brillent uniquement quand les tâches sont indépendantes ou quand le résumé suffit.

Anecdote personnelle. Sur ma première version de bug-analyzer, la description disait juste "Analyze bugs". Claude ne l'invoquait jamais quand je tapais "trouve l'origine de ce bug Stripe". J'ai réécrit la description en 5 lignes précises avec "Use PROACTIVELY" et 3 phrases-trigger réelles. Activation : 100% des cas pertinents au prompt suivant. Le même pattern s'applique aux skills, on en parle dans le workflow LinkedIn + IA où chaque enrichissement de lead est un candidat naturel à automatiser.

Subagent, skill, ou simple prompt : trancher en 30 secondes

Arbre de décision en 3 questions. Tu déclenches toi-même la tâche ? Skill ou slash command. Tu veux que Claude délègue tout seul ? Subagent. Tâche sur moins de 5 fichiers et moins de 3 minutes ? Simple prompt, rien à packager. Sweet spot 2026 : 5 skills + 3 subagents max. Au-delà, l'overhead cognitif tue la productivité.

Voici l'arbre que j'applique avant de packager quoi que ce soit :

1. Question 1 : qui décide quand la tâche se déclenche ? Si c'est toi, c'est une skill ou une slash command. Si c'est Claude qui doit reconnaître le pattern et décider, c'est un subagent.
2. Question 2 : la tâche touche combien de fichiers ? Moins de 5 = simple prompt suffit. Entre 5 et 9 = skill, généralement. 10+ ou 3 tâches indépendantes = subagent.
3. Question 3 : la connaissance utilisée par cette tâche est utile ailleurs ? Oui = garde-la dans CLAUDE.md, pas dans un subagent. Non = subagent OK, le contexte sera bien isolé.

Sur les founders qu'on accompagne, ceux qui ont 4 à 6 outils packagés au total bossent 30% plus vite que ceux qui en ont 0 ou plus de 10. La courbe est nette. Trop peu = tu retapes les mêmes prompts à la main. Trop = tu passes plus de temps à choisir l'outil que ce que tu gagnes.

Mon setup actuel sur le repo VibesMoney, stable depuis 6 semaines :

• 4 skills : draft-article, illustrate-article, cover-article, commit.
• 2 subagents perso : bug-analyzer, code-reviewer. Plus les 3 built-in d'Anthropic.
• 0 slash command custom. Les built-in (/clear, /commit) suffisent.

Avant ce setup, j'avais 8 skills et 5 subagents. Trop. Je perdais 5 minutes par session à choisir lequel utiliser. J'ai désinstallé tout ce que je n'utilisais pas chaque semaine. La règle : si tu ne déclenches pas un outil pendant 14 jours, supprime-le. Tu pourras toujours le recréer en 30 minutes plus tard.

Au final, un subagent réussi remplit 4 critères. Il est invoqué automatiquement à 100% sur ses phrases-trigger. Il rend une synthèse exploitable en moins de 20 lignes. Il préserve le contexte du main Claude au lieu de le saturer. Il gagne au moins 10 minutes par invocation. Si un de tes subagents rate sur l'un de ces 4 critères, il est à réécrire, pas à abandonner. C'est exactement la même logique que un onboarding qui évite 70% du churn : tu mesures, tu ajustes, tu ne supprimes pas.