Comment créer des sous-agents de code Claude personnalisés (Guide de configuration)

Il y a une limite que l'on atteint avec toute session de codage IA unique : la fenêtre de contexte. Remplissez une conversation avec une refactorisation tentaculaire, trois séries de résultats de tests et une revue de code, et l'agent commence à perdre le fil. Les sous-agents Claude Code sont la solution. Au lieu d'un seul agent jonglant avec tout dans un seul contexte, vous créez des travailleurs ciblés, chacun avec sa propre fenêtre de contexte, ses propres instructions et ses propres permissions d'outils. Ils effectuent une seule tâche, renvoient un résultat et maintiennent le fil principal propre.

Ceci est le guide de construction pratique. Comment créer un sous-agent personnalisé sous forme de fichier de configuration, ce que chaque champ d'en-tête YAML fait, comment Claude décide de lui déléguer, et comment configurer une installation pratique où un agent révise le code pendant qu'un autre écrit des tests en parallèle. Si vous souhaitez d'abord une vue d'ensemble conceptuelle, notre article sur ce que sont les sous-agents Claude Code et pourquoi ils sont importants couvre les bases. Ici, nous nous concentrons sur leur construction et sur l'aspect des tests d'API qui transforme un sous-agent de test en une étape de vérification fiable.

TL;DR

