Guide · IA & agents
Sous-agents Claude Code : limiter le contexte
Fichier de sous-agent, outils en lecture seule, et le redémarrage qui manque souvent. Doc relue le 18 octobre 2026, essai non fait.
Un sous-agent Claude Code n'est pas un second produit, ni une équipe de sessions. La page « Create custom subagents », relue le 18 octobre 2026, le décrit comme un assistant spécialisé dans la même session : sa propre fenêtre de contexte, son prompt, ses outils, ses permissions. Il renvoie un résumé. Les lectures intermédiaires restent chez lui. C'est utile quand une recherche noierait la conversation principale. Ce n'est pas utile pour faire semblant d'avoir plusieurs ingénieurs.
La même page sépare trois autres mécanismes, sans en donner les commandes dans le passage relu : des sessions indépendantes surveillées ensemble, des sessions qui s'envoient des messages, et une équipe de sessions que Claude lance et supervise. Ce guide ne recopie pas ces autres pages. Il reste sur les sous-agents, parce que c'est la page dont les commandes ont été lues. Le comparatif Claude Code et Cursor ne choisit pas non plus entre ces mécanismes.
Aucune commande ci-dessous n'a été rejouée. Aucune délégation n'a été observée.
Prérequis
Claude Code installé, et un dépôt d'essai. L'installation est dans Installer Claude Code. Un sous-agent envoie ses propres requêtes. La page dit qu'elles comptent dans les mêmes plafonds d'usage que la conversation principale. Ce guide ne cite aucun montant.
Claude choisit un sous-agent d'après sa description. Une description vague, et la délégation part au mauvais endroit, ou pas du tout. Les descriptions, hors agents intégrés, occupent du contexte. Au-delà de 15 000 jetons cumulés, la page dit que Claude Code affiche un avertissement au démarrage, avec le total. Le détail long va dans le prompt du sous-agent, qui ne se charge que lorsqu'il tourne.
Ce qui existe déjà
La page liste des sous-agents intégrés. Deux sont en lecture seule : Explore et Plan. Write et Edit leur sont refusés. Explore sert à chercher dans le code. Plan sert à rassembler du contexte en mode plan. Les deux sautent les fichiers CLAUDE.md et l'instantané git, pour rester moins chers. Les autres sous-agents, intégrés ou non, chargent les deux, sauf si le champ omitClaudeMd est posé.
Le modèle d'Explore suit des règles qui dépendent du fournisseur. La page les détaille. Ce guide ne les résume pas en une phrase fausse. Un sous-agent de projet ou d'utilisateur nommé Explore remplace l'intégré et garde son propre champ model.
general-purpose est le sous-agent des tâches qui explorent et modifient. Il a les outils disponibles aux sous-agents. Ce n'est pas le bon choix si vous voulez interdire l'écriture.
Pour retirer seulement Explore et Plan, la page donne la variable CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1, à partir de Claude Code v2.1.198. Claude lit alors les fichiers lui-même. Pour empêcher toute délégation, la page dit de refuser l'outil Agent via permissions.deny. Le JSON exact de ce refus est sur la page des permissions, pas recopié ici.
Écrire un fichier, puis le relire
Un sous-agent est un fichier Markdown avec un frontmatter YAML. La page propose de demander à Claude de l'écrire, ou de l'écrire soi-même. Si vous demandez à Claude, la page dit d'ouvrir le fichier ensuite. L'exemple qu'elle montre pour un fichier relu à la main est celui-ci. Il est cité tel quel, pas exécuté :
---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---
You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.
tools est une liste blanche. Read, Glob et Grep ne comprennent pas Write ni Edit. C'est le point du fichier, pas un oubli. Le corps devient le prompt système du sous-agent. Il ne reçoit pas le prompt système de Claude Code, seulement ce texte et des détails d'environnement comme le répertoire de travail.
L'emplacement décide qui le voit. .claude/agents/ vaut pour le projet en cours. ~/.claude/agents/ vaut pour tous les projets de la machine. En cas de même nom, la page donne un ordre : réglages gérés par l'organisation, puis le drapeau --agents, puis le projet, puis l'utilisateur. Le tableau complet est sur la page. Un fichier d'essai dans le projet évite de polluer tous les dépôts.
Claude Code surveille ces deux dossiers s'ils existaient au démarrage de la session. Un ajout ou une modification est pris en compte en quelques secondes, sans redémarrage, sauf trois cas que la page nomme. Le premier est celui qui piège : le surveillant ne voit pas un dossier agents créé après le début de la session. Il faut redémarrer. Les deux autres : un sous-agent dans un répertoire ajouté avec --add-dir ou /add-dir, et une session lancée avec --disable-slash-commands.
La demande documentée pour provoquer la délégation, dans le quickstart de la page, est du type « Use the code-improver agent to suggest improvements in this project ». Dans la transcription, la page dit que la délégation apparaît comme une ligne d'appel d'outil, le nom du sous-agent suivi d'une courte tâche, par exemple code-improver(Suggest code improvements). Ce texte n'a pas été vu ici.
/agents imprime, sur la version décrite par la page, un rappel : demander à Claude, ou éditer .claude/agents/ et ~/.claude/agents/. Sur v2.1.197 et avant, la même commande ouvrait un assistant avec des onglets Running et Library. Si votre /agents ne ressemble pas à ce que vous aviez lu ailleurs, la version explique souvent l'écart. Ce guide ne l'a pas lancé.
Une définition pour une seule session
Le drapeau --agents passe du JSON pour la session en cours. La page montre un objet avec deux clés, code-reviewer et debugger. Le champ prompt du JSON correspond au corps Markdown. Un chemin de fichier, par exemple claude -p --agents ./agents.json "Review my changes", n'est accepté qu'en mode non interactif, et à partir de v2.1.281. En session interactive, la page dit que Claude Code refuse un chemin. Ne commencez pas un nom par un tiret.
permissionMode se règle dans le frontmatter. Les valeurs documentées comprennent default (demande d'autorisation), plan (exploration en lecture seule), dontAsk, acceptEdits, auto et bypassPermissions. La page est explicite sur le dernier : un sous-agent ne tourne dans ce mode que si la conversation principale y est déjà. Si la conversation principale est en bypassPermissions, acceptEdits ou auto, le sous-agent suit ce mode et le permissionMode du fichier est ignoré. Poser plan sur un fichier ne protège donc pas une session déjà ouverte en approbation large.
Les outils qui dépendent de l'interface ne sont pas disponibles aux sous-agents, même s'ils sont listés : la page cite AskUserQuestion, EnterPlanMode, ScheduleWakeup, WaitForMcpServers, et ExitPlanMode sauf si le sous-agent est en mode plan. Un workflow qui compte sur une question à l'utilisateur dans le sous-agent est hors de ce que la page permet.
Erreur fréquente
Claude ne trouve pas le sous-agent juste après sa création. La page le dit pour le cas où ~/.claude/agents/ n'existait pas au démarrage. Le correctif documenté est de redémarrer Claude Code, pas d'ajouter un second fichier sous un autre nom en espérant que l'un des deux sera vu. Vérifiez aussi le champ name et le nom du fichier. La page ne dit pas qu'ils doivent être identiques dans tous les cas, mais l'exemple code-reviewer aligne le champ name et le nom de fichier. Un écart non relu est une mauvaise piste.
L'autre silence : un tools qui contient une faute. La liste est une liste blanche. Un outil mal nommé n'élargit pas les droits, il manque. La page ne promet pas un message clair pour chaque faute de ce champ. Relisez le frontmatter avant de conclure que le modèle « refuse » la tâche.
Vérification
Après redémarrage si le dossier est neuf, demandez une délégation en nommant le sous-agent, comme dans l'exemple de la page. Le contrôle documenté est la ligne d'appel d'outil dans la transcription, pas une impression que « ça a l'air d'avoir cherché ». Si la ligne n'apparaît pas, la recherche a peut-être été faite par la conversation principale. Ce n'est pas la même chose : les extraits de fichiers restent alors dans le contexte principal, ce que le sous-agent était censé éviter.
Pour un contrôle plus étroit, lancez une session avec le drapeau --agents et un JSON dont tools ne contient que Read, Grep et Glob, sur le modèle de l'exemple code-reviewer. La forme fichier de ce drapeau exige -p et v2.1.281 ou plus. Ce guide ne l'a pas fait. Si la version est plus ancienne, le chemin de fichier sera refusé ou ignoré selon ce que la page des erreurs décrit. Cette page d'erreurs n'a été lue que pour d'autres messages, pas pour coller ici un texte non revu.
Sources
Page relue le 18 octobre 2026 pour les commandes et le format de fichier : Create custom subagents.
Source recontrôlée le 19 octobre 2026. La page headless est citée par celle-ci pour le mode non interactif. Le passage sur --agents et le fichier JSON a été lu sur la page des sous-agents, pas reconstruit. Les équipes d'agents, les sessions en arrière-plan et les messages entre sessions ne sont pas documentés dans ce guide. Pas de capture de transcription, pas de tarif.