Subagents Claude Code
À l'issue de cette leçon, le stagiaire comprend ce qu'est un subagent dans Claude Code, sait en créer un avec permissions ciblées, et l'invoquer depuis une session principale via la syntaxe @nom.
L'agent unique devient une équipe
Jusqu'ici, Claude Code se présente comme un agent unique : vous discutez avec lui, il agit sur votre projet. Pour les tâches simples, c'est largement suffisant. Mais sur les sessions longues ou les projets complexes, cette uniformité devient un frein : un agent généraliste qui fait tout n'est optimal sur rien, et son contexte se sature de tâches annexes qui polluent la conversation principale.
La réponse : les subagents. Des instances spécialisées de Claude, chacune avec son propre contexte isolé, ses outils dédiés et ses permissions ciblées. L'agent unique devient une équipe d'agents spécialisés, chacun pour son rôle.
Cas d'usage typiques
Code reviewer
Subagent en lecture seule, spécialisé dans la revue de code. Vous lui passez le dernier commit, il identifie les problèmes potentiels sans rien modifier.
Test writer
Subagent avec accès aux fichiers de test uniquement. Il génère et exécute des tests pour les fonctions que vous lui désignez. Pas d'accès au code source de production.
Doc fetcher
Subagent spécialisé dans la recherche de documentation externe via web. Vous lui demandez de ramener la doc d'une API, il revient avec la synthèse. Le contexte principal reste propre.
Security auditor
Subagent dédié à l'audit sécurité : détection de secrets en clair, dépendances vulnérables, patterns risqués. Permissions de lecture seule sur tout le projet.
Isolation du contexte — pourquoi c'est précieux
La force principale des subagents est l'isolation du contexte. Les échanges avec un subagent ne polluent pas la conversation principale, et inversement. Trois bénéfices concrets :
Conversation principale propre
Vous travaillez sur une fonctionnalité importante. Vous avez besoin de consulter la doc d'une bibliothèque. Plutôt que de polluer le fil principal avec 50 messages de recherche, vous déléguez au subagent doc fetcher. Il revient avec la synthèse, votre fil principal reste lisible.
Permissions différenciées
Un code reviewer en lecture seule ne peut pas modifier le code par erreur, même si vous l'invoquez par mégarde au mauvais moment. Vous configurez les permissions une fois, vous oubliez. Le subagent est borné par construction.
Économie de tokens
Les subagents partent toujours d'un contexte vide. Vous ne consommez pas l'historique de la session principale dans les tâches annexes. Sur les sessions longues, le gain est substantiel.
Comme tout outil de spécialisation, les subagents sont à utiliser avec parcimonie. Si vous créez 15 subagents pour un projet de 1000 lignes, vous fragmentez votre travail au lieu de le simplifier. Commencez par 1 ou 2 subagents utilisés régulièrement avant d'envisager une « équipe ».
Créer un subagent — la commande /agents
Dans votre session Claude Code, taper la commande
/agents. L'interface de gestion des subagents s'ouvre : liste des subagents existants, option pour en créer un nouveau.Choisir Create new agent. Donner un nom court et explicite (par exemple
code-reviewer,test-writer). Le nom servira à l'invocation :@code-reviewer.Rédiger la description et les instructions du subagent. La description précise son rôle. Les instructions sont l'équivalent du CLAUDE.md pour ce subagent : son périmètre, son ton, ses limites.
Configurer les permissions : lecture seule ? écriture sur certains dossiers uniquement ? exécution de quelles commandes ? Appliquer le principe du privilège minimal — accordez le strict nécessaire.
Valider. Le subagent est créé. Vous pouvez l'invoquer immédiatement depuis la session principale avec
@nom, par exemple « @code-reviewer regarde le dernier commit et signale les points d'attention ».
Stockage et partage
Niveau utilisateur
~/.claude/agents/ — vos subagents personnels, réutilisables sur tous vos projets. Idéal pour les outils que vous emportez de projet en projet (votre code reviewer habituel).
Niveau projet
.claude/agents/ à la racine du projet — subagents partagés avec l'équipe via Git. Idéal pour les conventions spécifiques au projet (le test writer qui connaît la stack de l'équipe).
Format de définition
Fichier YAML simple, lisible et versionnable. Nom, description, instructions, permissions. Modifiable à la main si besoin (utile pour amender plusieurs subagents en lot).
Évolution dans le temps
Comme un CLAUDE.md, un subagent s'affine avec l'usage. Vos premiers seront imparfaits. Mettez-les à jour quand vous repérez les répétitions ou les manques.
Bonnes pratiques de conception
Un subagent bien conçu est un subagent qui se justifie par son usage répété et son périmètre clair. Quatre règles de conception pour éviter la dispersion :
Un rôle, une mission
Pas de subagent « assistant multi-tâches ». Un subagent doc fetcher, un autre code reviewer, un autre test writer — chacun avec une mission précise et exclusive.
Permissions minimales
Le défaut doit être lecture seule. N'accordez écriture ou exécution qu'aux subagents qui en ont vraiment besoin, et restreignez les dossiers concernés.
Pas de subagent pour les tâches uniques
Si vous créez un subagent que vous n'utiliserez qu'une fois, c'est une perte de temps. Réservez la création aux tâches répétitives.
Documenter dans CLAUDE.md
Mentionnez les subagents disponibles dans le CLAUDE.md du projet : « Subagents disponibles : @reviewer (revue de code), @tests (génération de tests). » Pratique pour les nouveaux arrivants.
Créer et utiliser un premier subagent
Identifiez UNE tâche annexe que vous faites régulièrement et qui pollue votre contexte principal : revue de code, recherche de doc, génération de tests, audit sécurité. Créez le subagent correspondant avec /agents. Accordez-lui les permissions minimales. Utilisez-le au moins trois fois cette semaine et notez l'effet sur la lisibilité de votre session principale.
Cet exercice est à conserver dans votre dossier de stagiaire. Il n'est pas évalué mais il est tracé.
- docs.claude.com — Sub-agents documentation officielle des subagents, configuration et permissions
Vous savez créer un subagent avec /agents, lui donner des permissions ciblées et l'invoquer depuis la session principale ?