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

Le problème du contexte infini

Imagine que tu demandes à Claude de rechercher comment fonctionne l’authentification de ton projet. Il commence à lire des fichiers. Beaucoup de fichiers. Soudain, tu te retrouves avec 50'000 tokens de contexte remplis de code que tu avais juste besoin de consulter, pas de retenir.

Maintenant, chaque réponse est plus lente. Et plus chère. Et quand tu voudras faire autre chose, tout ce contexte reste là, occupant de l’espace mental.

La solution : les sous-agents. Tu lances un agent spécialisé qui fait le travail dans son propre contexte isolé, te renvoie un résumé, et disparaît. Ta 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 ta 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)

Pense à eux comme à des stagiaires spécialisés. Tu leur assignes une tâche, ils travaillent de façon indépendante, et te font un rapport quand ils ont terminé.

Les sous-agents que tu as déjà

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

Le plus utile est Explore. Quand Claude a besoin de chercher quelque chose dans ta codebase, il lance un Explore qui lit des fichiers comme un fou, traite tout, et ne renvoie que le pertinent.

Comment lancer des sous-agents

Depuis le REPL (conversation normale)

Demande-le simplement en langage naturel :

Utilise un sous-agent pour rechercher comment fonctionne le système de cache

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

Recherche 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, tu peux forcer qu’il s’exécute dans un sous-agent isolé avec context: fork :

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

---
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
- Patterns de design détectés

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

Lancement explicite par type

Si tu veux ê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. Ta session attend qu’ils terminent.

Recherche comment fonctionne le rate limiting
[Claude lance le sous-agent, tu attends, tu reçois le résultat]

Utile quand tu as besoin du résultat immédiatement.

Background (parallèle)

Tu peux envoyer un sous-agent en background de deux façons :

1. En le demandant explicitement :

Recherche le système de cache en background pendant que je révise autre chose

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

Si un sous-agent tourne déjà et que tu veux continuer à travailler, appuie sur Ctrl+B. L’agent passe en background et tu peux continuer.

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

Voir les tâches en background

Utilise la commande /tasks pour voir ce qui tourne :

/tasks

Cela affiche toutes les tâches en background avec leurs IDs, statut et progression.

Communication avec les sous-agents

Savoir ce qu’il fait

Pendant qu’un sous-agent est en foreground, tu vois sa progression en temps réel (quels fichiers il lit, quelles commandes il exécute).

S’il est en background, utilise /tasks pour voir le statut. Quand il termine, Claude te notifie automatiquement avec le résultat.

Donner des instructions supplémentaires

Si un sous-agent tourne et que tu veux 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 c’est possible.

Arrêter un sous-agent

Pour arrêter une tâche en background :

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

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

Reprendre un sous-agent

Les sous-agents maintiennent leur historique dans la session. Tu peux reprendre où ils s’étaient arrêtés :

Continue l'analyse d'authentification que tu avais faite avant
et maintenant vérifie aussi l'autorisation

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

Créer tes propres sous-agents

Avec la commande /agents (recommandé)

/agents

Sélectionne Create new agent, choisis le scope (utilisateur ou projet), décris ce que tu veux, et Claude génère le fichier pour toi.

Manuellement

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

---
name: security-scanner
description: Scanne le code à la recherche de vulnérabilités. À utiliser de façon 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'input insuffisante
- Dépendances vulnérables

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

Configuration du frontmatter

Modes de permissions

Exemple : Agent en lecture seule

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

---
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, ne fais que décrire ce que tu trouves.

Exemple : Agent de tests

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

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

1. Exécute : `uv run pytest -x --tb=short`
2. S'il y a des échecs, lit les fichiers pertinents
3. Reporte :
   - 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 reporter.

Cas d’usage habituels

1. Recherche de codebase

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

L’Explore lit tout ce qui est nécessaire, tu reçois un résumé sans contaminer ton contexte.

2. Analyse parallèle

Recherche 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 recherche son domaine.

3. Tests en background

Exécute les tests en background pendant que j'implémente cette feature

Tu n’as pas besoin d’attendre. Quand ils échouent (ou passent), il te 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 en contexte séparé. Tu reçois du feedback sans bruit.

5. Refactoring sûr

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

---
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 automatiquement les tests.

Sous-agents vs Skills : Quand utiliser chacun

Tu peux aussi les combiner : un skill avec context: fork lance un sous-agent.

Limitations

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

Tips avancés

Désactiver des sous-agents spécifiques

Dans settings.json :

1
2
3
4
5

{
  "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 :

1

export CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=50

Voir les transcriptions

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

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

Utile pour le debugging ou l’audit.

Désactiver les tâches background

Si tu préfères que tout soit bloquant :

1

export CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1

Conclusion

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

Utilise-les pour la recherche, l’analyse, les tests, et toute tâche qui génère beaucoup d’output que tu n’as pas besoin de retenir. Crée les tiens 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) te donne un contrôle assez fin sur comment travaille Claude.

TL;DR : Les sous-agents sont des instances isolées de Claude pour des tâches spécifiques. Ils maintiennent ton contexte propre, peuvent tourner en parallèle (Ctrl+B), et tu peux créer les tiens dans .claude/agents/. Utilise /tasks pour les monitorer et /agents pour les gérer.

Documentation officielle : Subagents - Claude Code Docs