Sous-agents Claude Code (subagents) : guide pratique pour écrire les vôtres

La plupart des gens commencent avec Claude Code comme une seule longue conversation. Ça marche, jusqu'au moment où la conversation se remplit de logs de tests, de résultats de recherche et d'idées à moitié finies, et où le modèle perd de vue l'essentiel. Les sous-agents (subagents) règlent ce problème. Ils permettent de confier une tâche précise à un agent séparé, avec ses propres instructions et ses propres outils, et de ne récupérer que le résultat.

J'utilise des subagents personnalisés tous les jours, y compris sur un terminal de trading en production où des agents développeurs et relecteurs font l'essentiel du volume. J'ai décrit ce pipeline complet à part. Cet article est la partie pratique : comment fonctionnent les subagents de Claude Code et comment en écrire de bons.

Claude Code évolue vite. Tout ce qui suit correspond à la documentation officielle sur les subagents à fin 2026, mais vérifiez la documentation de votre version avant de compter sur un champ précis.

Ce que sont les subagents de Claude Code

Un subagent est un assistant spécialisé auquel la session principale de Claude Code peut déléguer. Trois choses le rendent utile :

Sa propre fenêtre de contexte. Le subagent ne voit pas l'historique de votre conversation. La session principale lui écrit une tâche, il travaille de son côté, et seul son résumé revient. Les sorties verbeuses restent hors de votre contexte principal.
Son propre prompt système. Le corps du fichier devient ses instructions. Vous pouvez écrire un règlement strict pour une tâche sans encombrer toutes les autres.
Ses propres outils. Vous ne lui donnez que les outils dont il a besoin. Un relecteur peut lire le code sans pouvoir le modifier.

La contrepartie : un subagent démarre à froid. Il ne sait que ce que le message de délégation lui dit, donc la qualité de cette passation compte.

Où placer les fichiers

Un subagent est un fichier Markdown avec un frontmatter YAML. Les deux emplacements que vous utiliserez le plus :

.claude/agents/ dans votre dépôt, pour les subagents du projet. Versionnez-les pour que toute l'équipe partage les mêmes agents.
~/.claude/agents/ dans votre dossier personnel, pour vos subagents disponibles dans tous vos projets.

Si deux subagents portent le même nom, celui du projet l'emporte sur le personnel. Claude Code parcourt aussi les sous-dossiers, vous pouvez donc ranger vos agents par répertoire. L'identité d'un agent vient de son champ name, pas du chemin du fichier.

Les champs de frontmatter qui comptent

Seuls deux champs sont obligatoires :

name : un identifiant unique, par exemple code-reviewer.
description : quand Claude doit déléguer à cet agent. C'est la ligne la plus importante du fichier.

Les champs optionnels que j'utilise le plus :

tools : une liste blanche d'outils. Sans elle, le subagent hérite de tous les outils disponibles.
model : le modèle qui fait tourner l'agent, ou inherit pour reprendre celui de la session principale.
maxTurns : un plafond sur le nombre de tours que le subagent peut faire avant de s'arrêter.
permissionMode : la façon dont il gère les demandes de permission.
isolation : avec la valeur worktree, le subagent reçoit son propre worktree git et ne peut pas entrer en collision avec le reste de votre copie de travail.

Il existe d'autres champs (hooks, skills, serveurs MCP, mémoire…), mais ceux-là suffisent pour aller loin.

Comment fonctionne la délégation

Claude délègue automatiquement quand une tâche correspond à la description d'un subagent. Écrire « use proactively » dans la description l'encourage à déléguer sans qu'on le lui demande.

Vous pouvez aussi être explicite :

Par son nom, en langage naturel : « Utilise le subagent code-reviewer pour relire les changements d'authentification. »
Par une @-mention, qui garantit que ce subagent précis tourne.
Pour toute une session, en lançant Claude Code avec cet agent comme agent principal.

