DEV Community

Cover image for Comment créer des sous-agents de code Claude personnalisés (Guide de configuration)
Antoine Laurent
Antoine Laurent

Posted on • Originally published at apidog.com

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

Il y a une limite que l’on atteint vite avec une session de codage IA unique : la fenêtre de contexte. Ajoutez une refactorisation large, plusieurs sorties de tests et une revue de code, et l’agent commence à perdre le fil. Les sous-agents Claude Code résolvent ce problème en séparant le travail : chaque sous-agent possède son propre contexte, ses propres instructions et ses propres permissions d’outils. Il exécute une tâche ciblée, renvoie un résultat, et garde le fil principal lisible.

Essayez Apidog aujourd’hui

Ce guide montre comment créer un sous-agent personnalisé avec un fichier de configuration, comment écrire l’en-tête YAML, comment Claude décide de déléguer, et comment mettre en place un workflow où un agent révise le code pendant qu’un autre écrit et exécute des tests d’API. Pour la vue d’ensemble conceptuelle, consultez ce que sont les sous-agents Claude Code et pourquoi ils sont importants. Ici, on se concentre sur l’implémentation.

TL;DR

Un sous-agent Claude Code est un fichier Markdown placé dans .claude/agents/ ou ~/.claude/agents/.

Il contient :

  • un name ;
  • une description utilisée par Claude pour décider quand déléguer ;
  • une liste tools facultative pour limiter les outils disponibles ;
  • un model facultatif ;
  • un corps Markdown qui devient l’invite système du sous-agent.

Chaque sous-agent s’exécute dans sa propre fenêtre de contexte. Vous pouvez laisser Claude le déclencher automatiquement via sa description, ou l’appeler explicitement par son nom.

Référence officielle : 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 délègue une tâche.

Pensez à cette organisation :

  • l’agent principal pilote le travail ;
  • les sous-agents exécutent des tâches spécialisées ;
  • chaque sous-agent renvoie uniquement son résultat final.

Trois propriétés les rendent utiles en pratique :

  • Contexte isolé : le sous-agent lit les fichiers, exécute ses recherches et produit son analyse sans polluer le fil principal.
  • Invite système dédiée : vous pouvez définir un comportement précis, par exemple “réviseur sécurité” ou “auteur de tests API”.
  • Outils limités : vous donnez uniquement les permissions nécessaires à chaque sous-agent.

L’aperçu conceptuel explique davantage le “pourquoi”. Ce guide applique le même principe que l’architecture du harnais d’agent Claude Code, mais au niveau des tâches individuelles.

Pourquoi utiliser des sous-agents

1. Isoler le contexte

Une session longue devient moins efficace quand le contexte se remplit :

  • sorties de tests ;
  • fichiers lus ;
  • erreurs intermédiaires ;
  • discussions de conception ;
  • diffs successifs.

En déléguant une tâche à un sous-agent, vous gardez ce bruit hors du fil principal. L’agent principal reçoit un résumé exploitable au lieu de milliers de tokens intermédiaires.

Cette isolation aide aussi à maîtriser les coûts, comme expliqué dans ces notes sur la réduction des coûts des jetons d’agent.

2. Exécuter des tâches en parallèle

Les tâches indépendantes ne doivent pas forcément s’exécuter en séquence.

Exemple :

  • un sous-agent révise le diff ;
  • un autre écrit des tests ;
  • un troisième met à jour la documentation.

Le temps total dépend alors de la tâche la plus lente, pas de la somme de toutes les tâches.

Les flux de travail dynamiques poussent ce modèle plus loin avec de nombreux sous-agents parallèles dans une seule session.

3. Spécialiser les comportements

Un agent généraliste peut faire beaucoup de choses, mais un sous-agent bien configuré peut être meilleur sur une tâche précise.

Exemples :

  • un réviseur qui cherche explicitement les failles de sécurité ;
  • un testeur qui suit vos conventions d’assertion ;
  • un agent de documentation qui respecte votre style de README ;
  • un agent de migration qui applique une règle répétitive à plusieurs fichiers.

Vous construisez une petite équipe de spécialistes au lieu de surcharger un seul agent.

Comment créer un sous-agent personnalisé

Les sous-agents sont de simples fichiers Markdown.

Utilisez :

# Sous-agents au niveau projet
.claude/agents/

# Sous-agents personnels
~/.claude/agents/
Enter fullscreen mode Exit fullscreen mode

Chaque fichier contient :

  1. un en-tête YAML ;
  2. un corps Markdown qui sert d’invite système.

Exemple : un sous-agent de revue 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.
Enter fullscreen mode Exit fullscreen mode

Champs YAML

name

Identifiant du sous-agent.

Exemple :

name: code-reviewer
Enter fullscreen mode Exit fullscreen mode

