Les sous-agents en pratique : rôles, budgets, interdictions et défaillances silencieuses

Les compétences permettent de résoudre un type d’oubli : l’agent cesse de perdre de vue l’aspect de votre base de code. Un autre type d’oubli persiste, et il concerne l’identité. À chaque nouvelle session, le modèle arrive en tant que généraliste zélé, prêt à exprimer une opinion raisonnable et banale sur tout ce que vous lui présentez.

La connaissance correspond au problème des compétences. Le rôle correspond au problème des sous-agents, et c’est ce que traite cet article.

En bref, avant que la longueur ne vous décourage : une compétence indique au modèle à quoi ressemble votre monde, tandis qu’un sous-agent lui indique quel rôle jouer. Avoir les deux est mieux que n’en avoir qu’un, et pour un développeur solo qui gère plusieurs projets inachevés en même temps, cette combinaison est d’autant plus importante. Vous êtes le seul spécialiste de l’équipe, et vous ne pouvez pas occuper cinq postes en même temps.

La première moitié ci-dessous constitue les bases conceptuelles : de quoi il s’agit pour ces fichiers, où ils se trouvent sur le disque, et comment en créer un. Tout cela peut être obtenu à partir de la documentation. La seconde moitié provient uniquement de l’exécution de deux sous-agents pendant des mois dans une douzaine de répertoires, en observant leurs échecs de manières que aucune notice de bonnes pratiques n’avait prévues. Ces deux agents sont open source, et les fichiers réels valent la peine d’être lus, car une instruction affinée par des tests réels enseigne plus que n’importe quel conseil.

Le rôle comblé par un sous-agent

Un agent de codage est fourni avec une personnalité par défaut, celle du généraliste serviable. Lorsque vous demandez une revue de demande de fusion, vous recevez des retours généraux et raisonnables. Si vous vous demandez pourquoi une application est lente, il se concentre sur le dernier fichier que vous avez modifié. Pour obtenir un plan de migration de base de données, les résultats semblent sensés, mais trois éléments cruciaux pour le fonctionnement en production sont omis.

Rien de tout cela n’est dû à une intelligence insuffisante. Ce qui manque, c’est un cadre adapté au rôle. Une personne chargée des vérifications de sécurité pense différemment d’un ingénieur en sécurité, et celle qui cherche à corriger une erreur examine des preuves différentes de celle qui a déjà été appelée pour ce même problème à trois reprises. L’intelligence est déjà présente ; ce qui fait défaut, c’est le contexte approprié.

Le mécanisme de génération consiste à taper sans cesse le même préambule. Avant de permettre à Claude Code d’examiner une modification, on peut coller quelque chose comme : « Vérifiez cela comme un expert en sécurité paranoïaque, contrôlez d’abord les limites d’authentification, dites-moi ce qui s’infiltre dans les journaux, ignorez les petites remarques sur le style ». Lorsque cela se produit pour la troisième fois en deux semaines, on se rend compte que ce préambule représente un rôle, et qu’un rôle que l’on tape constamment correspond à un sous-agent que personne n’a encore créé.

La répétition de la saisie est le déclencheur mentionné dans tous les guides. Ce n’est pas elle qui a donné naissance aux deux agents qui ont survécu, ceux-ci étant issus de deux autres facteurs de pression.

• Économie de contexte. La recherche est complexe : vingt recherches, une douzaine de pages récupérées, dont la moitié est inutile. Si cela se produit lors de votre session principale, celle-ci se remplit de contenu inutile que vous ne souhaitez pas lire. Le travail doit avoir lieu ailleurs et revenir sous forme de résumé. C’est là toute la raison d’être de l’agent de recherche sur le web. Il n’est pas plus intelligent que le thread principal ; son rôle est simplement de maintenir ce qu’il a lu en dehors de votre contexte.
• Séparation des rôles. Lors du travail de conception, vous souhaitez rester dans le cadre de la discussion relative à la conception. Être tiré hors de ce cadre pour approuver la onzième modification technique, qui découle clairement d’une décision déjà prise, est une perte de temps. Ainsi, les décisions restent entre les mains des humains, tandis que la saisie est confiée à un agent d’implémentation. Les capacités n’ont rien à voir avec cette séparation ; ce qui compte, c’est de déterminer qui doit réfléchir à quoi.

Un évaluateur constitue un premier sous-agent agréable. Ces deux types sont différents : ce sont eux qui transforment une fonctionnalité utile en le mode de fonctionnement réel d’un projet.

Compétences versus sous-agents : connaître versus agir

Une compétence regroupe ce que l’agent doit connaître : sa bibliothèque interne particulière, les particularités de l’environnement qui perturbent les compilations, les faits propres au domaine que tout nouvel employé compétent doit connaître car personne ne pourrait les deviner. Elle s’active selon des conditions, lorsque c’est pertinent.

Un sous-agent regroupe la manière dont l’agent doit agir : ce pour quoi il optimise, ce qu’il examine en premier, les compromis qu’il choisit par défaut, et la forme que doit prendre la réponse. Il n’apporte rien de nouveau au modèle. Il oriente l’intelligence déjà présente vers une tâche spécifique.

Un test utile consiste à imaginer qu’on sollicite un collègue spécialiste. S’il apporte principalement des informations que vous manquez (connaissances sectorielles, contexte, sagesse acquise), il s’agit alors d’une compétence. S’il apporte surtout une manière d’aborder le problème, c’est-à-dire ce qu’il examine en premier, ce qu’il prend en compte de manière importante, ce qu’il refuse d’approuver sans vérification et ce qu’il restitue, il s’agit alors d’un sous-agent.

Prenons l’exemple d’un ingénieur en sécurité qui examine votre code. Il ne possède pas seulement plus de connaissances que vous ; il travaille différemment : il commence par définir les limites d’authentification, accorde une importance bien plus grande à la possibilité d’escalade de privilèges qu’à un nom de variable peu élégant, ne valide rien sans commentaire concernant les secrets, et présente ses constatations sous forme de liste structurée. Cet ordre d’attention est ce que codifie un sous-agent.

Les connaissances font partie d’une compétence. La méthodologie fait partie d’un sous-agent.

Qu’est-ce qu’un sous-agent dans Claude Code

Claude Code est l’outil de référence ici car il est utilisé au quotidien. Les autres outils ont leur propre section plus bas, y compris leurs particularités.

Dans Claude Code, un subagent n’est en réalité rien de plus qu’un document Markdown commençant par un petit bloc YAML. Deux répertoires peuvent le contenir :

• ~/.claude/agents/ est la bibliothèque personnelle, disponible dans chaque projet de la machine. Considérez-la comme un environnement isolé.
• .claude/agents/ à l’intérieur d’un répertoire de dépôt est limité à ce projet et est transféré avec le répertoire une fois qu’il a été commité.

Le frontmatter est court. Voici un exemple complet fonctionnel :

---
name: migration-risk-reviewer
description: Reviews database migration plans and schema changes for rollback risk, lock contention, and data integrity problems. Use before running any migration against real data.
tools: Read, Grep, Glob
model: sonnet
---

You are a senior database engineer reviewing a migration for production risk.

## What you look at first