Claude Code fournit aussi des subagents intégrés, dont Explore (recherche rapide en lecture seule dans le code), Plan (recherche en lecture seule utilisée en mode plan) et general-purpose (tous les outils, pour les tâches en plusieurs étapes). Avant d'écrire un agent personnalisé, vérifiez qu'un agent intégré ne fait pas déjà le travail.

Deux exemples de définitions

Un relecteur en lecture seule. Il peut regarder sans toucher, et doit prouver chaque affirmation :

---
name: code-reviewer
description: Reviews a diff for correctness bugs. Use proactively after code changes.
tools: Read, Grep, Glob, Bash
model: inherit
maxTurns: 40
---

You review one change. Your job is to find what the author missed,
not to confirm it works.

Rules:
- Read the diff and the code it touches. Run the existing tests.
- Report only findings you can reproduce with a failing test or command.
- For each finding: file, line, what breaks, and the repro.
- If you find nothing provable, say "no findings". Do not pad the list.

Un développeur qui travaille isolé et s'arrête aux contrôles :

---
name: implementer
description: Implements one scoped ticket end to end in an isolated worktree.
isolation: worktree
model: inherit
---

You implement exactly one ticket.

- Read the ticket and the relevant contract or spec first.
- Write the code and the tests together.
- Before reporting done, run lint, the full test suite and the build.
- Report: what changed, which files, gate results. If a gate fails, say so.

J'écris les instructions en anglais, mais le français fonctionne aussi. La règle du relecteur sur les problèmes reproductibles n'est pas décorative : sans elle, les relecteurs IA produisent du bruit plausible. J'explique pourquoi dans tout relecteur de code IA a besoin d'une repro qui échoue.

Conseils de conception

Écrivez la description pour le routeur

La description est ce que Claude lit pour décider de déléguer. Elle doit dire quand, pas seulement quoi : « Relit un diff pour trouver des bugs après une modification » vaut mieux que « Expert en revue de code ». Restez court. Chaque description occupe de la place dans le contexte de la session principale, et Claude Code vous avertit quand l'ensemble des descriptions de vos subagents devient trop volumineux.

Donnez le moins d'outils possible

Un relecteur qui peut modifier des fichiers finira par « corriger » ce qu'il devait signaler. Un agent de recherche n'a pas besoin d'écrire. Des listes d'outils restreintes rendent les agents plus prévisibles et plus sûrs.

Définissez le format de retour

La session principale ne voit que le résumé. Dites au subagent exactement quoi renvoyer : une liste de problèmes avec leurs repros, un court rapport avec les résultats des contrôles, une liste de fichiers. Un résumé bavard gaspille le contexte que vous vouliez économiser.

Une seule tâche par agent

« Développer, tester, relire et documenter », ce sont quatre agents déguisés en un seul. Un agent avec une seule tâche et un règlement clair est plus facile à déboguer quand ça déraille.

Les pièges courants

Croire que le subagent connaît le contexte. Il ne voit pas votre conversation. S'il a besoin du ticket, de la branche ou d'une contrainte, la délégation doit le dire.
Laisser les agents noter leur propre copie. Ce n'est pas au développeur de décider que son travail est correct. Utilisez des contrôles automatiques et un relecteur séparé.
Aucune limite de tours. Un agent coincé dans une boucle continue de consommer des tokens. maxTurns est une assurance qui ne coûte rien. Je parle d'autres pièges de coût dans réduire le coût des LLM.
Trop d'agents qui se chevauchent. Si deux descriptions correspondent à la même tâche, la délégation devient imprévisible. Fusionnez-les ou précisez-les.

Travailler ensemble

Je suis Driss Briksine, ingénieur logiciel et ML. Je construis des systèmes multi-agents et j'utilise des subagents Claude Code personnalisés pour livrer du code de production, comme sur le terminal de trading sur lequel je travaille. Si vous voulez une configuration de subagents pensée pour le code de votre équipe, envoyez-moi un court descriptif.