Vous pouvez ensuite l’invoquer explicitement :

Utilise le sous-agent code-reviewer sur les changements du module commandes.
Enter fullscreen mode Exit fullscreen mode

description

Champ le plus important pour la délégation automatique.

Claude lit cette description pour décider quand appeler le sous-agent.

Préférez une description orientée déclencheur :

description: Reviews code changes for bugs, security issues, and convention violations. Use after writing or editing code.
Enter fullscreen mode Exit fullscreen mode

Évitez les descriptions vagues :

description: Code reviewer
Enter fullscreen mode Exit fullscreen mode

tools

Liste d’autorisation des outils disponibles.

Exemple pour un réviseur qui ne doit pas modifier le code :

tools: Read, Grep, Glob
Enter fullscreen mode Exit fullscreen mode

Exemple pour un testeur qui doit pouvoir écrire et lancer des tests :

tools: Read, Grep, Write, Bash
Enter fullscreen mode Exit fullscreen mode

Si vous omettez tools, le sous-agent hérite des outils de l’agent principal. C’est pratique, mais moins sûr.

model

Permet d’épingler un modèle pour ce sous-agent.

Exemple :

model: sonnet
Enter fullscreen mode Exit fullscreen mode

Utilisez un modèle rapide pour les tâches mécaniques et un modèle plus puissant pour les tâches de raisonnement complexe.

Corps du fichier

Le corps Markdown devient l’invite système du sous-agent.

Rédigez-le comme un brief opérationnel :

  • objectif ;
  • étapes ;
  • priorités ;
  • format de sortie ;
  • comportements à éviter.

Exemple de consigne utile :

Return your findings as:

- Verdict: pass/fail
- Critical issues
- Non-blocking issues
- Files reviewed
- Suggested next action
Enter fullscreen mode Exit fullscreen mode

Vous pouvez aussi compléter ces instructions avec un fichier de projet comme design.md ou AGENTS.md, afin de centraliser vos conventions.

Comment invoquer des sous-agents

Il existe deux modes.

1. Délégation automatique

Claude utilise le champ description pour décider quand déléguer.

Exemple :

description: Reviews code changes for bugs, security issues, and convention violations. Use after writing or editing code.
Enter fullscreen mode Exit fullscreen mode

Après une modification de code, Claude peut déléguer automatiquement au sous-agent code-reviewer.

Pour fiabiliser cette délégation :

  • décrivez le moment d’utilisation ;
  • indiquez le type de tâche ;
  • évitez les intitulés trop génériques.

2. Invocation explicite

Vous pouvez appeler un sous-agent par son nom :

Utilise le sous-agent code-reviewer pour vérifier les changements dans src/orders.
Enter fullscreen mode Exit fullscreen mode

Ou :

Utilise le sous-agent api-test-writer pour écrire les tests du nouvel endpoint POST /orders.
Enter fullscreen mode Exit fullscreen mode

L’invocation explicite est préférable quand vous voulez contrôler précisément quel spécialiste intervient.

Dans les deux cas, le sous-agent travaille dans son propre contexte, puis renvoie son résultat au fil principal.

Pour construire des séquences plus déterministes, les commandes slash et le SDK offrent plus de contrôle que l’invocation ad hoc. Voir l’aperçu de Claude Code.

Sous-agents vs SDK d’agent vs flux de travail dynamiques

Outil Modèle de contrôle Idéal pour
Sous-agents Claude décide quand déléguer, ou vous nommez un agent Spécialisation en session et parallélisme léger
Flux de travail dynamiques Claude orchestre un déploiement large dans une session Nombreuses tâches parallèles et balayages larges
SDK d’agent Vous écrivez le flux de contrôle dans le code Boucles déterministes, planifiées ou sans surveillance

Utilisez les sous-agents quand vous travaillez dans Claude Code et voulez déléguer à un ou deux spécialistes.

Passez au SDK d’agent Claude quand vous devez écrire une orchestration programmatique, déterministe ou planifiée.

Si vous comparez une option hébergée avec une solution construite en interne, cette comparaison des agents gérés vs le SDK d’agent détaille les compromis.

Exemple pratique : revue parallèle et écriture de tests

Supposons que l’agent principal vient d’implémenter un nouvel endpoint de commande.

Vous voulez deux vérifications :

  1. une revue de code ;
  2. des tests API.

Ces tâches sont indépendantes. Elles peuvent donc tourner en parallèle.

Sous-agent 1 : revue 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.

Return:

- Verdict: pass/fail
- Blocking issues
- Non-blocking issues
- Files reviewed
- Recommended next action

Be specific. Cite file and line. Do not rubber-stamp.
Enter fullscreen mode Exit fullscreen mode

Sous-agent 2 : auteur de tests API 

---
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.

Return:

- Verdict: pass/fail
- Tests added
- Commands run
- Failures, if any
- Files changed
Enter fullscreen mode Exit fullscreen mode

Invocation

Dans Claude Code :

L’endpoint POST /orders vient d’être implémenté.

Lance en parallèle :
1. code-reviewer pour réviser le diff ;
2. api-test-writer pour écrire et exécuter les tests API.
Enter fullscreen mode Exit fullscreen mode

Résultat attendu :

  • le réviseur renvoie un rapport structuré ;
  • le testeur renvoie un verdict de test ;
  • le fil principal reste propre.

La partie importante est le verdict du testeur. Un sous-agent qui exécute réellement votre suite API devient une porte de vérification. Il ne juge pas seulement si le code “semble” correct : il vérifie si l’endpoint fonctionne.

C’est le principe des boucles d’agents de codage : la confiance vient du verdict de la porte de test, pas de l’agent.

Pour les tests d’API, vous pouvez connecter ce sous-agent à une plateforme dédiée. Les équipes qui utilisent Apidog peuvent diriger le sous-agent vers un scénario de test Apidog afin de valider les réponses par rapport au schéma. Elles peuvent aussi faire passer les appels live via le débogueur d’agent IA Apidog pour inspecter les requêtes comme le ferait un testeur humain.

Le même modèle peut ensuite être intégré dans des flux de travail Claude qui s’exécutent sans vous. Si vous voulez une porte de test sensible aux schémas dès le départ, vous pouvez télécharger Apidog.

Bonnes pratiques

Gardez une responsabilité par sous-agent

Un sous-agent doit faire une seule chose.

Bon découpage :

  • code-reviewer ;
  • api-test-writer ;
  • security-auditor ;
  • docs-writer.

Mauvais découpage :

name: everything-agent
description: Reviews code, writes tests, updates docs, fixes bugs, and deploys changes.
Enter fullscreen mode Exit fullscreen mode

Ce type de sous-agent recrée un agent généraliste, avec plus de complexité.

Écrivez des descriptions déclenchables

Le champ description doit dire quand utiliser le sous-agent.

Préférez :

description: Reviews code changes for bugs and security issues. Use after writing or editing code.
Enter fullscreen mode Exit fullscreen mode

À :

description: Code review expert.
Enter fullscreen mode Exit fullscreen mode

Appliquez le moindre privilège

N’accordez que les outils nécessaires.

Un réviseur peut souvent se limiter à :

tools: Read, Grep, Glob
Enter fullscreen mode Exit fullscreen mode

Un testeur peut nécessiter :

tools: Read, Grep, Write, Bash
Enter fullscreen mode Exit fullscreen mode

Cette séparation réduit le risque qu’un sous-agent modifie accidentellement ce qu’il devait seulement analyser.

Épinglez le bon modèle par tâche

Toutes les tâches ne nécessitent pas le même niveau de raisonnement.

  • Tâche répétitive : modèle plus rapide et moins coûteux.
  • Audit sécurité ou analyse complexe : modèle plus puissant.
  • Écriture de tests : modèle équilibré.

Cela aide à contrôler la vitesse et le coût.

Retournez des résultats structurés

Demandez un format de sortie stable.

Exemple :

Return:

- Verdict: pass/fail
- Summary
- Blocking issues
- Non-blocking issues
- Files changed
- Commands run
- Next action
Enter fullscreen mode Exit fullscreen mode

Un résultat structuré est plus facile à lire, à chaîner et à utiliser dans une boucle automatisée.

Évitez l’imbrication excessive

Des sous-agents qui appellent des sous-agents qui appellent des sous-agents deviennent difficiles à suivre et coûteux.

Gardez une hiérarchie simple :

Agent principal
├── code-reviewer
├── api-test-writer
└── docs-writer
Enter fullscreen mode Exit fullscreen mode

Ces pratiques rejoignent les modèles décrits dans le câblage d’outils de flux de travail agentiques.

Quand utiliser les sous-agents

Utilisez un sous-agent quand la tâche est :

  • délimitée ;
  • indépendante ;
  • bruyante.

Exemples adaptés :

  • revue d’un diff ;
  • écriture d’une suite de tests ;
  • reproduction d’un bug ;
  • audit sécurité d’un module ;
  • vérification d’un endpoint API ;
  • génération de documentation à partir d’un ensemble de fichiers.

Ces tâches produisent beaucoup de travail intermédiaire, mais leur résultat final peut être résumé clairement.

Quand éviter les sous-agents

Évitez un sous-agent quand la tâche est :

  • petite ;
  • fortement couplée au contexte principal ;
  • strictement séquentielle ;
  • déjà bien comprise par l’agent principal.

Exemples :

  • renommer une variable ;
  • corriger une faute de frappe ;
  • modifier une ligne ;
  • appliquer une correction déjà évidente ;
  • continuer une tâche où l’agent principal possède tout le contexte nécessaire.

