Plus une session Claude Code dure, plus son contexte se remplit. Lancer toute la suite de tests, parser des logs, fouiller un gros dépôt : ces tâches crachent des centaines de lignes qui noient ce qui compte. Le sous-agent règle ça — il fait le travail bruyant à part et ne vous renvoie que le résumé.
Ce qu'est vraiment un sous-agent
Un sous-agent est une instance Claude isolée, avec son propre contexte vierge, son prompt système, ses outils autorisés et même son modèle. Vous le décrivez dans un fichier Markdown ; quand une tâche correspond à sa description, Claude lui délègue automatiquement. Le détail reste chez lui, seul le résultat remonte chez vous.
Le fichier, concrètement
Un sous-agent vit dans .claude/agents/ (au niveau projet, versionné) ou ~/.claude/agents/ (perso, tous projets confondus). C'est un Markdown : un frontmatter YAML qui le configure, puis le prompt système en dessous.
---
name: code-reviewer
description: Relit le code après chaque changement. Axé sécurité, perfs et tests.
tools: Read, Glob, Grep
model: sonnet
---
Tu es un relecteur de code senior. Analyse le diff et renvoie des retours
concrets et actionnables sur la qualité, la sécurité et la couverture de tests.Trois sous-agents que j'utilise tous les jours
- Un explorer en lecture seule : il fouille le dépôt et répond « où est X », sans jamais pouvoir écrire.
- Un test-runner : il lance la suite complète et ne remonte que les tests rouges, pas les milliers de lignes vertes.
- Un code-reviewer read-only : déclenché après mes changements, il relit le diff sans pouvoir le modifier.
Les pièges qui coûtent cher
- Description vague : Claude délègue à partir de la description. « Reviewer » ne dit pas quand l'utiliser ; « relit le code après chaque changement, axé sécurité et tests », oui.
- Croire qu'il voit votre historique : un sous-agent démarre vierge. Donnez-lui le contexte de la tâche dans votre demande, il ne lit pas la conversation.
- Oublier qu'il peut ignorer CLAUDE.md : certains sous-agents le sautent pour rester rapides. Si une règle doit l'atteindre, réécrivez-la dans son prompt.
Un sous-agent n'est pas un Claude au rabais. C'est un spécialiste à qui on confie le travail salissant pour garder sa propre tête claire.