- Can this be rolled back without losing data?
- Does it hold locks on a busy table during deploy?
- Is the ordering safe for a multi-step change?
- Will existing data violate any new constraint?

## Output shape

Findings in order of severity:

1. Blockers — deploy will fail or data will be lost
2. High risk — real production risk, needs a mitigation
3. Medium risk — should fix, won't necessarily block
4. Notes — worth tracking

For each finding: what it is, why it matters, what to do about it.

Il y a plusieurs aspects liés à la manière dont Claude Code gère un fichier de ce type qui sont utiles à connaître.

• Le corps du fichier constitue l’instruction système. Tout ce qui se trouve sous le frontmatter devient les instructions du sous-agent lorsqu’il est exécuté. Il ne s’agit pas de documentation que le modèle lit puis met en œuvre ; il la lit et l’adopte comme son identité.
• La description a une grande importance. Claude Code s’y réfère pour décider quand transférer automatiquement le travail, il faut donc la rédiger comme une API que quelqu’un d’autre doit découvrir à partir du contexte. Des expressions comme « À utiliser avant d’exécuter toute migration » fonctionnent, tandis que « Aide pour les questions de base de données » ne le font pas. Il faut également inclure les aspects négatifs : les deux agents mentionnés ici indiquent clairement à quoi ils ne servent pas, car le système transmettra volontiers un travail à un agent qui n’est pas compétent pour le gérer.

tools représente une liste d’autorisation. En l’omettant, le sous-agent hérite de tout. En la restreignant, on obtient un évaluateur physiquement incapable d’éditer vos fichiers, même s’il a des idées. Pour un agent d’évaluation, c’est plutôt un avantage, car une approche consistant simplement à « me dire ce qui ne va pas » ne devrait pas modifier les choses à la légère.

model est un choix lié au budget plutôt qu’un détail technique. Un modèle bon marché convient aux tâches mécaniques, tandis qu’un modèle coûteux est adapté aux décisions nécessitant du jugement. Une section ultérieure aborde ce sujet en détail, car elle explique en grande partie pourquoi la délégation s’avère rentable.

Il dispose de sa propre fenêtre de contexte. Les gens sous-estiment cet aspect : le sous-agent travaille dans un contexte distinct et renvoie un résumé, de sorte que votre session principale n’est pas submergée par tout ce qu’il a lu. C’est également là que les problèmes surviennent, comme l’expliquera une section ultérieure.

Vous n’avez pas besoin d’écrire le fichier manuellement. Décrivez le rôle à Claude Code et il créera le fichier à l’endroit approprié. La commande /agents gère également ces fichiers.

Vous pouvez appeler un sous-agent en le demandant explicitement, en laissant Claude le rediriger en fonction de la description, ou en l’intégrant dans un flux plus large où il fonctionne en tant qu’agent délégué. Le comportement est identique dans tous les cas.

Le mot « agent » remplit trop de fonctions

Ce terme est utilisé pour désigner quatre choses différentes, et leur confusion provoque une perplexité constante. Voici une distinction claire :

• Un sous-agent (un fichier dans .claude/agents/, ou un fichier .agent.md dans l’espace Copilot) est un fichier réutilisable qui définit un rôle spécialisé. C’est de cela dont traite cet article.
• Mode agent ou exécution autonome est un interrupteur de fonctionnalité. Vous permettez à l’outil d’exécuter des commandes et d’éditer des fichiers sans avoir à valider chaque ligne. Il s’agit d’une configuration de permissions et n’a rien à voir avec les spécialistes.
• Un agent de codage en arrière-plan ou dans le cloud est un service qui prend une tâche, la traite en secret, puis renvoie une branche ou une demande de fusion. Ce n’est pas non plus un fichier spécialisé.
• Un fichier d’instructions au niveau du répertoire représente des directives toujours actives, les règles de base que tout agent doit respecter dans ce codebase. Pensez-y comme au manuel du personnel, et non comme à un collègue que l’on appelle par son nom.

Chaque fois que le terme « subagent » apparaît par la suite, il désigne un spécialiste réutilisable, écrit une seule fois et invoqué intentionnellement. Comprendre bien ces quatre concepts éclaircit déjà la moitié des confusions.

Rédiger le premier

Commencez par l’élément le plus simple qui permet d’obtenir des résultats concrets. Un premier sous-agent a deux tâches : définir son rôle et préciser ce que ce rôle signifie en pratique. L’outil d’examen de migration mentionné précédemment fait déjà cela. Il possède un rôle clair, des heuristiques spécifiques et une structure de sortie prévisible, et il est délibérément restreint. D’autres éléments sont ajoutés après avoir testé son fonctionnement sur des cas réels pour identifier ce qu’il manque.

Les premiers sous-agents échouent le plus souvent en raison d’un rôle flou. « Aide à la sécurité » n’est pas un rôle, car rien dans cette expression ne précise au modèle ce qu’il doit optimiser ou examiner en premier. Un vrai rôle fonctionne comme un contrat comportemental qui couvre la tâche elle-même, les éléments à examiner en premier, ainsi que ceux qui ne doivent jamais être ignorés. Si la tâche ne peut pas être décrite en une phrase, elle est trop vague.

Une version concrète précise ce dont le modèle doit se soucier et ce qu’il doit ignorer. Ignorer fait déjà la moitié de la valeur. Un évaluateur qui accorde la même importance à une faute d’orthographe qu’à une limite de privilèges n’est rien d’autre qu’une machine de moyenne.

Ce qui figure dans le corps du texte

Une fois le rôle défini, un corps de texte utile couvre cinq éléments. Le premier jour, il n’est pas nécessaire d’en inclure tous.

1. Ce pour quoi il optimise. La seule chose que ce rôle s’efforce le plus d’obtenir correctement. Lorsqu’un compromis apparaît, c’est vers cela qu’il cherche à s’orienter.
2. Ce qu’il examine en premier. Les signaux de priorité absolue que tout véritable spécialiste lit avant tout le reste.
3. Les modes de défaillance. Les manières particulières dont ce type de travail échoue. C’est ici que réside la véritable expertise, et la plupart d’entre elles ne se révèlent que en observant l’agent commettre des erreurs sur des tâches réelles.

Forme du résultat. Pas un simple « retour d’information », mais des constatations classées par gravité, un plan en phases, ou une liste hiérarchisée d’hypothèses. Un résultat prévisible représente l’avantage pratique majeur par rapport à une simple demande.

Ce qu’il ne doit pas faire. Cette section était autrefois considérée comme optionnelle, mais ce n’est plus le cas. Dans l’agent le plus utilisé ici, c’est la partie la plus longue du fichier, et chaque ligne y fait référence à un incident spécifique.

Commencez par le rôle, les premières vérifications et la forme du résultat, et laissez les erreurs fournir le reste.

Exemple : un chasseur de bugs qui ignore le dernier commit

Voici un exemple né d’un problème récurrent. Quelque chose ne fonctionne plus, l’erreur est collée dans Claude Code, et son premier réflexe est d’examiner le fichier qui a été modifié récemment. Parfois c’est correct. Souvent, la dernière modification n’a aucun rapport avec le problème.

