Agents et sous-agents Claude Code, expliqués simplement

J’ai passé une partie du mois dernier à supprimer des fichiers d’agents. Les agents Claude Code et les sous-agents Claude Code sont ce que j’ai ajouté de plus utile à mon workflow depuis un an, et aussi ce qu’il est le plus facile de copier sans comprendre : tu clones le repo de quelqu’un avec soixante personas spécialisés, tu les déposes dans un dossier, puis tu passes quinze jours à te demander pourquoi rien n’est allé plus vite. Le mécanisme est vraiment simple une fois qu’on l’a vu. Savoir quand déléguer, c’est ça la partie difficile. Et la question à laquelle presque personne ne répond, c’est où tous ces agents devraient réellement tourner une fois que tu arrêtes de les surveiller.

Voici la version que j’aurais aimé lire en premier.

Ce qu’est vraiment un agent Claude Code

Un agent, c’est un fichier Markdown. C’est tout. Un frontmatter YAML en haut déclare qui il est et ce qu’il a le droit de toucher ; tout ce qui se trouve sous le frontmatter devient son prompt système.

Dépose le fichier dans .claude/agents/ et il appartient au projet : il est commité et tous ceux qui travaillent dans le repo ont le même spécialiste. Dépose-le dans ~/.claude/agents/ et il te suit dans tous les projets de ta machine. Les deux chemins et la liste complète des champs du frontmatter se trouvent dans la documentation d’Anthropic sur les sous-agents.

Les champs à connaître dès le premier jour :

Il y en a d’autres, dont skills, effort, memory et isolation: worktree pour les agents qui doivent travailler dans leur propre worktree git, mais les sept ci-dessus couvrent l’essentiel de ce que tu écriras.

Agents et sous-agents Claude Code : le même fichier, utilisé de deux façons

C’est la distinction qui fait trébucher les gens, et elle n’a rien à voir avec le format du fichier.

Lance claude --agent code-reviewer et cette définition devient ta session principale. Tu lui parles directement. C’est un agent.

Laisse plutôt ta session principale lui confier le travail, et la même définition tourne comme sous-agent : une fenêtre de contexte séparée, sans historique de conversation, sans souvenir des fichiers que tu as déjà lus et sans visibilité sur ce que tu étais en train de faire. Il fait le travail et renvoie un résumé. Tu peux le forcer avec une mention explicite @agent-code-reviewer, ou laisser Claude le choisir automatiquement à partir du champ description.

Claude Code fournit aussi trois agents intégrés que tu utilises déjà sans écrire le moindre fichier : Explore pour la recherche en lecture seule dans le code, Plan pour la recherche en mode plan, et General-purpose pour le travail en plusieurs étapes. D’après la documentation, par défaut, jusqu’à vingt sous-agents peuvent tourner en même temps avec trois niveaux d’imbrication, les deux étant réglables par variables d’environnement.

La fenêtre de contexte séparée, c’est tout l’intérêt

Un sous-agent n’est pas une astuce de persona. C’est un conteneur.

Quand Claude parcourt un log de 4 000 lignes dans ta session principale, ces 4 000 lignes restent dans ton contexte pour tout le reste de la conversation. Quand c’est un sous-agent qui le fait, le log reste dans sa fenêtre à lui et ta session reçoit un paragraphe. C’est tout l’échange : tu renonces au contexte partagé et tu gagnes de la place pour continuer à travailler.

Le deuxième effet, c’est le coût, et c’est là que le champ model par agent prend tout son sens. D’après les tarifs API publiés par Anthropic, Claude Opus 5 coûte 5 $ par million de tokens en entrée et 25 $ par million en sortie, Claude Sonnet 5 coûte 2 $ et 10 $, et Claude Haiku 4.5 coûte 1 $ et 5 $. Même page : un hit dans le cache de prompt coûte 0,1x le tarif d’entrée de base. Un agent de type grep-et-résumé épinglé sur haiku tourne donc à un cinquième du tarif d’entrée de la session Opus qui l’a appelé, et l’appelant ne paie jamais pour la transcription qu’il a dû traverser. Épingle le reviewer qui doit vraiment réfléchir sur opus, et celui qui cherche des fichiers sur haiku.

Le troisième effet, c’est le rayon d’impact. Un reviewer déclaré avec tools: Read, Grep, Glob ne peut physiquement pas modifier ton code, peu importe à quel point il est convaincu qu’il devrait.

Les trois règles que je suis maintenant