Vous créez un sous-agent Claude Code en écrivant un fichier Markdown dans .claude/agents/ avec un en-tête YAML : un name, une description qui indique à Claude quand déléguer, une tools (liste d'autorisation) facultative et un model facultatif. Le corps du fichier devient l'invite système du sous-agent. Chaque sous-agent s'exécute dans sa propre fenêtre de contexte avec ses propres outils, ce qui vous offre une isolation de contexte, un parallélisme et une spécialisation. Claude délègue automatiquement en fonction de la description, ou vous invoquez un sous-agent par son nom. La référence officielle est la documentation des sous-agents Claude Code.

Les sous-agents en 60 secondes

Un sous-agent est une instance d'agent distincte à laquelle l'agent principal Claude Code confie une tâche. L'agent principal est l'ingénieur en chef ; les sous-agents sont les spécialistes qu'il sollicite. Le spécialiste travaille dans sa propre conversation, avec sa propre fenêtre de contexte et son invite système, puis ne renvoie que le résultat. Trois propriétés les rendent dignes d'être configurés :

• Sa propre fenêtre de contexte. Un sous-agent démarre à neuf avec seulement la tâche qui lui est donnée, de sorte que le fil principal ne se remplit jamais de son travail intermédiaire.
• Une invite système personnalisée. Vous façonnez son comportement : un réviseur qui chasse les failles de sécurité, un rédacteur de tests qui suit vos conventions.
• Des outils configurables. Vous n'accordez à chaque sous-agent que les outils dont il a besoin, de sorte qu'un réviseur ne peut pas écrire et qu'un exécuteur de tests n'obtient qu'un accès shell suffisant.

C'est la base conceptuelle ; l'aperçu conceptuel va plus loin sur le pourquoi. Le reste de ce guide concerne leur construction, ce qui est le même principe que celui derrière l'architecture du harnais d'agent Claude Code appliqué au niveau des tâches individuelles.

Pourquoi utiliser des sous-agents

Trois raisons, et elles se combinent.

Isolation du contexte. Une longue session se dégrade à mesure que la fenêtre de contexte se remplit. Chaque lecture de fichier, chaque exécution de test, chaque digression consomme du budget et dilue la concentration. Déléguer une tâche importante à un sous-agent conserve tout ce travail dans le contexte du sous-agent, et non dans le contexte principal. L'agent principal reçoit un résumé propre au lieu de 50 000 jetons de bruit intermédiaire. Cette isolation est également un levier de coût, car vous ne traînez pas un contexte surchargé à chaque tour. Nos notes sur la réduction des coûts des jetons d'agent abordent les aspects économiques.

Parallélisme. Les tâches indépendantes n'ont pas besoin de s'exécuter l'une après l'autre. Un agent principal peut envoyer plusieurs sous-agents à la fois : réviser ce module tout en testant celui-ci et en documentant un troisième. Le temps réel de traitement est réduit à la tâche la plus lente au lieu de la somme. Les flux de travail dynamiques de Claude Code poussent cela à sa limite, déployant des centaines de sous-agents parallèles à partir d'une seule session.

Spécialisation. Un agent généraliste est bon partout et excellent nulle part. Un sous-agent avec une invite système précise et les bons outils est excellent dans une chose. Un réviseur incité à être critique trouve plus de bogues qu'un généraliste jetant un coup d'œil au diff. Un rédacteur de tests qui connaît votre style d'assertion produit des tests que vous garderez réellement. Vous construisez une petite équipe de spécialistes au lieu d'un généraliste surchargé.

Comment créer un sous-agent personnalisé

Les sous-agents sont de simples fichiers Markdown. Placez ceux au niveau du projet dans .claude/agents/ et ceux personnels dans ~/.claude/agents/. Chaque fichier contient un en-tête YAML et un corps qui devient l'invite système du sous-agent.

Voici un réviseur de code :

---
name: code-reviewer
description: Reviews code changes for bugs, security issues, and convention violations. Use after writing or editing code.
tools: Read, Grep, Glob
model: sonnet
---

You are a senior code reviewer. When given a diff or a set of files:

1. Look for correctness bugs, security holes, and missed edge cases.
2. Check that the code matches the project's existing conventions.
3. Report only high-confidence issues, ranked by severity.

Be specific. Cite file and line. Do not rubber-stamp.

Les champs de l'en-tête YAML :

• name — l'identifiant que vous utilisez pour l'invoquer.
• description — c'est le plus important. Claude le lit pour décider quand déléguer automatiquement. Rédigez-le comme un déclencheur clair ("Utiliser après avoir écrit du code"), et non comme une étiquette vague.
• tools — la liste d'autorisation. Omettez-le pour hériter des outils de l'agent principal, ou listez des outils spécifiques pour les restreindre. Un réviseur qui ne peut pas écrire de code ne peut pas le modifier accidentellement.
• model — épinglez éventuellement un modèle. Utilisez un modèle moins cher et plus rapide pour les sous-agents mécaniques et un modèle plus puissant pour les raisonnements complexes.

Le corps est l'invite système. C'est là que réside la spécialisation, alors rédigez-le comme vous brieferiez un nouvel employé : quoi faire, quoi prioriser, quoi éviter. L'associer à un fichier de projet design.md ou AGENTS.md donne au sous-agent vos conventions sans les répéter dans chaque fichier.

Comment invoquer des sous-agents

Il y a deux façons d'exécuter un sous-agent.

Délégation automatique. Claude lit le champ description de chaque sous-agent disponible et délègue de lui-même lorsqu'une tâche correspond. Terminez l'édition d'un fichier et l'agent principal peut confier le diff à votre code-reviewer sans qu'on le lui dise, car la description dit "utiliser après avoir écrit du code". De bonnes descriptions favorisent une bonne délégation.

Invocation explicite. Vous pouvez également le nommer directement : "utiliser le sous-agent code-reviewer sur les modifications du module des commandes." C'est ainsi que vous forcez un spécialiste spécifique lorsque vous ne voulez pas laisser la délégation au hasard.

Dans les deux cas, le sous-agent s'exécute dans son propre contexte, effectue le travail et renvoie un résultat au fil principal. Vous voyez le transfert se produire et vous pouvez configurer le niveau de détail affiché. Pour enchaîner les sous-agents en séquences déterministes et reproductibles, les commandes slash et le SDK vous donnent plus de contrôle que l'invitation ad hoc ; l'aperçu de Claude Code couvre la surface de configuration.

Sous-agents vs le SDK d'agent vs les flux de travail dynamiques

Ces éléments se chevauchent, voici donc quand chacun s'adapte.

Les sous-agents sont l'option conversationnelle en session : vous travaillez dans Claude Code et vous voulez un ou deux spécialistes. Lorsque vous avez besoin d'une boucle programmatique qui s'exécute selon un calendrier sans présence humaine, vous passez au SDK d'agent Claude et écrivez vous-même l'orchestration. Si vous hésitez entre une option hébergée et le développement de votre propre solution, notre comparaison des agents gérés vs le SDK d'agent détaille les compromis. Les trois ne sont pas tant des concurrents que des échelons sur une échelle allant de l'interactif au entièrement automatisé.

Un exemple pratique : revue parallèle et écriture de tests

Mettez tout cela ensemble. Supposons que l'agent principal vient d'implémenter un nouveau point de terminaison de commande. Vous voulez qu'il soit examiné et testé, et il n'y a aucune raison que cela se fasse séquentiellement.

Définissez deux sous-agents. Le code-reviewer ci-dessus, plus un rédacteur de tests :

---
name: api-test-writer
description: Writes API test cases for new or changed endpoints. Use after an endpoint is implemented.
tools: Read, Grep, Write, Bash
model: sonnet
---

You write API tests against the project's OpenAPI spec.

1. Read the spec and the endpoint implementation.
2. Write tests covering success, validation errors, and auth.
3. Assert status codes and validate response bodies against the schema.
4. Run the suite and report pass/fail with reasons.

Maintenant, l'agent principal envoie les deux à la fois : le réviseur lit le diff pendant que le rédacteur de tests lit la spécification et écrit la couverture. Deux spécialistes, deux contextes isolés, exécutés en parallèle. Le fil principal reste propre et reçoit deux résumés : un rapport de révision et un résultat de test.

Ce résultat de test est la partie qui rend cela digne de confiance. Un sous-agent qui exécute votre suite d'API est une porte de vérification, la vérification déterministe qui indique si le point de terminaison fonctionne réellement plutôt que s'il semble terminé. C'est l'idée fondamentale des boucles d'agents de codage : la confiance de l'agent lui-même ne compte pas, c'est le verdict de la porte qui compte. Connectez le sous-agent de test à une plateforme de test d'API réelle et le retour d'information sera plus précis. Les équipes utilisant Apidog dirigent le sous-agent vers un scénario de test Apidog afin que chaque réponse soit validée par schéma, et acheminent les appels de points de terminaison en direct de l'agent via le débogueur d'agent IA Apidog afin qu'il inspecte les requêtes comme le ferait un testeur humain. Reprenez cette même configuration, insérez-la dans une boucle, et vous obtenez le flux de travail non supervisé que nous avons construit dans les flux de travail Claude qui s'exécutent sans vous. Téléchargez Apidog si vous voulez que la porte de test soit sensible aux schémas dès le départ.

Bonnes pratiques

Quelques habitudes maintiennent les sous-agents utiles au lieu de chaotiques.

• Une responsabilité par sous-agent. Un réviseur révise. Un testeur teste. Ne construisez pas un sous-agent "tout-en-un" ; ce n'est qu'un agent principal avec des étapes supplémentaires.
• Rédigez des descriptions pour la délégation. Le champ description est la façon dont Claude décide d'appeler votre sous-agent. Faites-en un déclencheur clair, pas un titre. "Utiliser après avoir modifié du code pour rechercher des bogues" vaut mieux que "Réviseur de code".
• Accorder le moindre privilège. Ne listez que les outils dont chaque sous-agent a besoin. Un réviseur sans accès en écriture ne peut pas modifier ce qu'il révise. C'est plus important lorsque les exécutions sont sans surveillance.
• Épinglez le bon modèle par tâche. Les sous-agents mécaniques peuvent s'exécuter sur un modèle plus rapide et moins cher. Réservez le modèle le plus puissant aux sous-agents effectuant des raisonnements complexes. Cela contrôle à la fois la vitesse et le coût.
• Retournez des résultats structurés. Demandez aux sous-agents de rapporter des informations sous une forme cohérente (un verdict, une liste de problèmes, un succès/échec). Un résultat structuré est plus facile à exploiter pour l'agent principal et pour vous.
• Ne pas imbriquer à l'excès. Des sous-agents appelant des sous-agents appelant des sous-agents deviennent difficiles à suivre et coûteux. Gardez la hiérarchie peu profonde.

Ces éléments reflètent les schémas de câblage que nous avons abordés dans le câblage d'outils de flux de travail agentiques, et ils sont valables que vous ayez deux ou vingt sous-agents.

Quand utiliser les sous-agents (et quand ne pas le faire)

Les sous-agents sont un outil, pas un paramètre par défaut. Savoir quand les ignorer permet de maintenir votre configuration rapide et économique.

Utilisez un sous-agent lorsqu'une tâche est **délimitée, indépendante et bruyante**. Une revue de code est délimitée (elle a une fin claire), indépendante (elle n'a pas besoin de l'état d'exécution du fil principal) et bruyante (elle génère beaucoup de lecture intermédiaire que vous ne voulez pas encombrer le contexte principal). Il en va de même pour l'écriture d'une suite de tests, la reproduction d'un bug ou l'audit d'un module pour des problèmes de sécurité. Ce sont des délégations parfaites : isoler le travail, obtenir un verdict.