Un débogueur expérimenté ne commence pas par le code. Il commence par des preuves, c’est-à-dire ce qui échoue réellement, ce que disent les journaux d’erreur et ce qui a changé dans l’environnement, et il n’ouvre le code source que lorsque l’hypothèse vaut la peine d’être testée. Il s’agit d’un comportement, c’est pourquoi il a été enregistré en tant qu’agent :

---
name: bug-investigator
description: Investigates a bug or failure starting from evidence, not from recent code changes. Produces ranked hypotheses with the next diagnostic step for each. Use for "why is this broken" before touching the source.
tools: Read, Grep, Glob, Bash
---

You are a senior engineer investigating a failure. Your job is to find the most
likely cause, rule out the alternatives, and say what to check next.

## Investigation order

1. Start from the symptom — what is actually failing, and how does it show up?
2. Get the error output and any logs from around the time it broke — ask the caller for them if they weren't provided.
3. Only then look at recent changes, and only if the evidence points there.
4. Read source last, once there's a symptom-to-cause hypothesis worth testing.

## Output shape

**Symptoms:** what's failing and how it manifests.
**Likely causes (ranked):** for each — the hypothesis, the evidence for it, the next diagnostic step.
**Ruled out:** what you checked and why it isn't the cause.
**Next steps:** in priority order.
**Open questions:** what you still can't confirm.

## Failure modes to avoid

- Don't assume the last change is the cause without evidence.
- Don't propose a fix before you can name the mechanism.

Vient ensuite l’étape que les gens sautent : le tester sur un vrai bug déjà résolu, et non sur un exemple fictif. Donnez-lui les symptômes ainsi que les journaux d’activité de l’époque, et observez si sa méthode d’enquête correspond à celle qui a réellement permis de trouver le problème. Partout où elle s’écarte, cet écart devient une nouvelle ligne dans le rapport.

C’est là que se terminent la plupart des rapports sur les sous-agents. Tout ce qui suit décrit ce qui se passe après des mois d’utilisation, c’est-à-dire la partie qui devait être rapportée.

Le contraire de ce qui était attendu : un sous-agent débute sans aucune information

Tout le monde présente la fenêtre de contexte isolée comme une véritable avancée. Or, cela a des effets contradictoires.

Une phrase a été transmise à l’agent d’implémentation après que trois transferts différents aient échoué. Elle décrit l’agent comme quelqu’un qui connaît bien le projet, mais qui ignore complètement les discussions de planification qui ont précédé la tâche.

Une conversation « froide » signifie qu’elle n’a jamais pris en compte ces deux heures durant lesquelles vous avez écarté l’approche évidente, abandonné une idée abstraite, et choisi une solution étrange pour une raison valable. Pour le sous-agent, rien de tout cela ne s’est produit. Une conversation « chaude » signifie qu’il dispose de CLAUDE.md ainsi que du code source, ce qui lui permet déjà de connaître les règles et les conventions sans qu’on ait à les lui expliquer.

Si l’on se trompe dans l’une ou l’autre hypothèse, le résultat est un désordre prévisible. En supposant que l’agent partage votre conversation, il reconstruira volontiers le design que vous avez rejeté il y a une heure, car de son point de vue, ce design semble parfaitement correct. En supposant qu’il ne sait rien du projet, vous passerez mille tokens à décrire un répertoire qu’il aurait pu lire plus rapidement que vous ne pourriez le résumer.

La conclusion à laquelle aucun guide d’agent subalterne n’a abouti : le transfert est un fichier, et ce fichier, c’est le contrat. Il ne s’agit pas d’un paragraphe tapé dans l’instruction de tâche. C’est un document sur le disque composé de sections fixes, car une instruction improvisée omet silencieusement une section cruciale différente à chaque fois.

Dans ce cadre, le transfert correspond à un TASKS.md situé dans la racine du répertoire, généré par une compétence de planification. La tâche en cours comprend ces sections et aucune autre :

• Objectif. Ce qui sera vrai une fois le travail terminé.
• Pourquoi (pointeur). Un lien vers la décision enregistrée dans PLAN.md, et non un nouvel argument en faveur de celle-ci. Un pointeur, pas du texte narratif.
• État d’exécution. L’agent met cet élément à jour en permanence. Nous en parlerons plus en détail juste ci-dessous, car c’est la section qui vous sauve.

Conception en éléments numérotés. Une file d’attente séquentielle où [ ] signifie non commencé, [x] terminé et [!] bloqué, avec les dépendances indiquées en ligne, comme dépend de #2.

Fichiers. L’endroit où le travail a lieu.

Tests. Les vérifications servant de remplacement à l’examen.

Hors champ. La section la plus précieuse de tout le document.

Rapport de retour. Ce que le message final doit contenir.

Ce qui fait fonctionner ce système, c’est une règle : remplir chaque section avant de commencer, et ne mettre un trait que si elle ne s’applique vraiment pas. C’est dans les sections non remplies que l’agent improvise.

Il y a ensuite la distinction qui a mis le plus de temps à être remarquée : deux documents ayant des durées de vie différentes. Les connaissances de base concernant la manière de réaliser le travail ici doivent figurer dans la définition de l’agent, et non être répétées pour chaque tâche. Le fichier de l’agent contient le protocole, c’est-à-dire la façon de lire une tâche, de gérer un obstacle, quels éléments ne doivent jamais être modifiés et ce qu’un rapport comprend. Le fichier de la tâche contient le travail en cours. Coller une instruction dans trois tâches consécutives indique qu’il ne s’agissait jamais de contenu de tâche, et elle devrait être transférée dans l’agent.

État d’exécution, car les sessions s’arrêtent

Une seule règle a permis d’accomplir plus de travail réel que n’importe quelle technique ingénieuse de formulation de requêtes. Chaque fois que l’agent s’arrête, que ce soit parce qu’il a terminé ou qu’il est bloqué, il doit enregistrer l’état actuel des choses : cocher la case de statut de chaque tâche au fur et à mesure, et mettre à jour une note d’état décrivant ce qui a été fait, ce qui est bloqué et pourquoi, ce qui reste à faire et où reprendre. Modifier TASKS.md à cette fin fait explicitement partie des compétences requises, car ce fichier constitue le point de récupération en cas d’arrêt de la session.

Les sessions s’arrêtent bel et bien. L’ordinateur portable se ferme, la connexion est interrompue, une limite d’utilisation est atteinte, ou bien on s’ennuie et on appuie sur Ctrl-C sur une tâche presque terminée. Lorsque cela arrive à un sous-agent, tout ce qu’il savait disparaît. Si le seul enregistrement des progrès se trouvait dans sa mémoire, il faudrait alors comparer son répertoire de travail avec sa mémoire pour deviner jusqu’où il était parvenu.

Ainsi, l’agent enregistre les progrès sur le disque au fur et à mesure, directement dans le fichier qui a attribué la tâche. Une session ultérieure ouvre ce fichier et reprend à l’endroit marqué. Elle ajoute quelques lignes à la définition de l’agent et transforme une session terminée en situation de travail perdu en une session en pause.

Une règle complémentaire concerne le débit plutôt que la récupération. Un élément bloqué ne met pas en pause la file d’attente. Lorsqu’un élément est mal spécifié ou rencontre une dépendance irrésoluble, l’agent le marque [!] avec une raison en une seule ligne et continue avec tous les éléments restants qui ne dépendent pas de lui, ne s’arrêtant que lorsqu’il n’y a plus rien de possible à faire. Il ne suppose jamais le design, et tout embranchement bloqué est inclus dans le rapport pour être traité par un humain.

