Trois fichiers de subagent qui valent encore le coup
Un fichier de subagent Claude Code est un fichier Markdown qui définit un assistant avec son propre contexte neuf. Anthropic recommande d'utiliser moins de subagents et ne les garde que dans quelques cas, avec un test à l'appui. Nous avons écrit les fichiers qu'elle conserve, lancé chacun sur un vrai dépôt, puis passé un agent de plus à son fold test. Environnement : Claude Code 2.1.294 avec Opus 5.5, exécutions du 2026-11-08, sur une petite API de facturation en TypeScript et sur le dépôt de Hono.
Le piège, c'est que le conseil à la mode dit de supprimer vos subagents, alors que l'article d'Anthropic les garde pour des cas précis et donne un test. Nous l'avons appliqué à l'agent que toute collection fournit, un rédacteur de tests. Replié dans un skill, il a réussi les douze exécutions. Trois fichiers survivent : un scout en lecture seule, un reviewer en lecture seule qui a validé un changement au vert tout en signalant un risque dont personne n'avait parlé, et un builder isolé qui a livré une fonctionnalité entière dans sa propre copie du dépôt pendant que la session principale continuait à travailler.
Ce qu'est un fichier de subagent, et le test d'Anthropic
Un subagent est un assistant avec son propre contexte neuf. Dans un gros dépôt, tout ce que lit votre session reste dans son contexte, c'est-à-dire sa mémoire de travail, et celle-ci se remplit. Un subagent fonctionne comme un collègue à qui l'on confie un ticket : il lit la moitié de la base de code et renvoie une courte note.
Vous créez un dossier agents dans votre dossier .claude, et chaque subagent y est un fichier Markdown. En haut, vous écrivez un nom et une description qui dit quand l'utiliser. Ce sont les deux seuls champs obligatoires. La description compte plus qu'il n'y paraît, car c'est elle que Claude lit pour décider d'appeler ou non l'assistant. Quand nous avons tapé la commande agents, Claude Code nous a dit que l'assistant de création avait été supprimé : vous écrivez donc le fichier vous-même, ou vous le demandez à Claude. La documentation des sub-agents décrit le format.
L'équipe d'IA appliquée d'Anthropic a écrit un article sur le repli des subagents dans l'agent principal, destiné à leur plateforme. Elle garde les subagents dans trois cas : votre contexte gonfle, vous avez besoin de travail parallèle dans des contextes neufs que vous jetez, ou votre agent n'arrive pas à choisir les bons outils. Tout le reste peut en général être un skill, c'est-à-dire les mêmes instructions chargées dans votre session principale au besoin. Le test : construire un petit eval, replier le subagent, et ne garder le subagent que si la version repliée obtient un moins bon score.
Le coût d'un subagent, c'est qu'il démarre à l'aveugle. Il ne sait que ce que vous mettez dans son prompt, et chaque passation peut perdre un détail. Avant d'écrire le moindre fichier, nommez donc le cas auquel il répond.
Le fold test d'Anthropic sur un quatrième agent
Le fold test est la méthode d'Anthropic pour décider si un subagent mérite son fichier. Il s'appuie sur un eval, un ensemble fixe de tâches que l'on lance toujours de la même façon, avec une règle de réussite choisie à l'avance. Nous l'avons appliqué au rédacteur de tests, l'agent que presque tout le monde ajoute parce que chaque collection en fournit un. C'est un subagent qui écrit des tests pour un module, ne touche jamais à votre code source et relance la suite jusqu'à ce qu'elle soit verte.
La méthode : garder le fichier d'agent tel quel, copier les mêmes instructions dans un skill, et lancer chaque tâche plusieurs fois avec l'agent. Puis mettre le fichier d'agent de côté et relancer les mêmes tâches avec le skill. On ne perd rien si le test donne tort au fichier, puisqu'on ne fait que déplacer les instructions.
Nous l'avons fait tourner sur notre petite API de facturation, avec un prompt par module, par exemple « add tests for the router », soit six tâches avec deux exécutions chacune par variante. La règle de réussite était fixée d'avance : la suite doit être verte, aucun fichier source ne doit changer, et les nouveaux tests doivent détecter un bug planté. Un bug planté est une minuscule modification du code que les anciens tests ratent, donc un bon nouveau test doit échouer dessus.
| Variante | Invoqué | Réussite | Coût moyen | Durée moyenne |
|---|---|---|---|---|
| Subagent | 12/12 | 11/12 | 0,410 $ | 72 s |
| Replié dans un skill | 12/12 | 12/12 | 0,262 $ | 36 s |
Le subagent a échoué une fois. Sur le routeur, il a tenté une commande de test que les réglages de notre projet n'autorisaient pas : personne n'a donc lancé ses nouveaux tests, et l'un d'eux était rouge. La version repliée a pris environ moitié moins de temps, parce que la session principale connaissait déjà le dépôt et n'avait pas à briefer un assistant de zéro. Le rédacteur de tests replié répond plus vite et coûte moins cher à chaque requête, sans rien perdre. L'article frère d'Anthropic dit que les montages à plusieurs agents consomment typiquement bien plus de tokens qu'un agent seul, et nos exécutions vont dans le même sens.
Le rédacteur de tests échoue au fold test, car replié il fait au moins aussi bien pour moins cher. La limite : c'est un petit eval de douze exécutions par côté sur un seul dépôt, et l'échec tenait en partie à nos permissions. Lancez-le sur votre propre dépôt et lisez toute exécution qui bascule. Nous avons écrit le skill, lancé les deux versions, et le fichier d'agent est parti, parce que la version repliée n'a jamais fait moins bien.
Fichier un : le scout en lecture seule
Un scout est un subagent qui ne peut que lire et chercher, et qui renvoie quelques lignes avec la preuve. Sans lui, une question qui demande de lire beaucoup de fichiers oblige votre session principale à tous les lire, puis à porter chaque ligne ensuite.
Vous ne lui donnez que les outils de lecture et de recherche, rien d'autre : il ne peut donc ni modifier un fichier ni lancer ses propres assistants. Vous le mettez sur Haiku, le petit modèle bon marché d'Anthropic, parce que lire et chercher n'exigent pas votre meilleur modèle. Vous écrivez aussi un contrat de retour, la forme de réponse exigée : la réponse d'abord, puis le fichier et la ligne qui la prouvent, puis ce qu'il n'a pas trouvé. Dans la description, vous dites à Claude de l'utiliser pour les questions qui demandent de lire beaucoup de fichiers, un scout par question, en parallèle.
Nous avons cloné Hono, un grand framework web open source, et demandé un audit de la façon dont ses vingt-sept middleware intégrés rejettent une requête. Nous avons fait l'audit en inline sans aucun agent, puis avec des scouts en parallèle, chacun prenant une part des dossiers. Les deux méthodes ont donné la même réponse, jusqu'aux mêmes middleware et aux mêmes codes de statut. Deux exécutions chacune :
| Mesure | Inline, exécution 1 / exécution 2 | Scouts, exécution 1 / exécution 2 |
|---|---|---|
| Contexte principal à la fin (tokens) | 45 868 / 47 476 | 30 505 / 33 937 |
| Coût | 0,457 $ / 0,433 $ | 0,267 $ / 0,344 $ |
Avec les scouts, la session principale a fini environ un tiers plus légère, parce qu'elle a lu leurs courtes notes au lieu de chaque fichier. Cette marge compte quand vous continuez à travailler dans la même session : votre tâche suivante démarre avec moins d'encombrement et moins de choses à oublier. Les scouts tournaient sur le modèle bon marché, donc l'ensemble a coûté moins cher. C'est le cas que décrit Anthropic : la grosse lecture se fait à un endroit que l'on jette, et votre session garde de la place pour le travail qui suit.
Reste la limite. Sur les petites questions qui ne demandent que quelques fichiers, les scouts n'ont presque rien fait gagner. Un benchmark publié sur dev.to a constaté la même chose sur des recherches ordinaires : le fan-out n'a rien trouvé de plus et a coûté beaucoup plus cher. La session principale a aussi repris la réponse des scouts sans ouvrir elle-même les fichiers, alors vérifiez les lignes de preuve avant d'agir dessus. Envoyez un scout quand la lecture est grosse et que votre session a encore du travail ensuite, et passez votre tour pour une recherche rapide.
Fichier deux : le reviewer en lecture seule
Un reviewer est un subagent au regard neuf qui ne peut que lire. Quand vos tests sont verts, il est tentant de fusionner un changement que personne n'a relu, et la session qui a écrit le changement est la pire pour le juger, car elle croit déjà à son propre plan. Le reviewer voit la spec et le diff, c'est-à-dire la liste des lignes que le changement ajoute et supprime.
Vous ne lui donnez que les outils de lecture et de recherche. Vous omettez edit et write, pour qu'il ne puisse pas corriger ce qu'il trouve, et vous omettez l'outil agent, pour qu'il ne puisse pas lancer d'assistants. La documentation d'Anthropic le dit exactement : gardez un reviewer en lecture seule en laissant de côté l'outil agent. Vous écrivez ensuite la forme de la réponse dans le fichier : un verdict, réussite ou échec, puis chaque constat avec son fichier, sa ligne et le code cité, puis ce qu'il n'a pas pu prouver. Une règle de plus le garde honnête : pas de remarques de style et aucun constat sans ligne citée, si bien que chaque constat vient avec une ligne que vous pouvez ouvrir et vérifier vous-même.
Nous lui avons donné un vrai changement, un export tableur des factures ouvertes écrit par notre builder, avec la spec et le diff complet. Il est revenu en dix-neuf secondes avec une réussite et un constat mineur sur une fiche client qui pourrait manquer. Sous « ce qu'il n'a pas pu prouver », il a signalé deux choses dont personne n'avait parlé. Un nom de client commençant par un signe égal pourrait s'exécuter comme une formule dans un tableur, et les lignes étaient triées comme du texte, ce qui ne fonctionne que tant que les numéros de facture gardent la même longueur. C'est un reviewer qui valide un changement au vert tout en signalant un risque, et sans toucher à un seul fichier.
Nous avons vérifié chaque point nous-mêmes. Rien ne supprime un client, donc le constat de fiche manquante ne peut pas se produire, mais le risque de formule et le tri valent la peine d'être corrigés. La limite : un reviewer ne sait que ce qu'il peut lire, il marque donc le reste comme non prouvé, et vous vérifiez chaque constat avant d'agir. Lancez le reviewer après le build et avant la fusion, et lisez sa liste de non prouvé aussi attentivement que son verdict.
Fichier trois : le builder isolé
Un builder est un subagent qui écrit du code dans son propre worktree, c'est-à-dire une seconde copie de votre dépôt, sur sa propre branche, dans son propre dossier. Il convient à un morceau de travail autonome qui ne doit pas bloquer votre session pendant qu'on le construit.
Vous réglez le champ d'isolation sur worktree, et Claude Code crée cette copie pour lui et la nettoie si rien n'a changé. Vous fixez aussi un plafond de tours, pour qu'un builder qui tourne en rond s'arrête et rende ce qu'il a, marqué comme partiel. Sans plafond, un builder bloqué peut continuer à dépenser des tours sur le même test en échec pendant que vous attendez pour rien. Dans les instructions, vous lui dites de rapporter sa branche, de lancer les tests et la vérification de types jusqu'à ce que les deux passent, puis de commiter.
Nous lui avons demandé un export tableur des factures ouvertes, avec des noms de clients pouvant contenir des virgules et des guillemets, tests inclus. Il est parti en arrière-plan, et pendant qu'il travaillait nous avons posé à la session principale une autre question : quelles factures peuvent être annulées, et où vit cette règle. La session principale a répondu avec la ligne exacte dans le code, et le builder ne l'a jamais gênée. Le builder est revenu en environ une minute et demie avec un commit sur sa propre branche et quatorze nouveaux tests, tous au vert. Notre branche principale n'a pas bougé tant que nous n'avons pas choisi de fusionner. Nous n'avons fusionné qu'après la réussite du reviewer, et la branche principale a simplement avancé jusqu'au commit du builder, sans aucun commit de fusion. Vous voyez toujours le travail du builder sous forme de branche que vous pouvez lire, tester et fusionner, ou jeter.
Un article sur le fan-out résume la règle en une ligne : fan-out pour les lectures, un seul agent pour les écritures. La limite : le worktree part de votre branche par défaut, pas de l'endroit où vous êtes, donc le travail non commité n'y figure pas. Ne l'envoyez jamais sur du code que votre session principale est en train de modifier, et ne lancez jamais une équipe de builders qui écrivent en même temps. Donnez au builder un morceau autonome, continuez à travailler, et fusionnez après la revue.
Verdict : trois fichiers et un test
Anthropic dit d'utiliser moins de subagents, et elle a raison, mais trois fichiers méritent encore leur place, chacun pour une raison que vous pouvez nommer. Le scout garde une grosse lecture hors de votre session principale. Le reviewer vous donne un regard neuf qui ne peut que lire. Le builder écrit un morceau séparé dans sa propre copie du dépôt. Écrivez cette raison dans la description de chaque fichier, car c'est ce que Claude lit pour décider de l'appeler. Si vous ne pouvez pas écrire la raison en une phrase, c'est en général le signe que l'agent devrait être un skill.
Le rédacteur de tests a fait aussi bien en skill, donc son fichier est parti, et le vôtre aussi, probablement. Passez votre tour pour une question rapide, pour du code que votre session modifie déjà, et pour tout persona sans raison de contexte d'exister. Dans ces cas, un assistant vous coûte un briefing, une attente et une passation, et ne vous apporte rien que votre session ne sache faire. Les agent teams, des sessions qui s'envoient des messages, sont autre chose, et rien ici n'en a besoin.
La seule règle est celle qu'a écrite Anthropic : avant qu'un nouvel agent reçoive un fichier, repliez-le dans un skill, lancez les deux, et ne gardez le fichier que si le skill obtient un moins bon score.
AIDive