Évitez le sous-agent lorsque la tâche est **petite, étroitement couplée ou séquentielle avec le travail principal**. Renommer une variable, corriger un bug d'une ligne, ou toute tâche pour laquelle l'agent principal a déjà le contexte nécessaire en vue ne bénéficie pas d'un transfert. La création d'un sous-agent n'ajoute alors que de la latence et un aller-retour de contexte sans gain. Si l'agent principal devait expliquer la moitié de la conversation pour briefer le sous-agent, gardez-le dans le fil principal.

La règle générale : déléguez le travail suffisamment autonome pour être décrit en un paragraphe et suffisamment précieux pour être exécuté en parallèle. Un nouveau point de terminaison à réviser et à tester convient. Une faute de frappe ne convient pas. À mesure que vous passez à de nombreux sous-agents concurrents, les modèles d'orchestration des flux de travail dynamiques prennent le relais, mais le même jugement s'applique : parallélisez ce qui est indépendant, gardez le travail couplé ensemble.

Erreurs courantes

• Descriptions vagues. Si la description est une étiquette, la délégation automatique ne se déclenchera pas quand vous l'attendez. Rédigez-la comme un déclencheur d'utilisation.
• Un sous-agent surchargé. Entasser toutes les tâches dans un seul sous-agent tue le bénéfice de la spécialisation. Divisez par responsabilité.
• Hériter de tous les outils par défaut. Laisser tools non défini donne à un sous-agent tout ce que l'agent principal possède. C'est bien pour un travail de confiance, risqué pour tout ce qui est automatisé. Listez délibérément les outils autorisés.
• Pas de sous-agent de vérification. Une configuration de révision et de construction sans porte de test livre du code qui semble correct et qui se brise aux limites. Incluez toujours un sous-agent qui exécute réellement les tests.
• Traiter les sous-agents comme le SDK. Les sous-agents sont déclenchés par le modèle et en session. Si vous avez besoin d'un flux de contrôle déterministe et planifié, c'est le travail du SDK d'agent, pas un tas de sous-agents.