Le comportement par défaut face à un obstacle est de s’arrêter et de poser des questions, de sorte qu’une file de huit tâches génère une tâche et une question. Le comportement par défaut sans contraintes est encore pire : l’agent devine une solution de conception et continue, laissant sept éléments construits sur une invention que personne n’a approuvée. Sautez cette étape et continuez, ne devinez jamais, signalez plutôt la situation. C’est cette combinaison qui vous permet de mettre les tâches en file d’attente avant de vous éloigner.

Qui paie pour quel type de réflexion

Ici, le champ model joue un rôle essentiel, et l’économie du système en dépend.

La description de l’implementateur, tirée d’un projet réel, dit à peu près ceci : un travailleur Sonnet qui exécute une tâche de codage mécanique entièrement spécifiée à partir du fichier de tâches, tandis que le thread principal de planification Opus continue de fonctionner ; ce système n’est pas destiné aux décisions de conception, aux questions ouvertes ou aux tests de qualité en temps réel, qui restent tous dans le thread principal.

Le modèle coûteux prend les décisions tandis que le modèle bon marché s’occupe de la saisie. Un champ d’action restreint est précisément ce qui rend le modèle bon marché fiable : un travailleur Sonnet à qui l’on donne une file numérotée entièrement définie au sein d’une base de code qu’il peut lire fonctionne de manière fiable.

Cette séparation permet également deux rythmes de travail différents à partir de la même machine.

• Planifié. On aligne deux ou trois tâches, on envoie l’agent à l’œuvre, puis on planifie le prochain lot pendant qu’il travaille. Aucune des deux parties ne reste inactive en attendant l’autre.
• Sans surveillance. On remplit la file de tâches, puis on s’éloigne pour revenir plus tard avec une comparaison, un rapport et une note indiquant quelle tâche a été bloquée et pourquoi.

En dessous de tout cela se trouve la couche de permissions qui applique réellement les règles. L’implementateur non supervisé a ses commandes de fichiers et de shell inscrites sur une liste autorisée dans les paramètres du projet, et tout ce qui dépasse cette liste doit être approuvé. Ce que indique l’invite est la politique ; la liste autorisée constitue la barrière.

Une autre ligne existe dans cet agent en raison de la plus coûteuse des erreurs : traiter les tâches numérotées en file séquentielle, de la première à la dernière, en une seule passe, sans travailleurs parallèles et sans arrêt pour faire un rapport après chaque tâche.

Les agents parallèles semblent offrir une vitesse accrue, mais ce n’est pas du tout le cas. Chacun finit par déverser tout son résultat dans le contexte qui l’a généré, et une structure de diffusion complexe peut entraîner l’engorgement de la session chargée de lire tout cela. Du travail réel est ainsi perdu. Exécuter des tâches en parallèle sur des fichiers distincts doit être une option pour des cas spécifiques, et non une configuration par défaut. La configuration par défaut consiste en un seul agent qui traite les éléments d’une file d’attente un par un.

Sans budget, il dépense tout

Tout sous-agent disposant d’outils tels que la recherche, la récupération de données ou un shell continuera à fonctionner jusqu’à ce que quelque chose l’arrête, et la conclusion « c’est suffisant » n’est pas une conclusion à laquelle un modèle parvient de manière fiable de lui-même. Un agent de recherche sans budget peut passer l’après-midi à examiner une multitude de onglets de navigateur cachés, pour finalement fournir un résumé que les trois premiers résultats auraient pu fournir.

Ainsi, l’agent de recherche sur le Web débute avec des limites strictes, imposées au-dessus de sa méthodologie et de tout le reste. Les fiches de procédure par source qu’il charge en temps de exécution, contenant des listes de sources et des tactiques de recherche pour chaque domaine, bénéficient d’une section dédiée un peu plus bas.

Quatre leçons tirées de ce tableau de limites sont plus importantes que les chiffres qu’il indique, lesquels doivent être ajustés en fonction de votre propre travail.

Proposez un réglage de profondeur plutôt qu’une limite fixe. Toute configuration unique est généralement inadaptée : trop stricte pour une question complexe, trop souple pour obtenir rapidement un fait. Avec trois niveaux nommés et un paramètre par défaut défini, choisir le mode deep devient une décision consciente plutôt qu’un hasard. L’ordre de priorité est également précisé : les valeurs indiquées par l’utilisateur priment, suivies d’un niveau spécifié dans la demande, puis de la configuration du projet, enfin du mode standard.

Un budget encourage les jeux, car un modèle le considère comme une cible, il faut donc des clauses pour en limiter l’usage. Les clauses importantes stipulent de récupérer une seule information par URL, de ne jamais relire une page déjà consultée, d’arrêter dès que les questions de l’utilisateur sont répondues, et de traiter le budget restant comme quelque chose d’autre qu’une quota. Une exécution profonde qui se termine après six recherches est considérée comme un succès et non comme un gaspillage.

Ce dernier paragraphe a été ajouté après qu’une exécution ait répondu à la question à la quatrième recherche puis ait continué malgré tout, car vingt était le nombre fixé. Il faut dire à haute voix que terminer tôt, c’est gagner.

Comptez les éléments qui coûtent quelque chose. Le budget de récupération inclut toutes les requêtes réseau, des récupérations natives jusqu’à chaque tentative supplémentaire pour les pages bloquées, ainsi que chaque requête HTTP dans un script d’aide, chaque tentative de réessai 429 dans ce script étant comptée séparément. Une version antérieure ne comptait que les « appels de récupération », ce qui permettait à l’agent de passer inaperçu par inadvertance. Ce n’était pas de la tricherie ; il suivait simplement à la lettre une règle mal écrite.

Faites en sorte qu’il annonce les dépenses. Après chaque phase, l’agent rapporte une ligne du type [deep: 3/20 recherches, 5/30 récupérations]. Sans cela, on ne peut pas distinguer une exécution minutieuse d’une exécution débridée avant qu’elle ne soit terminée. Si le budget s’épuise avec des questions restées sans réponse, l’agent s’arrête et indique précisément ce qui reste inconnu, quel URL est le plus susceptible de y répondre, et que relancer la recherche en profondeur est une option possible. La seule action interdite est de continuer au-delà de la limite sans le signaler, puisque c’est l’utilisateur qui a choisi ce niveau et que les dépenses excessives annulent ce choix.

Les interdictions constituent la majeure partie d’un agent mature

Ouvrez le fichier d’agent le plus utilisé, et ce qui saute aux yeux, c’est le rapport entre les informations fournies. La description du rôle occupe un seul paragraphe, tandis que les interdictions remplissent toute une liste. Ce déséquilibre n’est pas dû à du remplissage inutile. Un agent disposant d’outils réels a bien plus de moyens de se conformer aux exigences techniques que quiconque ne peut le prédire.

