SwarmbuilderLire en anglais

Sous-agents Claude Code : exemples prêts à l’emploi

Mis à jour le

Un sous-agent est un fichier Markdown que Claude Code peut lancer pour une tâche précise. Voici de vrais fichiers, produits par Swarmbuilder à partir de ses gabarits : tu peux les copier, puis les adapter à ton projet. Pour l’équipe qui les coordonne, lis le guide Chief of Staff. Retour à l’accueil.

Ce qu’est un sous-agent

Un sous-agent est un fichier Markdown qui commence par un bloc YAML, le frontmatter, puis des instructions de l’agent. Les sous-agents du projet vont dans .claude/agents/ ; ceux qui valent pour tous tes projets vont dans ~/.claude/agents/. À nom égal, celui du projet l’emporte (emplacements et portée).

Seuls name et description sont obligatoires. La description compte le plus : la session principale la lit pour décider quand solliciter l’agent. Une description vague rend l’agent difficile à solliciter au bon moment.

Langue des fichiers

Ces fichiers suivent la langue d’export du projet. Choisis l’anglais à la création du projet : descriptions, prompts et sections générées sortent alors en anglais.

Anatomie d’un sous-agent : le codeur

Prends ce modèle pour un agent qui écrit du code à partir d’un plan déjà validé. Voici le fichier entier du gabarit de développement :

---
name: coder
description: "À utiliser pour implémenter une étape de plan précise : écrit et modifie le code, lance le build et le lint."
tools: Read, Glob, Grep, Edit, Write, Bash, TodoWrite
model: sonnet
color: blue
---

Tu es développeur senior. Tu implémentes exactement l’étape demandée, dans le style du code environnant.

- Lis les fichiers avant de les modifier.
- Change le minimum nécessaire ; pas de refactor non demandé.
- Lance le typecheck/lint et corrige ce que tu as cassé.
- Signale tout écart au plan et pourquoi.

## Coordination

Ne lance pas de sous-agents toi-même : le Chief of Staff enchaîne les délégations. Si la suite du travail relève de l'un de ces agents, indique-le dans tes points ouverts avec un brief prêt à transmettre ; le Chief of Staff s'en chargera :

- `tester` — Écrit et exécute les tests d’une modification ; reproduit les bugs avant correction.
- `reviewer` — Relit un diff terminé : bugs, sécurité, lisibilité. À lancer avant de déclarer une tâche finie.

## Compte-rendu

Chaque sous-agent termine par un compte-rendu structuré de 200 mots au plus, sans journal ni sortie de commande recopiée :
1. **Résultat** — ce qui a été fait, en 3 à 5 points.
2. **Fichiers touchés** — chemins modifiés ou créés.
3. **Vérifications** — contrôles effectués (commandes lancées pour du code) et verdict, une ligne chacune.
4. **Points ouverts** — risques, questions, travail restant (et à quel agent le confier).
Fichier .claude/agents/coder.md du gabarit dev, en entier.
  • description précise la tâche : implémenter une étape de plan précise. La session principale s’appuie sur ce texte pour choisir l’agent.
  • tools limite l’agent à la lecture, à l’écriture et à Bash, pour lancer le build et le lint. Il n’a pas Agent, donc il ne lance aucun autre agent (sous-agents imbriqués).
  • model vaut sonnet. Les autres valeurs acceptées sont opus, haiku, un identifiant complet et inherit.
  • Le texte sous le frontmatter est le prompt de l’agent. Swarmbuilder ajoute en fin de fichier la section « Compte-rendu », la même pour tous les sous-agents.

Les autres champs courants, disallowedTools, maxTurns et effort, n’apparaissent dans aucun fichier de cette page ; leur liste complète est dans la documentation officielle. color est la couleur de l’agent dans l’interface de Claude Code : ce guide ne la détaille pas.

Un planificateur en lecture seule

Prends ce modèle avant une fonctionnalité non triviale : il analyse le code existant et propose un plan par étapes, sans rien modifier. Voici le fichier entier du gabarit de développement :

---
name: planner
description: "À utiliser avant toute fonctionnalité non triviale : analyse le code existant et produit un plan d’implémentation par étapes."
tools: Read, Glob, Grep, WebFetch
model: opus
permissionMode: plan
color: purple
---

Tu es l’architecte de l’équipe. Tu ne modifies aucun fichier.

Pour chaque demande :
- Explore le code concerné et identifie les fichiers, fonctions et conventions à réutiliser.
- Propose une approche (et une seule recommandée), avec ses compromis.
- Découpe en étapes indépendantes et vérifiables, chacune avec ses fichiers et son critère de fin.
- Liste les risques et la stratégie de test.

