Sous-agents dans Claude Code : Déléguer sans perdre le contrôle

Le problème du contexte infini

Imaginez que vous demandez à Claude d’enquêter sur le fonctionnement de l’authentification de votre projet. Il commence à lire des fichiers. Beaucoup de fichiers. Soudain, vous vous retrouvez avec 50 000 tokens de contexte remplis de code que vous aviez juste besoin de consulter, pas de retenir.

Maintenant, chaque réponse est plus lente. Et plus chère. Et quand vous voulez faire autre chose, tout ce contexte est toujours là, occupant l’espace mental.

La solution : les sous-agents. Vous lancez un agent spécialisé qui fait le travail dans son propre contexte isolé, vous renvoie un résumé, et disparaît. Votre conversation principale reste propre.

Qu’est-ce qu’un sous-agent

Un sous-agent est une instance séparée de Claude qui :

• A son propre contexte (ne contamine pas votre conversation)
• Peut avoir des outils restreints (lecture seule, bash seulement, etc.)
• Peut utiliser un modèle différent (haiku pour les tâches simples, opus pour les complexes)
• Peut s’exécuter en foreground (bloquant) ou background (parallèle)

Pensez à eux comme à des stagiaires spécialisés. Vous leur assignez une tâche, ils travaillent de manière indépendante, et vous rapportent quand ils ont terminé.

Les sous-agents que vous avez déjà

Claude Code est livré avec plusieurs sous-agents intégrés :

Le plus utile est Explore. Quand Claude a besoin de chercher quelque chose dans votre base de code, il lance un Explore qui lit les fichiers intensivement, traite tout, et ne renvoie que ce qui est pertinent.

Comment lancer des sous-agents

Depuis le REPL (conversation normale)

Demandez-le simplement en langage naturel :

Utilise un sous-agent pour enquêter sur le fonctionnement du système de cache

Lance l'agent Explore pour trouver tous les endpoints de l'API

Enquête sur l'authentification en parallèle pendant que je continue à travailler

Claude comprend ces demandes et utilise l’outil Task en interne pour lancer le sous-agent approprié.

Depuis un Skill

Dans un skill, vous pouvez forcer l’exécution dans un sous-agent isolé avec context: fork :

---
name: deep-analysis
description: Analyse approfondie de l'architecture
context: fork
agent: Explore
---

Analyse l'architecture complète du projet.
Génère un rapport avec :
- Structure des répertoires
- Dépendances principales
- Motifs de conception détectés

Avec context: fork, le skill s’exécute dans un sous-agent. Avec agent: Explore, vous spécifiez quel type d’agent utiliser.

Lancement explicite par type

Si vous voulez être spécifique :

Utilise l'agent Explore pour mapper la structure du projet
Utilise un agent general-purpose pour refactoriser le module de paiements
Utilise l'agent Bash pour exécuter la suite de tests complète

Foreground vs Background

Foreground (bloquant)

Par défaut, les sous-agents s’exécutent en foreground. Votre session attend qu’ils terminent.

Enquête sur le fonctionnement du rate limiting
[Claude lance le sous-agent, vous attendez, vous recevez le résultat]

Utile quand vous avez besoin du résultat immédiatement.

Background (parallèle)

Vous pouvez envoyer un sous-agent en arrière-plan de deux façons :

1. En le demandant explicitement :

Enquête sur le système de cache en arrière-plan pendant que je révise autre chose

2. Avec Ctrl+B pendant qu’il s’exécute :

Si un sous-agent est déjà en cours et que vous voulez continuer à travailler, appuyez sur Ctrl+B. L’agent passe en arrière-plan et vous pouvez continuer.