Un exemple montre pourquoi ces précisions supplémentaires sont essentielles. On indique à l’agent de ne jamais utiliser d’automatisation de navigateur : pas de navigateur simple, pas de prévisualisation intégrée, pas de Playwright, pas d’outils d’extension Chrome, pas d’ouverture de onglets ou de fenêtres, et si un outil de navigateur est proposé, il n’est pas destiné à cette tâche. La raison en est expliquée directement : l’ouverture d’onglets pour lire des pages a déjà généré une centaine d’onglets, ce qui a gâché une exécution.

Un autre exemple provient de l’implementateur du dépôt research-agent, où le mécanisme constitue la raison principale pour laquelle tout le monde respecte cette règle. Il ne doit en aucun cas créer de fichiers dans agents/ ou skills/, car agents/ contient le contenu à charger, et le gestionnaire de paquets transforme tous les fichiers .md qu’il contient en agents de niveau supérieur distincts au moment de l’installation. Un fichier égaré à cet endroit se retrouverait dans tous les projets consommateurs.

C’est le principe à retenir : chaque interdiction précise son mécanisme. Il n’est pas nécessaire de convaincre l’agent. La raison doit être écrite, car une contrainte sans explication sera modifiée. Six semaines plus tard, en affinant le texte, vous tomberez sur une phrase du type « jamais créer de fichiers ici » ; elle semblera arbitraire, et vous la généraliserez judicieusement. La clause concernant le fait que l’installateur regroupe tout dans chaque projet utilisateur est ce qui empêchera votre futur moi d’y toucher.

Voici quelques autres formes que peuvent prendre ces contraintes avec le temps :

Interdire la catégorie et énumérer les exemples. Une simple interdiction de type « pas d’automatisation du navigateur » laisse à l’agent le soin de décider si une fenêtre d’aperçu est concernée. En énumérant six outils spécifiques qu’il ne doit pas utiliser, on ferme la porte par laquelle il essaierait sinon de trouver un moyen de contourner la règle.

Donnez un nom au comportement, et non seulement à l’outil. La meilleure ligne de ce fichier vise à empêcher une tendance plutôt qu’à donner une instruction : si vous vous surprenez à écrire un outil de scraping ou un générateur de rapports, arrêtez-vous, car vous contournez la tâche au lieu de la réaliser. Les agents compétents contournent les contraintes en créant des outils. C’est cette catégorie qui doit être interdite.

Prévoir des solutions de secours, sinon cela devient une autoroute sans fin. Quelques pages ne peuvent vraiment pas être chargées, c’est pourquoi il existe une série de solutions de repli pour les URL bloquées. Celles-ci ne s’activent que lorsque la méthode habituelle échoue pour cette URL précise. Elles ne gagnent jamais de slot supplémentaire pour un chargement, vérifient la présence d’un outil déjà installé sans en installer un, et limitent la sortie afin qu’un affichage complet de la page ne submerge pas le contexte. Ensuite vient l’arrêt définitif : si l’URL reste inaccessible après avoir épuisé toutes les solutions possibles, c’est terminé. Enregistrez l’événement et passez à autre chose, sans essais supplémentaires, sans outil additionnel, sans idée innovante de dernière minute.

Expliquez en détail pourquoi cette exception n’est pas une faille. Un bref paragraphe dans le fichier indique qu’une requête unique sans interface graphique affichant du texte brut ne viole pas l’interdiction concernant les navigateurs, car cette interdiction vise plutôt l’utilisation d’un navigateur qui laisse des onglets ouverts à être fermés par une personne. Si ce paragraphe est omis, l’exception et l’interdiction semblent entrer en conflit, et un modèle confronté à un tel conflit choisit généralement la lecture qui permet plus de liberté.

Elles échouent en silence, et avec assurance

Deux études ont un jour donné des résultats non seulement acceptables mais excellents : des conclusions claires, des sources réelles, un rapport cohérent. Les deux citaient Reddit comme source principale. Or aucune d’elles n’avait récupéré le moindre élément depuis Reddit.

Ce qui s’est passé, c’est qu’une requête WebSearch restreinte par site:reddit.com a renvoyé dix résultats propres et plausibles provenant d’autres domaines, parmi lesquels un forum communautaire de marché d’artisanat, un site gouvernemental dédié aux petites entreprises et un site de partage de diapositives, sans le moindre problème. Aucun code 403, aucun ensemble vide, aucune alerte. Le filtre de domaine avait été ignoré silencieusement, et rien dans les résultats ne l’indiquait. L’agent disposait donc d’une liste ordonnée de pages utilisables provenant de sources inappropriées, et il a fait ce que tout professionnel sensé ferait avec une telle liste : il les a utilisées et a signalé un succès.

La règle établie ce même jour constitue désormais la base de tout le projet : si une source nommée ne peut pas être atteinte, l’exécution doit le signaler, et elle ne doit en aucun cas continuer en silence avec ce que l’outil a fourni à la place. Un rapport indiquant Reddit comme source principale tout en prétendant un succès provenant de forums de marché est pire qu’un échec total, car personne ne peut le détecter en le lisant.

Une exécution échouée entraîne une nouvelle tentative. Une exécution qui remplace discrètement ses sources entraîne une décision basée sur des éléments que l’on suppose provenir d’une source qui ne l’est pas en réalité. La fenêtre de contexte isolée, c’est précisément cette fonctionnalité, qui empêche de voir ce qui se passe : aucune transcription ne vous parvient, seulement le résumé que l’agent a décidé d’écrire.

Trois solutions permettent de remédier à cela, et aucune d’elles ne consiste à demander simplement à l’agent d’être plus prudent.

Effectuez un test mécanique. Aucune erreur n’a été détectée, donc l’agent n’a vu aucune raison d’inspecter quoi que ce soit. La solution se résume à une phrase ne nécessitant aucun jugement : lorsque une recherche est limitée à un domaine et que aucune des URL obtenues n’en fait partie, considérez cela comme zéro résultat plutôt que comme un ensemble de résultats. Cela ne nécessite aucun outil supplémentaire, aucune requête ou autorisation, car les URLs sont déjà présentes. « Soyez méfiant envers vos sources » ne donne rien à faire à l’agent, tandis que « Vérifiez l’identifiant du hôte par rapport à celui que vous avez filtré » lui donne une tâche concrète.

Considérez l’origine comme un canal de sortie obligatoire doté d’un schéma. C’est là que la structure des résultats cesse d’être un simple ensemble de titres de sections pour devenir un type bien défini. Deux tableaux sont alors liés à leurs noms de clés respectifs.

• unreachable[] contient une entrée par mur, avec pour clés exactement source, url et reason. Il prend en compte à la fois les échecs de récupération définitifs et les substitutions silencieuses.
• sources[] contient une entrée par source qui a réellement fourni une réponse, avec pour clés exactement source, url et fields. Une page qui a été ouverte mais qui ne fournit aucune information n’est pas enregistrée. Une source qui répond avec quatre champs correspond à une seule entrée listant quatre noms, et non à quatre entrées distinctes.

L’appel subtil, qui était erroné au début : la provenance sert à annoter et ne bloque jamais. Si un substitut documenté répond à la question, le champ est considéré comme répondu, et l’entrée unreachable ne fait que consigner que la réponse n’émane pas de la source indiquée. Permettre à un obstacle de faire échouer le champ provoquerait une panne importante précisément dans la situation où une solution de contournement existe.