Un agent par résultat vérifiable, pas par intitulé de poste. « Architecte senior » produit des impressions. « Lance la suite de tests et signale la première assertion en échec avec le fichier et la ligne » produit un résultat que je peux vérifier.

Écris la description pour le routeur, pas pour les humains. Claude lit ce champ pour décider s’il délègue. Les descriptions vagues sont la raison pour laquelle les gens concluent que la délégation automatique ne marche pas.

Restreins les outils avant de restreindre les modèles. Un agent bon marché capable d’écrire des fichiers est une plus mauvaise idée qu’un agent coûteux qui ne peut que lire.

Où ces agents doivent-ils tourner ?

Une fois les définitions bien écrites, la question intéressante se déplace. Il ne s’agit plus de savoir ce qu’est l’agent, mais quelle machine le réveille.

La critique « ça ne fait rien pendant que tu dors » adressée à Claude Code est dépassée, et voici l’état des lieux exact :

Les Routines sont celles qu’il faut vraiment comprendre. D’après la documentation, elles tournent sur une infrastructure cloud gérée par Anthropic, acceptent des déclencheurs par planification, API et événements GitHub, imposent un intervalle minimum d’une heure, clonent à chaque exécution les repos GitHub que tu as sélectionnés, poussent le travail sur des branches préfixées claude/, et sont disponibles sur les forfaits Pro, Max, Team et Enterprise avec Claude Code on the web activé, dans la limite d’un plafond quotidien d’exécutions. Les Channels sont une preview de recherche qui pousse des messages Telegram, Discord ou iMessage dans une session déjà ouverte, ce qui veut dire que la session doit être ouverte.

Remarque ce que toutes les lignes ont en commun : l’unité de travail, c’est un repository.

La moitié de mon backlog qui n’a pas de repo

J’écris du logiciel, et pourtant je passe plus de temps dans ma semaine en dehors d’un repo git que dedans. Le devis à envoyer. La base de données Notion qui a trois jours de retard. Le fil d’emails à résumer avant un appel. Rien de cette liste ne se clone depuis GitHub, et rien ne produit de pull request. Les Routines ne sont pas faites pour ça, et c’est normal, parce qu’elles n’ont jamais été pensées pour.

C’est ce manque qui explique pourquoi j’ai construit Notis comme je l’ai fait. Même logique de délégation que celle que tu viens de lire, autre support : l’agent vit dans WhatsApp, Telegram, iMessage, l’email, Slack ou l’app Desktop, et les spécialistes à qui il délègue atteignent Notion, Gmail, Google Calendar, Outlook, Linear, GitHub et Dropbox plutôt qu’un working tree. Un vocal enregistré en marchant devient une ligne Notion classée et une réponse rédigée. Il n’y a pas de repository à sélectionner, parce que le livrable n’a jamais été un diff.

Deux choses sur la facturation, puisque tout l’intérêt de faire tourner des spécialistes, c’est de ne pas avoir de mauvaise surprise. La consommation est incluse dans le forfait au lieu d’être facturée en plus, avec 20 $ de consommation par mois sur Pro, 59 $ sur Pro+ et 149 $ sur Ultra, et une tâche type qui n’y prélève que quelques centimes ; au-delà de l’enveloppe, la consommation à la demande continue de fonctionner et est facturée à terme échu. Et tout appel payant à l’usage facturé plus de 1,20 $ est refusé d’office : l’agent doit alors annoncer le prix et demander avant de réessayer. Pro coûte 13 $/mois en facturation annuelle.

Ce que je ferais cette semaine

Si tu débutes : écris exactement deux agents. Un reviewer en lecture seule sur haiku ou sonnet, et un lanceur de tests avec maxTurns défini. Supprime tous les fichiers de persona que tu n’as pas écrits toi-même.

Si tes agents fonctionnent déjà : sors une tâche récurrente de ton ordinateur. Une routine nocturne qui lit les PR fusionnées la veille et ouvre une PR de mise à jour de la documentation est un meilleur premier candidat que n’importe quoi d’interactif.

Si l’essentiel de ce qui te vide ta semaine ne touche jamais un repo : arrête d’essayer de faire faire ça à un harness de code. Ce travail a besoin d’un agent qui vit là où tu écris déjà.

Le format du fichier s’apprend en dix minutes. Décider ce qui mérite sa propre fenêtre de contexte, et quelle machine doit s’en charger, c’est la partie qui change vraiment ta semaine.