> Analyse tous les tests du projet
[Commence à s'exécuter...]
[Vous appuyez sur Ctrl+B]
> Bon, en attendant, explique-moi ce que fait ce fichier
[Vous continuez à travailler, l'analyse continue en parallèle]

Voir les tâches en arrière-plan

Utilisez la commande /tasks pour voir ce qui est en cours :

/tasks

Cela affiche toutes les tâches en arrière-plan avec leurs IDs, état et progrès.

Communication avec les sous-agents

Savoir ce qu’il fait

Pendant qu’un sous-agent est en foreground, vous voyez son progrès en temps réel (quels fichiers il lit, quelles commandes il exécute).

S’il est en arrière-plan, utilisez /tasks pour voir l’état. Quand il termine, Claude vous notifie automatiquement avec le résultat.

Donner des instructions supplémentaires

Si un sous-agent est en cours et que vous voulez ajouter du contexte :

Au fait, ignore les fichiers de test, seul le code de production m'intéresse

Claude essaie de passer cette information au sous-agent si possible.

Arrêter un sous-agent

Pour arrêter une tâche en arrière-plan :

Arrête la tâche d'analyse
Annule le sous-agent qui est en cours

Ou depuis /tasks, vous pouvez annuler des tâches spécifiques par ID.

Reprendre un sous-agent

Les sous-agents maintiennent leur historique dans la session. Vous pouvez reprendre où ils se sont arrêtés :

Continue l'analyse d'authentification que tu as faite avant
et maintenant révise aussi l'autorisation

Claude reprend le sous-agent avec tout son contexte précédent.

Créer vos propres sous-agents

Avec la commande /agents (recommandé)

/agents

Sélectionnez Create new agent, choisissez le scope (utilisateur ou projet), décrivez ce que vous voulez, et Claude génère le fichier pour vous.

Manuellement

Créez un fichier Markdown dans .claude/agents/ (projet) ou ~/.claude/agents/ (global) :

---
name: security-scanner
description: Scanne le code à la recherche de vulnérabilités. Utiliser de manière proactive après des changements dans l'authentification ou la gestion des données.
tools: Read, Grep, Glob
model: opus
---

Tu es un expert en sécurité. Analyse le code en cherchant :

- Injection SQL
- XSS
- Secrets codés en dur
- Validation d'entrée insuffisante
- Dépendances vulnérables

Rapporte par sévérité : Critique > Élevé > Moyen > Bas.
NE modifie PAS le code, ne fais que rapporter.

Configuration du frontmatter

Modes de permissions

Exemple : Agent de lecture seule

---
name: code-reader
description: Lit et analyse le code sans rien modifier
tools: Read, Grep, Glob
disallowedTools: Write, Edit, Bash
permissionMode: plan
---

Analyse le code demandé.
Ne suggère JAMAIS de modifications, décris seulement ce que tu trouves.

Exemple : Agent de tests

---
name: test-runner
description: Exécute les tests et rapporte les échecs. Utiliser après des changements de code.
tools: Bash, Read
model: haiku
---

1. Exécute : `uv run pytest -x --tb=short`
2. S'il y a des échecs, lis les fichiers pertinents
3. Rapporte :
   - Tests réussis : X
   - Tests échoués : Y
   - Résumé de chaque échec (fichier, ligne, erreur)

N'essaie PAS de corriger les tests, ne fais que rapporter.

Cas d’usage courants

1. Recherche dans la base de code

Utilise Explore pour comprendre comment fonctionne le système de notifications

L’Explore lit tout ce qui est nécessaire, vous recevez un résumé sans contaminer votre contexte.

2. Analyse parallèle

Enquête en parallèle :
- Comment fonctionne l'authentification
- Comment fonctionne le système de paiements
- Comment fonctionne l'envoi d'emails

Claude lance trois sous-agents simultanés. Chacun enquête sur son domaine.

3. Tests en arrière-plan

Exécute les tests en arrière-plan pendant que j'implémente cette fonctionnalité

Vous n’avez pas besoin d’attendre. Quand ils échouent (ou réussissent), il vous prévient.

4. Code review isolé

Utilise un sous-agent pour réviser la sécurité des changements que je viens de faire

La révision se fait dans un contexte séparé. Vous recevez des commentaires sans bruit.

5. Refactoring sécurisé

---
name: safe-refactor
description: Refactorise le code avec des vérifications
tools: Read, Edit, Bash
hooks:
  PostToolUse:
    - matcher: "Edit"
      hooks:
        - type: command
          command: "uv run pytest -x"
---

Chaque édition déclenche les tests automatiquement.

Sous-agents vs Skills : Quand utiliser chacun

Vous pouvez aussi les combiner : un skill avec context: fork lance un sous-agent.

Limitations

• Ils ne peuvent pas s’imbriquer : Un sous-agent ne peut pas lancer un autre sous-agent
• Permissions en arrière-plan : Les sous-agents en arrière-plan auto-refusent les permissions non pré-approuvées
• Session unique : Le contexte du sous-agent ne vit que pendant la session

Astuces avancées

Désactiver des sous-agents spécifiques

Dans settings.json :

{
  "permissions": {
    "deny": ["Task(Explore)", "Task(mon-agent-custom)"]
  }
}

Auto-compactage

Les sous-agents ont un auto-compactage à 95% du contexte. Pour le déclencher plus tôt :

export CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=50

Voir les transcriptions

Les logs des sous-agents sont sauvés dans :

~/.claude/projects/{projet}/{session}/subagents/agent-{id}.jsonl

Utile pour le débogage ou l’audit.

Désactiver les tâches en arrière-plan

Si vous préférez que tout soit bloquant :

export CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1

Conclusion

Les sous-agents sont la façon de faire évoluer votre utilisation de Claude Code sans que le contexte explose. Ils délèguent le travail ingrat, gardent votre conversation propre, et peuvent travailler en parallèle.

Utilisez-les pour la recherche, l’analyse, les tests, et toute tâche qui génère beaucoup de sortie que vous n’avez pas besoin de retenir. Créez les vôtres pour les tâches répétitives avec des restrictions spécifiques.

La combinaison de skills (quoi faire) + sous-agents (où le faire) + hooks (quand valider) vous donne un contrôle assez fin sur la façon dont Claude travaille.

En résumé : Les sous-agents sont des instances isolées de Claude pour des tâches spécifiques. Ils gardent votre contexte propre, peuvent tourner en parallèle (Ctrl+B), et vous pouvez créer les vôtres dans .claude/agents/. Utilisez /tasks pour les monitorer et /agents pour les gérer.

Documentation officielle : Subagents - Claude Code Docs

Cet article a été rédigé en espagnol et traduit avec l’aide de l’IA.