Sous-agents

Claude Code peut déléguer des tâches à des sous-agents autonomes. Chaque sous-agent tourne dans son propre contexte isolé, ce qui protège ton thread principal et permet de lancer plusieurs tâches en parallèle.

Qu'est-ce qu'un sous-agent ?

Un sous-agent est une instance Claude Code secondaire, invoquée par le thread principal pour traiter une tâche précise. Il dispose de son propre contexte : il ne voit pas l'historique de la conversation parente, et ses actions (lecture de fichiers, exécution de commandes) ne polluent pas le contexte principal.

Deux avantages concrets :

• Isolation : une tâche exploratoire (lire 50 fichiers pour comprendre une archi) consomme de la fenêtre de contexte. La confier à un sous-agent protège le contexte du thread principal pour la suite.
• Spécialisation : chaque sous-agent peut avoir un rôle défini (explorer, refactorer, écrire des tests, rédiger de la doc). Le thread principal orchestre, les sous-agents exécutent.

Pourquoi déléguer à un sous-agent ?

Déléguer à un sous-agent n'est pas toujours la bonne décision. Voici les trois cas où ça vaut vraiment le coup :

Recherche large dans un gros codebase. Si Claude doit lire 30 à 50 fichiers pour comprendre une architecture, cette exploration peut consommer plusieurs dizaines de milliers de tokens. Déléguer à un sous-agent garde ces tokens hors de ta fenêtre principale - le sous-agent consomme SA propre fenêtre, pas la tienne.

Tâche répétitive sur N items. Corriger le style de 20 fichiers, écrire un test par fonction, traduire une liste de chaînes : ces tâches sont parfaites pour la parallélisation. Tu peux lancer plusieurs sous-agents en même temps sur des lots différents.

Tâche spécialisée avec un comportement différent. Une review de sécurité, une rédaction MDX avec des contraintes de format précises, une validation SQL : un sous-agent avec son propre system prompt fait mieux que le thread principal chargé du contexte de toute la session.

Trois anti-cas à connaître :

• Pour une seule lecture de fichier connue : lancer un sous-agent est excessif, fais-le directement.
• Quand le résultat doit alimenter une décision immédiate dans le thread principal : le temps de latence d'un sous-agent n'est pas justifié.
• Quand la tâche modifie beaucoup le filesystem avec des dépendances croisées : mieux vaut garder la cohérence dans le thread principal.

La fenêtre de contexte et les sous-agents

C'est le point le plus concret à comprendre. Claude Sonnet 4.6 et Claude Opus 4.7 ont tous les deux une fenêtre de contexte de 1M tokens (input + output). Claude Haiku 4.5 dispose de 200K tokens. (Chiffres valables au moment de la rédaction, mai 2026 - vérifie la page Models overview pour les valeurs à jour.)

Pour donner un ordre de grandeur :

• Un fichier de 1000 lignes représente environ 5K à 8K tokens.
• Une recherche complète sur 50 fichiers peut dépasser 100K tokens facilement.
• Un historique de conversation de 2h commence à saturer une fenêtre de 200K tokens.

Quand tu délègues à un sous-agent, il consomme sa propre fenêtre, indépendante de la tienne. C'est la valeur principale du mécanisme : tu préserves ton contexte principal pour les décisions et les étapes qui suivent.

Choisir le bon modèle pour un sous-agent

Les alias disponibles dans le frontmatter d'un sous-agent sont : sonnet, opus, haiku. Tu peux aussi passer un ID complet (claude-sonnet-4-6). Si tu omets le champ model, le sous-agent hérite du modèle de la conversation principale.

Lancer un sous-agent ad hoc

Tu n'as pas besoin de configuration préalable pour utiliser un sous-agent. Demande-le simplement dans ton prompt :

Lance un sous-agent pour explorer le dossier src/ et me faire un résumé de l'architecture. Ne modifie rien.

Claude Code va créer un sous-agent, lui passer la tâche, et te restituer le résultat dans ton thread. Le sous-agent disparaît une fois la tâche terminée.

Tu peux aussi paralléliser plusieurs tâches en une seule demande :

Lance deux sous-agents en parallèle : le premier liste toutes les dépendances directes de package.json avec leur version, le second cherche les fichiers TODO dans le projet.

Le menu /agents

La slash command /agents liste tous les sous-agents disponibles dans ta session : les sous-agents intégrés (Explore, Plan, general-purpose) et ceux que tu as configurés.

$/agents

Ce menu te permet de voir les agents disponibles, leurs descriptions, les outils auxquels ils ont accès, et de créer de nouveaux agents de façon guidée. Tu peux t'en servir pour vérifier qu'un agent custom a bien été chargé.

Configurer un sous-agent custom

Pour des tâches récurrentes (rédiger des tests, valider du SQL, relire de la doc), tu peux définir un sous-agent persistant. La configuration se fait via un fichier Markdown dans .claude/agents/.

Anatomie d'un fichier d'agent

Voici un exemple réaliste - un agent qui écrit des tests unitaires TypeScript :

---
name: test-writer
description: >
  Écrit des tests unitaires Vitest pour les fonctions TypeScript passées
  en entrée. Utiliser quand tu demandes de tester une fonction ou un module.
model: sonnet
tools:
  - Read
  - Write
  - Bash
color: green
---

Tu es un expert en tests unitaires TypeScript avec Vitest.

Pour chaque fonction reçue :
1. Identifie les cas nominaux et les cas limites.
2. Écris les tests dans un fichier `*.test.ts` adjacent au source.
3. Lance `pnpm test --run` pour vérifier que les tests passent.
4. Retourne un résumé : nombre de tests écrits, cas couverts, résultat du run.

Ne modifie jamais le fichier source. Tes seules écritures concernent les fichiers `*.test.ts`.

Les champs du frontmatter :

• name : identifiant kebab-case. C'est ce que tu utilises pour invoquer l'agent (utilise test-writer pour cette fonction).
• description : décrit quand utiliser cet agent. Claude lit cette description pour décider d'invoquer l'agent automatiquement. Une description vague empêche la sélection automatique.
• model : modèle à utiliser. sonnet est le bon choix pour la plupart des agents secondaires.
• tools : liste explicite des outils autorisés. Restreindre les outils réduit la surface de risque - un agent de lecture n'a pas besoin de Write ou Bash.
• color (optionnel) : couleur d'identification dans l'UI (red, blue, green, yellow, purple, orange, pink, cyan).

Corps du fichier

Tout ce qui suit le frontmatter est le system prompt de l'agent. C'est là que tu définis son comportement, ses contraintes, son workflow, et son format de sortie.

Portée du fichier

• .claude/agents/ : sous-agent disponible uniquement dans ce projet. Commite-le dans le dépôt pour le partager avec ton équipe.
• ~/.claude/agents/ : sous-agent personnel disponible dans tous tes projets.