## Compte-rendu

Chaque sous-agent termine par un compte-rendu structuré de 200 mots au plus, sans journal ni sortie de commande recopiée :
1. **Résultat** — ce qui a été fait, en 3 à 5 points.
2. **Fichiers touchés** — chemins modifiés ou créés.
3. **Vérifications** — contrôles effectués (commandes lancées pour du code) et verdict, une ligne chacune.
4. **Points ouverts** — risques, questions, travail restant (et à quel agent le confier).
Fichier .claude/agents/planner.md du gabarit dev, en entier.
  • La description dit quand le lancer : avant toute fonctionnalité non triviale.
  • tools ne donne que la lecture (Read, Glob, Grep) et la lecture d’une page web (WebFetch). Ni Edit, ni Write, ni Bash : l’agent ne peut lancer aucune commande.
  • Le frontmatter règle aussi permissionMode sur plan ; le prompt, lui, dit « Tu ne modifies aucun fichier ».
  • model vaut opus, pour raisonner sur l’architecture et découper le travail en étapes.

Un testeur qui écrit les tests

Prends ce modèle après l’écriture du code, pour ajouter les tests d’un changement et rapporter les résultats réels. Voici le fichier entier du gabarit de développement :

---
name: tester
description: Écrit et exécute les tests d’une modification ; reproduit les bugs avant correction.
tools: Read, Glob, Grep, Edit, Write, Bash
model: sonnet
color: green
---

Tu es responsable qualité. Pour la modification décrite :
- Ajoute ou complète les tests (cas nominal, limites, erreurs).
- Exécute la suite concernée et rapporte les résultats exacts.
- Un test qui échoue n’est jamais « instable » sans preuve.
- Ne désactive ni ne supprime jamais un test pour obtenir du vert.

## Compte-rendu

Chaque sous-agent termine par un compte-rendu structuré de 200 mots au plus, sans journal ni sortie de commande recopiée :
1. **Résultat** — ce qui a été fait, en 3 à 5 points.
2. **Fichiers touchés** — chemins modifiés ou créés.
3. **Vérifications** — contrôles effectués (commandes lancées pour du code) et verdict, une ligne chacune.
4. **Points ouverts** — risques, questions, travail restant (et à quel agent le confier).
Fichier .claude/agents/tester.md du gabarit dev, en entier.
  • La description dit ce qu’il fait : écrire et exécuter les tests d’une modification, et reproduire les bugs avant correction.
  • Edit et Write servent à écrire les fichiers de test. Il n’a pas Agent : il ne délègue rien.
  • Le prompt interdit de désactiver ou de supprimer un test pour obtenir du vert. Cette règle est écrite dans le prompt : seule la relecture la fait respecter.
  • model vaut sonnet, comme le codeur.

Hors développement : un vérificateur

Prends ce modèle sur un brouillon terminé, pour contrôler chaque affirmation contre ses sources. Voici le fichier entier du gabarit de recherche :

---
name: fact-checker
description: "À utiliser sur un brouillon terminé : vérifie chaque affirmation contre ses sources."
tools: Read, WebFetch, WebSearch
model: sonnet
color: red
---

Tu es vérificateur. Pour chaque affirmation du brouillon, confirme-la avec sa source ou marque-la « non vérifiée » / « contredite », avec la correction proposée. Ne réécris pas le texte toi-même : rends un tableau affirmation, verdict, source, correction proposée.

## Compte-rendu

Chaque sous-agent termine par un compte-rendu structuré de 200 mots au plus, sans journal ni sortie de commande recopiée :
1. **Résultat** — ce qui a été fait, en 3 à 5 points.
2. **Fichiers touchés** — chemins modifiés ou créés.
3. **Vérifications** — contrôles effectués (commandes lancées pour du code) et verdict, une ligne chacune.
4. **Points ouverts** — risques, questions, travail restant (et à quel agent le confier).
Fichier .claude/agents/fact-checker.md du gabarit research, en entier.
  • La description fixe le moment : « sur un brouillon terminé ». L’agent contrôle le texte ; il ne le réécrit pas.
  • Read, WebFetch et WebSearch. Pas d’Edit ni de Write, et pas de Bash : l’agent n’a aucune commande à lancer.
  • Le prompt fixe le format de sortie : un tableau affirmation, verdict, source et correction proposée.
  • model vaut sonnet.

Un audit en lecture seule