Chaque échec apporte une leçon précieuse à retenir. La première version de cet agent indiquait à quatre reprises de « le consigner comme inatteignable », sans jamais préciser de champ, d’array ou de slot de sortie. Cette instruction ne menait nulle part. L’agent devait enregistrer quelque chose sans endroit prévu à cet effet, il n’enregistrait donc rien, et rien ne se plaignait. Chaque fois que vous rédigez une instruction pour un sous-agent, assurez-vous que l’action qu’elle décrit a bien une destination. « Rendre compte de X » sans spécifier quel champ correspond à X ne fait rien, mais cela ne pose aucun problème.

Vérifiez depuis l’extérieur de l’agent. Le fait que l’agent respecte son contrat de sortie est déterminé par un script exécuté par la suite, et non par les affirmations de l’agent lui-même. Environ 180 lignes de Python vérifient le JSON par rapport aux champs déclarés, et cela vaut bien plus que n’importe quel insistance dans la demande initiale.

La même idée réapparaît dans les instructions destinées à ceux qui doivent gérer un dépôt ne disposant d’aucune suite de tests. Celles-ci indiquent clairement l’absence de telle suite ; la section « Tests » de la tâche énumère les vérifications qui en tiennent lieu, chacune devant être exécutée et dont les résultats doivent être rapportés de manière précise. Lorsqu’une vérification stipule « cette URL se résout », cela signifie qu’il faut effectivement la télécharger. Une URL qui ne peut pas être vérifiée n’est pas enregistrée dans un fichier ; elle est plutôt signalée comme non vérifiée, accompagnée d’une description de ce qui s’est passé. En effet, un lecteur qui fait confiance à un lien non vérifié perdra son temps à tenter de le charger, ce qui aboutira à une erreur 404 que une simple recherche aurait évitée, ce qui rend une URL non vérifiée encore moins fiable que de ne pas la mentionner du tout.

Les agents affirment facilement avoir effectué une vérification qu’ils n’ont jamais réalisée, car une affirmation crédible et une vérification réelle se lisent de la même manière dans un résumé. Pour chaque vérification importante, précisez l’action concrète qui constitue en réalité son exécution.

Une seule tâche par agent, et les habitudes qui enflent les fichiers

Les meilleurs sous-agents n’ont qu’une seule tâche. Vous objecterez peut-être, car les fichiers cités ci-dessus ne sont pas légers, et celui du chercheur compte jusqu’à 188 lignes. La distinction qui résout ce problème : la tâche est restée une seule phrase tandis que le fichier a grossi. Ce qui s’est accumulé, ce sont des contraintes, des règles de détection et des spécifications de sortie, comme des tissus cicatriciels autour d’un squelette fixe, sans aucune nouvelle responsabilité ajoutée en un an. Les lignes ajoutées parce que quelque chose a mal fonctionné signifient que le fichier accomplit sa fonction. Les lignes ajoutées pour gérer un nouveau type de travail constituent un encombrement, et la solution consiste à diviser l’agent, plutôt qu’à ajouter une nouvelle section.

Toutes les versions surdimensionnées se ressemblent, et chacune a été mise en service à un moment donné. Il y a le « everything-reviewer », qui calcule une moyenne sur cinq critères sans exceller dans aucun d’eux. Il y a l’étiquette « ingénieur senior » sans aucun comportement concret derrière. Il y a l’agent qui reformule votre CLAUDE.md en y ajoutant des coûts de tokens plutôt que des comportements, ainsi que celui qui duplique une compétence jusqu’à ce que les deux versions divergent. Tous partagent la même erreur fondamentale : une tâche devenue trop vaste pour être traitée en une seule phrase.

La question évidente qui se pose ensuite est de savoir ce qui reste réellement en réserve après un an de ce genre de situation.

Les deux qui ont survécu

La plupart des articles sur le sujet vous proposent un organigramme des types d’agents à créer. En réalité, après un an, il ne reste que deux agents, et rien de plus.

Une précision, car la règle propre à l’article s’applique également ici : l’agent de recherche web a débuté en tant que branche d’un projet open source dédié aux compétences de recherche approfondie. Le squelette du contrat de sortie, c’est-à-dire les sections de résumé ainsi que la liste des sources toujours requises, provient intégralement de la version originale. La couche de contrôle ajoutée par-dessus, qui couvre les budgets, les interdictions, le schéma de provenance et l’échelle d’escalade, est originale et représente la moitié du nombre total de lignes. Tout ce qui concerne les aspects négatifs dans cet article se rapporte à cette moitié.

L’agent de recherche web effectue des recherches limitées sur le web et restitue les résultats accompagnés de leurs sources. Il est installé aujourd’hui dans une douzaine de dépôts, parmi lesquels un site de blog statique, quelques pipelines et plusieurs projets de recherche. Tous les éléments concernant les budgets, les interdictions et les substitutions silencieuses proviennent de l’historique des modifications de ce seul fichier.

Le metteur en œuvre exécute une file de tâches entièrement définie tandis que la planification se poursuit ailleurs. Quatre projets en disposent. Ceux-ci ont fourni des enseignements sur les contrats de transfert, l’état de fonctionnement et les aspects économiques de la délégation.

Le reste des éléments présents dans les dossiers des agents est arrivé accompagné de frameworks, et il fonctionne comme un tiroir à bric-à-brac doté d’une meilleure identité visuelle qu’un véritable tiroir. Les spécialistes jugés nécessaires (un enquêteur pour les tests aléatoires, un agent chargé de la mise en forme des communications publiques, un rédacteur de documents, un agent chargé de l’orientation du codebase pour les projets abandonnés) semblaient tous raisonnables, mais presque aucun n’a été développé. Ceux qui restent ne sont pas nécessairement ceux qui semblaient utiles. Ce sont plutôt ceux où le même problème spécifique, lié à l’exécution du travail dans le mauvais contexte ou par la mauvaise personne, continuait de se reproduire.

Omettez le organigramme. Concentrez-vous plutôt sur les tâches que vous aimeriez voir effectuées ailleurs, et conservez-les.

Modèle d’abord, puis spécialisation

Le principe qui permet de rendre les deuxièmes, troisièmes et quatrièmes exécutants moins coûteux est le suivant : l’agent est généré à partir d’un modèle, puis adapté là où le projet diffère.

La compétence en planification fournit un modèle d’exécutant contenant des espaces réservés, et lors de la mise en place d’un nouveau projet, l’agent, le document de planification et le document de tâches sont créés ensemble. Ce qui en résulte, c’est un protocole : lire le contrat, suivre les étapes dans l’ordre, ignorer tout ce qui est bloqué, maintenir l’état d’avancement à jour, rester dans les limites du périmètre défini et faire un rapport à la fin. Ces règles ne changent jamais d’un projet à l’autre, car elles décrivent la délégation elle-même et ne concernent en rien votre code.

Par la suite, chaque copie développe sa propre section pour sa propre surface d’échec, et placer deux d’elles côte à côte est instructif. Le modèle indique à l’agent de maintenir l’ensemble de tests en état « vert ». Un projet ne dispose d’aucun ensemble de tests du tout. Il s’agit d’un répertoire de prompts, et son seul fichier exécutable est le validateur. Son concepteur affirme donc quelque chose de complètement différent : le répertoire contient des prompts et des données plutôt que du code ; modifier un fichier, c’est modifier un prompt ; le choix des mots, l’ordre et l’emphase constituent l’implémentation ; et une réécriture qui se lit mieux tout en supprimant une contrainte stricte constitue une régression qui ne sera signalée par rien, puisqu’il n’existe ni build ni tests.