Si l’agent principal doit expliquer la moitié de la conversation pour briefer le sous-agent, gardez la tâche dans le fil principal.

Règle pratique :

Déléguez ce qui peut être décrit en un paragraphe et exécuté indépendamment.

Un nouvel endpoint à réviser et tester convient. Une faute de frappe ne convient pas.

À plus grande échelle, les flux de travail dynamiques prennent le relais, mais la logique reste la même : parallélisez ce qui est indépendant.

Erreurs courantes

Descriptions trop vagues

Si la description ne contient pas de déclencheur clair, Claude ne saura pas toujours quand déléguer.

Mauvais :

description: Testing agent
Enter fullscreen mode Exit fullscreen mode

Mieux :

description: Writes and runs API tests for new or changed endpoints. Use after endpoint implementation.
Enter fullscreen mode Exit fullscreen mode

Sous-agent trop large

Un sous-agent qui fait tout perd l’intérêt de la spécialisation.

Divisez par responsabilité :

  • revue ;
  • test ;
  • documentation ;
  • sécurité.

Hériter de tous les outils

Omettre tools donne au sous-agent les outils de l’agent principal.

C’est acceptable pour un travail de confiance, mais risqué pour des exécutions automatisées.

Préférez une liste explicite :

tools: Read, Grep, Glob
Enter fullscreen mode Exit fullscreen mode

Oublier la vérification

Une configuration qui révise et construit sans exécuter de tests peut produire du code plausible mais cassé.

Ajoutez un sous-agent de vérification :

name: api-test-runner
description: Runs API tests and reports pass/fail. Use before considering endpoint work complete.
tools: Read, Bash
Enter fullscreen mode Exit fullscreen mode

Confondre sous-agents et SDK

Les sous-agents sont utiles en session, déclenchés par Claude ou appelés explicitement.

Si vous voulez un workflow programmatique, planifié ou sans surveillance, utilisez le SDK d’agent plutôt qu’un empilement de sous-agents.

L’article d’Anthropic Building Effective Agents développe ce principe général : structurer le travail autour du modèle est souvent plus efficace que simplement agrandir l’invite.

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 une tâche. Chaque sous-agent possède sa propre fenêtre de contexte, sa propre invite système et ses propres outils configurables.

Comment créer un sous-agent Claude Code ?

Créez un fichier Markdown dans :

.claude/agents/
Enter fullscreen mode Exit fullscreen mode

Ou, pour un sous-agent personnel :

~/.claude/agents/
Enter fullscreen mode Exit fullscreen mode

Ajoutez un en-tête YAML avec name, description, tools facultatif et model facultatif. Le corps du fichier devient l’invite système.

Comment Claude choisit-il le sous-agent à utiliser ?

Claude lit le champ description de chaque sous-agent disponible. Si une tâche correspond, il peut déléguer automatiquement.

Vous pouvez aussi invoquer un sous-agent explicitement par son nom.

Quelle est la différence entre les sous-agents et le SDK d’agent Claude ?

Les sous-agents sont utilisés en session dans Claude Code. Le modèle décide de déléguer, ou vous nommez un sous-agent.

Le SDK d’agent sert à écrire un flux de contrôle dans du code, pour des exécutions déterministes, planifiées ou sans surveillance.

Les sous-agents peuvent-ils s’exécuter en parallèle ?

Oui. L’agent principal peut lancer plusieurs sous-agents pour des tâches indépendantes : revue, tests, documentation, audit, etc.

Pour des déploiements plus larges, les flux de travail dynamiques permettent de gérer de nombreux sous-agents parallèles dans une même session.

Comment les sous-agents aident-ils avec les tests d’API ?

Vous pouvez créer un sous-agent qui lit la spécification OpenAPI, écrit des tests, les exécute et renvoie un verdict.

Connecté à une plateforme comme Apidog, ce sous-agent peut valider les réponses par rapport au contrat API, au lieu de se limiter à une vérification subjective.

Conclusion

Les sous-agents Claude Code résolvent une limite pratique : une seule fenêtre de contexte ne peut pas tout contenir proprement.

En donnant à chaque tâche son propre contexte, ses instructions et ses outils, vous transformez un agent généraliste surchargé en une petite équipe spécialisée.

Commencez simplement :

  1. créez un code-reviewer ;
  2. créez un api-test-writer ;
  3. limitez leurs outils ;
  4. exigez des résultats structurés ;
  5. utilisez le testeur comme porte de vérification.

Pour les endpoints API, Apidog donne à cette porte un schéma à vérifier. Vous pouvez télécharger Apidog et laisser un sous-agent de test prouver que votre code fonctionne avant de considérer le diff terminé.

Top comments (0)