Faites cela correctement et une poignée de sous-agents bien définis transformera Claude Code d'un assistant unique très occupé en une petite équipe concentrée. L'article d'Anthropic Building Effective Agents présente le cas plus large : la structure autour du modèle l'emporte sur une invite plus grande.

Questions fréquemment posées

Qu'est-ce qu'un sous-agent Claude Code ? C'est une instance d'agent distincte à laquelle l'agent principal Claude Code délègue des tâches. Chaque sous-agent a sa propre fenêtre de contexte, une invite système personnalisée et un ensemble d'outils configurable. Il effectue une tâche ciblée et renvoie le résultat, gardant la conversation principale propre et vous permettant d'exécuter des spécialistes en parallèle.

Comment créer un sous-agent Claude Code ? Créez un fichier Markdown dans .claude/agents/ (projet) ou ~/.claude/agents/ (personnel). Ajoutez un en-tête YAML avec name, description, tools facultatifs et model facultatif, puis écrivez l'invite système dans le corps. La description indique à Claude quand déléguer automatiquement.

Comment Claude décide-t-il quel sous-agent utiliser ? Il lit le champ description de chaque sous-agent disponible et délègue automatiquement lorsqu'une tâche correspond. Vous pouvez également en invoquer un explicitement par son nom, comme "utiliser le sous-agent code-reviewer". Des descriptions claires de type déclencheur rendent la délégation automatique fiable.

Quelle est la différence entre les sous-agents et le SDK d'agent Claude ? Les sous-agents sont en session et déclenchés par le modèle : vous travaillez dans Claude Code et il fait appel à des spécialistes. Le SDK d'agent est programmatique, où vous écrivez le flux de contrôle dans le code pour des exécutions déterministes ou sans surveillance. Utilisez les sous-agents pour la spécialisation interactive, le SDK pour les boucles planifiées.

Les sous-agents peuvent-ils s'exécuter en parallèle ? Oui. L'agent principal peut envoyer plusieurs sous-agents à la fois pour des tâches indépendantes, de sorte que la révision, les tests et la documentation se déroulent ensemble plutôt qu'en séquence. Pour un déploiement à grande échelle, les flux de travail dynamiques de Claude Code étendent cela à de nombreux sous-agents parallèles en une seule session.

Comment les sous-agents aident-ils avec les tests d'API ? Définissez un sous-agent qui écrit et exécute vos tests d'API par rapport à la spécification OpenAPI. Il devient une porte de vérification qui vérifie si un point de terminaison fonctionne réellement, et pas seulement s'il semble terminé. Le diriger vers une plateforme comme Apidog rend le feedback conscient du schéma, de sorte que chaque réponse est validée par rapport au contrat.

La conclusion

Les sous-agents Claude Code résolvent le problème qu'une seule fenêtre de contexte ne peut pas tout contenir. En donnant à chaque tâche son propre contexte, ses instructions et ses outils, vous échangez un agent surchargé contre une petite équipe de spécialistes qui travaillent en parallèle et rapportent des résultats propres. La configuration n'est qu'un fichier Markdown, et les avantages sont la concentration, la rapidité et la capacité de confier le bon modèle à la bonne tâche.

Commencez par deux : un réviseur et un testeur. Rédigez des descriptions précises afin que Claude délègue de lui-même, n'accordez à chacun que les outils dont il a besoin, et faites du testeur une véritable porte de vérification en le dirigeant vers votre suite d'API. Pour tout ce qui touche aux points de terminaison, Apidog donne à cette porte un schéma à vérifier ; téléchargez-le et laissez un sous-agent de test prouver que votre code fonctionne avant même de lire le diff.