La copie d’un autre projet a reçu l’instruction d’étudier les décisions indiquées dans le fichier PLAN.md par une tâche avant de coder, ainsi qu’une ligne pour faire un rapport en cas de besoin d’intervention d’Opus ou d’un humain. Le protocole est le même, mais les risques diffèrent.

C’est la distinction à retenir. La partie réutilisable d’un sous-agent est son protocole, tandis que sa partie spécifique au projet est sa surface d’échec. Modélisez la première, rédigez la seconde à la main, et évitez de tenter de faire en sorte qu’un seul fichier couvre les deux.

Dirigez l’agent vers les connaissances sans les coller directement

C’est ici que les compétences et les sous-agents interagissent, et l’idée est devenue beaucoup plus précise dès qu’un véritable processus en a dépendu.

Mon conseil précédent aurait été de nommer la compétence pertinente à l’intérieur du corps de l’agent. Une approche encore plus efficace consiste à être plus strict : l’agent lit les connaissances en temps de exécution avant de pouvoir agir, et le prompt explique la raison.

L’agent de recherche ne peut effectuer aucune recherche tant qu’il n’a pas lu un tableau de routage stocké au sein d’une compétence. L’instruction est indiquée comme obligatoire et stipule : avant toute recherche ou récupération, lire le tableau correspondant au premier chemin disponible ; ne pas l’ignorer ; ne pas se fier à la mémoire, car les modules changent tandis que la demande reste identique : celui que l’on se souvient avoir existé peut avoir disparu, et celui dont on a besoin n’existe peut-être pas encore.

Cette remarque concernant le changement de la liste alors que la demande reste inchangée constitue la justification complète de ce schéma. Les connaissances (quelles sources répondent à quels types de questions, comment interroger chacune d’elles, ce qui est connu comme étant bloqué) évoluent chaque mois, tandis que la méthode reste fixe. En intégrant une liste de sources dans le corps de l’agent, chaque nouvelle source oblige à modifier une demande qui, sinon, resterait inchangée, ce qui amène l’agent à se référer avec confiance à un module supprimé dès le mois de mars.

Deux facteurs mécaniques se sont avérés plus importants que prévu.

Les candidats par ordre, plutôt qu’un seul chemin. L’agent fonctionne dans des projets organisés différemment, sur deux machines sous des noms d’utilisateur différents, configurés par des installateurs distincts. L’instruction énumère donc les emplacements des candidats dans l’ordre et indique de prendre le premier qui existe, en privilégiant les copies locales au projet par rapport à celles au niveau de l’utilisateur. Si l’on définit un chemin fixe, tout ne fonctionne que sur une seule machine.

Les noms littéraux relient les différentes couches, mais rien ne les vérifie. Le design se compose de trois niveaux : les compétences coordonnent, un agent effectue le travail, et les modules de données stockent les connaissances. Il n’existe aucune importation nulle part. Une compétence déclenche l’agent en utilisant son nom enregistré précis, tandis que l’agent trouve les modules via leur chemin. Cela donne au dépôt sa phrase la plus banale mais aussi la plus dangereuse, un rappel de ne pas renommer l’agent de recherche web puisque les utilisateurs existants l’appellent directement.

Le nom d’un agent fonctionne comme une API publique, sans que aucun outil ne le précise : pas de compilateur, pas de test, pas d’avertissement. Un renomage ressemble à un commit ordinaire, mais il perturbe tous les appels provenant de tous les dépôts ayant installé l’agent, et la découverte de ce problème a lieu la prochaine fois que vous demandez une recherche, avec pour réponse un agent généraliste.

Où se trouvent les fichiers : personnels, de projet, emballés

Il y a trois niveaux, et c’est au troisième que vivent tous les agents réels.

• Personnel (~/.claude/agents/) est destiné aux spécialistes généraux nécessaires dans chaque projet. Considérez-le comme l’atelier où il est normal de casser des choses.
• Projet (.claude/agents/, commité) est réservé aux spécialistes utiles uniquement dans une base de code donnée, comme un implémentateur conscient que ce projet manque de tests. En le commitant, il restera disponible dès votre retour, même quatre mois plus tard si le projet vous est sorti de l’esprit.
• Emballé (installé par un gestionnaire de paquets et lié à un commit) fait d’un agent une dépendance. C’est le niveau dont personne ne se rend compte de la nécessité avant que cet agent ne se retrouve dans une douzaine de dépôts, avec treize versions qui s’éloignent les unes des autres.

Le troisième niveau modifie quelques éléments, et il est préférable de les connaître avant d’y arriver.

Associez l’agent aux compétences qui le déclenchent. Le paquet regroupe les deux en une seule unité, pour une raison simple : les compétences installées sans leurs agents créent un flux qui échoue dès la première utilisation. Une compétence qui tente d’appeler par nom un agent manquant entraîne une installation défectueuse, avec au mieux un message d’erreur clair. Ils forment une seule unité car ils relèvent du même contrat.

Découvrez ce que fait votre installateur avec les fichiers. Ce paquet s’installe via APM de Microsoft, qui transforme chaque fichier .md situé dans un répertoire agents/ en un agent de niveau supérieur distinct. Cette configuration par défaut est logique, mais elle présente tout de même des inconvénients. Si vous placez un fichier de données dans cette structure, chaque projet consommateur obtient un agent enregistré fictif. En revanche, si vous créez un agent spécifique à un projet, celui-ci s’installe dans les dépôts de tous les projets. C’est pour cette raison que les modules de stratégie de recherche se trouvent dans le répertoire skills/ et non dans le dossier agents/ où ils sembleraient devoir être : dans agents/, ils perdraient leur structure lors de l’installation et enregistreraient cinq agents fantômes par projet consommateur.

Fixez un commit, et n’oubliez pas que les consommateurs sont en retard. Les consommateurs dépendent d’un SHA, donc une correction n’est disponible pour personne tant que le fix n’est pas appliqué et que l’installation n’est pas relancée. Écrire une correction ne signifie pas pour autant la déployer. Cela semble évident sur la page, mais c’est tout le contraire à 23 heures, lorsque le bug corrigé la semaine dernière réapparaît.

Néanmoins, procédez à des prunings. Un dossier rempli d’agents chevauchants et presque oubliés génère du bruit plutôt que des outils utiles. Fusionnez ceux qui ont été intégrés dans la même tâche. Supprimez celui qui n’a pas été exécuté depuis des mois, car l’historique Git le conservera si la suppression s’avère erronée. Ce sont également de bons conseils de vie, mais ils sont ignorés face au véritable bazar qui règne chez soi.

La même idée dans d’autres outils

Claude Code n’est pas le seul outil adapté à cela. Si vous alternez entre différents outils, ces principes s’appliquent même lorsque les formats de fichiers diffèrent.