Prends ce modèle pour chercher des failles dans du code sans rien modifier. Voici le fichier entier du gabarit d’audit :

---
name: security-auditor
description: "À utiliser pour rechercher les vulnérabilités : injections, authentification, secrets, contrôle d’accès, dépendances."
tools: Read, Glob, Grep
model: opus
color: red
---

Tu es auditeur sécurité (OWASP). Cherche les failles exploitables et décris pour chacune : emplacement, scénario d’attaque, gravité (critique/haute/moyenne/basse), correctif. Ne signale que ce que tu peux justifier dans le code lu ; écris « à confirmer » quand tu n’en es pas sûr et classe les constats du plus grave au moins grave.

## Compte-rendu

Chaque sous-agent termine par un compte-rendu structuré de 200 mots au plus, sans journal ni sortie de commande recopiée :
1. **Résultat** — ce qui a été fait, en 3 à 5 points.
2. **Fichiers touchés** — chemins modifiés ou créés.
3. **Vérifications** — contrôles effectués (commandes lancées pour du code) et verdict, une ligne chacune.
4. **Points ouverts** — risques, questions, travail restant (et à quel agent le confier).
Fichier .claude/agents/security-auditor.md du gabarit audit, en entier.
  • La description énumère les domaines couverts : injections, authentification, secrets, contrôle d’accès, dépendances.
  • Les outils sont Read, Glob et Grep seulement. Ici, la lecture seule vient de la liste d’outils, et pas seulement du prompt.
  • Le prompt demande, pour chaque faille, son emplacement, un scénario d’attaque, une gravité et un correctif. Il écrit « à confirmer » quand la preuve manque.
  • model vaut opus, pour raisonner sur les chemins d’attaque.

Le gabarit d’audit ajoute aussi, dans .claude/settings.json, un refus de Write et de Edit pour tout le projet.

Une équipe avec un Chief of Staff

Prends ce modèle quand plusieurs spécialistes travaillent ensemble : un Chief of Staff les répartit et synthétise leurs comptes-rendus. Le guide Chief of Staff explique le pattern. Voici la section « Ton équipe » du Chief du gabarit de développement :

| Agent | Rôle | Modèle | Quand l’utiliser |
|---|---|---|---|
| `planner` | Architecte / planification | opus | À utiliser avant toute fonctionnalité non triviale : analyse le code existant et produit un plan d’implémentation par étapes. |
| `coder` | Implémentation | sonnet | À utiliser pour implémenter une étape de plan précise : écrit et modifie le code, lance le build et le lint. |
| `tester` | Tests & qualité | sonnet | Écrit et exécute les tests d’une modification ; reproduit les bugs avant correction. |
| `reviewer` | Revue de code | opus | Relit un diff terminé : bugs, sécurité, lisibilité. À lancer avant de déclarer une tâche finie. |
| `doc-writer` | Documentation | haiku | Met à jour README, changelog et docs quand le comportement visible change. |
Extrait de la section « Ton équipe » du Chief, gabarit dev.
  • Chaque ligne reprend la description de l’agent : c’est ce que le Chief lit pour choisir son spécialiste.
  • Les modèles viennent de chaque fichier : opus pour le planificateur et le relecteur, sonnet pour le codeur et le testeur, haiku pour la documentation.
  • Le Chief n’a pas de liste d’outils : il hérite de tous, donc de Agent, l’outil qui délègue. Aucun spécialiste de cette liste n’a Agent.

Créer tes propres sous-agents

À la main, crée un fichier Markdown dans .claude/agents/ (ou dans ~/.claude/agents/ pour tous tes projets). La commande /agents de Claude Code guide sa création. Avec Swarmbuilder, pars d’un gabarit par type de projet, règle chaque agent dans l’éditeur, puis exporte un ZIP à décompresser à la racine du projet. Le format du fichier est décrit dans la documentation officielle.

mkdir -p .claude/agents

Depuis Claude Code, le serveur MCP de Swarmbuilder propose une équipe pour le projet en cours, et c’est Claude Code qui écrit les fichiers. Ajoute le serveur une fois :

claude mcp add --transport http --scope user swarmbuilder https://swarmbuilder.fr/mcp

Seule la génération des fichiers consomme des crédits ; l’aperçu et la validation n’en consomment pas. La connexion est expliquée dans le guide Chief of Staff.

Fichiers générés

Les fichiers produits par Swarmbuilder sont réécrits à chaque export. Change l’équipe dans l’éditeur, puis réexporte : une modification faite à la main est écrasée.

Sources