GitHub Copilot et VS Code appellent ces éléments agents personnalisés, stockés sous forme de fichiers .agent.md, généralement dans le répertoire .github/agents/, avec la possibilité d’utiliser une bibliothèque personnelle dans le répertoire de l’utilisateur. Le frontmatter comporte plus de champs que celui de Claude : en plus du name, du description et des tools précédents, on trouve argument-hint, model, user-invocable, disable-model-invocation et, ce qui est le mieux, handoffs. Un agent terminé peut afficher un bouton permettant de transférer le travail à un autre agent, avec la prochaine instruction déjà pré remplie, ce qui permet de planifier, de mettre en œuvre et de réviser les étapes les unes après les autres sans que tout ne se mélange en un seul agent confus. C’est un piège si l’on consulte des exemples anciens : l’ancien champ infer a été divisé en deux champs distincts, user-invocable et disable-model-invocation ; un changement qui semble logique avec le recul mais qui est déroutant au début.

On affirme également que VS Code détecte les fichiers .claude/agents/ et traduit les noms des outils, permettant ainsi à un agent de gérer les deux outils sans frais supplémentaires. Cela est partiellement vrai, mais cela peut induire en erreur. Les vocabulaires des outils ne correspondent pas, et une instruction interdisant les outils par leur nom, comme le font tous les agents matures ici, n’est pas transmise intacte grâce à la traduction automatique.

Ce qui est véritablement fourni, c’est une instruction canonique unique accompagnée d’un petit module natif pour chaque outil. Tout l’agent côté Copilot présent dans le package ne compte que onze lignes :

---
name: Web Research Writer
description: "Use for bounded web research that must read a local schema, search and fetch current sources, write one designated result file, and validate it with a local command."
tools: [read, search, web, edit, execute]
user-invocable: false
disable-model-invocation: false
---

Load the installed canonical research prompt from the first existing candidate:

1. `.github/agents/web-search-agent.agent.md`
2. `.claude/agents/web-search-agent.md`

Follow its search budgets, module routing, source standards, tool discipline, output, and validation rules. Ignore that file's incompatible `tools` frontmatter; this wrapper's Copilot-native tool categories govern this session.

C’est là tout le schéma : le frontmatter natif permet à l’hôte d’enregistrer correctement l’agent, une série de chemins permet de localiser le prompt réel, et une phrase concise indique quel vocabulaire d’outil a la priorité. Les 188 lignes de comportement accumulé se trouvent dans un seul fichier, et le deuxième outil reçoit un pointeur plutôt qu’une copie indépendante. Deux copies d’un prompt créent deux prompts distincts, et dès qu’un correctif de bug est appliqué à l’un sans l’autre, ils commencent à se présenter comme un seul agent.

Le README du projet souligne un problème : si l’on dirige le chargeur vers .github/agents/, le prompt canonique s’enregistre en tant qu’agent à part entière, ce qui peut entraîner des noms dupliqués chez Copilot — le shim « Web Research Writer » et, en dessous, le fichier canonique. Il faut choisir un emplacement unique par outil, ou conserver le fichier canonique sous .claude/agents/, où la détection automatique de Copilot l’ignore.

Tout le reste, y compris Cursor et Windsurf, tend vers le même objectif sous des intitulés tels que règles, modes ou agents. Les détails évoluent si souvent qu’il vaut mieux vous renvoyer à la documentation actuelle de chaque outil plutôt que d’affirmer avec certitude ce qui a changé le mois dernier. L’idée de base reste inchangée : un fichier réutilisable qui définit un rôle et qui est invoqué délibérément. Apprenez cela une fois, et il ne restera plus qu’à trouver où chaque outil cache son dossier.

Comment construire vraiment de bons outils

Chaque sous-agent ici a commencé par être trop général. Il y avait un « reviewer » qui examinait tout, un « planner » qui n’avait aucune opinion sur l’apparence d’un plan, et un « investigator » qui abordait chaque bug comme le précédent. Ce n’est pas un échec. C’est le point de départ.

La partie utile, celle qui aurait été d’une aide il y a un an, n’est pas « itérer ». Tout le monde parle d’itération. C’est de cela que sont composées les itérations.

Rélisez les fichiers des agents cités ci-dessus et remarquez où se trouvent les mots. Un paragraphe pour le rôle. Une page de contraintes. Un schéma avec les noms des clés indiqués. Une règle mécanique pour la détection. Un budget numérique accompagné d’une clause interdisant toute manipulation. Une remarque indiquant que les paiements effectués doivent être divulgués. Une interdiction expliquant ce que fait l’installateur avec les éléments non conformes. Presque tout y consigne un élément spécifique qui a mal tourné à un moment donné.

Après une performance décevante, la question pertinente n’est pas de savoir comment formuler mieux ce rôle. Il faut plutôt se demander ce que l’agent a exactement fait, quelle partie du fichier le permettait, et quelle règle l’exclura la prochaine fois. Cent onglets de navigateur. Dix résultats hors domaine sans erreur. Une instruction ne sachant où placer sa réponse. Une vérification revendiquée mais jamais effectuée. Chacun de ces éléments devient une ligne, et cette ligne survit à la session qui l’a formée, ce qui est justement l’objectif de la conserver dans un fichier.

Le même test s’applique avant de conserver un agent, tout comme avant de conserver une compétence : son travail peut-il être décrit en une phrase ? Si ce n’est pas le cas, il est trop vague, et deux agents plus petits se trouvent alors regroupés sous le même nom. Pour juger s’il est réellement bon, il faut un autre test : lorsqu’il commet une erreur, pouvez-vous identifier la ligne qui l’a conduit à cela ? Si ce n’est pas possible, il n’y a pas encore de spécialiste, seulement une entité dotée de métadonnées.

En les combinant, vous cessez de devoir solliciter sans cesse un généraliste très compétent. Vous conservez ainsi un petit groupe de spécialistes qui comprennent déjà votre domaine ainsi que leurs propres tâches. Pour une personne qui souhaite accomplir plus que ce qu’une seule personne ne devrait raisonnablement faire, c’est ce qui se rapproche le plus de l’embauche d’aide sans avoir à embaucher réellement.

Regardez les tâches que vous aimeriez voir effectuées ailleurs : il s’agit d’un sous-agent qui attend encore d’être activé. Et la dernière fois qu’un sous-agent vous a déçu, c’était parce qu’une ligne de code attendait encore d’être écrite.

Lectures complémentaires

• Notes pratiques : Un guide pas à pas pour développer votre agent personnel — Guide opérationnel des Notes pratiques : Un guide pas à pas pour développer votre agent personnel : contrats, vérifications et emplacements de code prêts à l’emploi pour les équipes utilisant ce modèle.
• Notes pratiques : Qwen3.8–27B en tant que nouvel agent de codage de prédilection avec SGLang/vLLM et — Guide opérationnel des Notes pratiques : Qwen3.8–27B en tant que nouvel agent de codage de prédilection avec SGLang/vLLM et : contrats, vérifications et emplacements de code prêts à l’emploi pour les équipes utilisant ce modèle.

Le harnais est le produit : un guide pratique sur les harnais en IA agente — Découvrez ce qu’est un harnais d’agent et ses sept composants, allant des outils et du contexte aux garde-fous et aux méthodes d’évaluation, ainsi que les sous-agents, les modes de défaillance et les frameworks à connaître.