Créer des sous-agents personnalisés

• Préserver le contexte en gardant l’exploration et l’implémentation en dehors de votre conversation principale
• Appliquer des contraintes en limitant les outils qu’un sous-agent peut utiliser
• Réutiliser les configurations dans les projets avec des sous-agents au niveau utilisateur
• Spécialiser le comportement avec des invites système ciblées pour des domaines spécifiques
• Contrôler les coûts en acheminant les tâches vers des modèles plus rapides et moins chers comme Haiku

​

Sous-agents intégrés

• Pour bloquer un type intégré spécifique, ajoutez-le à permissions.deny comme indiqué dans Désactiver des sous-agents spécifiques.
• Pour empêcher Claude de déléguer à quelque sous-agent que ce soit, refusez l’outil Agent lui-même avec permissions.deny.
• Pour supprimer uniquement les sous-agents intégrés Explore et Plan, définissez CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1. Claude lit et explore alors les fichiers directement au lieu de leur déléguer ces tâches. Nécessite Claude Code v2.1.198 ou une version ultérieure.
• En mode non interactif et dans l’Agent SDK, définissez CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1 pour supprimer tous les types intégrés et ne fournir que les vôtres.

​

Démarrage rapide : créer votre premier sous-agent

Create a personal code-improver subagent in ~/.claude/agents/ that scans
files and suggests improvements for readability, performance, and best
practices. It should explain each issue, show the current code, and
provide an improved version. Make it read-only and have it use Sonnet.

---
name: code-improver
description: Scans files and suggests improvements for readability, performance, and best practices. Use after writing or modifying code.
tools: Read, Grep, Glob
model: sonnet
---

You are a code improvement specialist. For each issue you find, explain
the problem, show the current code, and provide an improved version.

Use the code-improver agent to suggest improvements in this project

​

Configurer les sous-agents

​

Choisir la portée du sous-agent

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  },
  "debugger": {
    "description": "Debugging specialist for errors and test failures.",
    "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."
  }
}'

claude --agents @'
{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  },
  "debugger": {
    "description": "Debugging specialist for errors and test failures.",
    "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."
  }
}
'@

• prompt : le prompt système de l’agent, équivalent au corps markdown dans les sous-agents basés sur fichier. prompt peut être vide. Si vous sélectionnez un agent avec un prompt vide et aucun champ memory comme agent de la session avec --agent, le prompt système de la session reste inchangé. Un prompt vide nécessite Claude Code v2.1.281 ou ultérieur.
• Champs de frontmatter : description, tools, disallowedTools, model, permissionMode, mcpServers, hooks, maxTurns, autoCompactWindow, skills, initialPrompt, memory, effort, background, omitClaudeMd et isolation.
• Champs ignorés : color et experimental ne sont pas acceptés ici et sont ignorés plutôt que rejetés.

​

Écrire des fichiers de sous-agent

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

• Il bloque une commande qui redirige git vers l’extraction principale.
• Il refuse une commande lorsqu’il ne peut pas vérifier à partir du texte de la commande que tout git que la commande exécute reste à l’intérieur du worktree, par exemple lorsque le nom de la commande est calculé à l’exécution.

​

Référence de frontmatter

• Pour trouver un champ mal orthographié dans un sous-agent qui s’est chargé, exécutez claude --debug dans votre shell et recherchez does not recognize or apply dans le journal de débogage à ~/.claude/debug/<session-id>.txt. Le journal de débogage nomme jusqu’à cinq champs de niveau supérieur du fichier du sous-agent que Claude Code ne reconnaît pas, avec le nom probablement voulu lorsqu’un champ pris en charge est proche. Nécessite Claude Code v2.1.296 ou ultérieur.
• Pour savoir pourquoi un fichier de sous-agent ne s’est pas chargé, consultez Fichiers de sous-agent que Claude Code ignore.

---
name: repo-auditor
description: Audits a large repository and reports what it finds
experimental:
  cacheTtl: 1h
---

​

Fichiers de sous-agent que Claude Code ignore

• Pas de name : Claude Code traite le fichier comme de la documentation conservée à côté de vos agents.
• Un --- d’ouverture qui n’est pas la première ligne du fichier : Claude Code lit le fichier comme n’ayant pas de frontmatter et le traite comme de la documentation.
• Un name qui commence par -, contient : ou dépasse 256 caractères : Claude Code ignore le fichier et écrit une erreur dans le journal de débogage.
• Un name mais pas de description : Claude Code ignore le fichier et écrit la raison dans le journal de débogage.
• YAML qui ne s’analyse pas : Claude Code ne lit aucun champ du fichier, l’ignore et écrit l’erreur d’analyse dans le journal de débogage.

​

Choisir un modèle

• Alias de modèle : utilisez l’un des alias disponibles : sonnet, opus, haiku ou fable
• ID de modèle complet : utilisez un ID de modèle complet tel que claude-opus-5-5 ou claude-sonnet-5. Accepte les mêmes valeurs que le flag --model
• inherit : utilisez le même modèle que la conversation principale

1. Le paramètre model par invocation
2. Le frontmatter model de la définition du sous-agent, où inherit sélectionne le modèle de la conversation principale
3. La variable d’environnement CLAUDE_CODE_SUBAGENT_MODEL, lorsque vous la définissez sur un alias de modèle ou un ID de modèle
4. Le modèle de la conversation principale

• Le modèle de la conversation principale appartient à cette famille : le sous-agent s’exécute sur le modèle exact de la conversation principale, y compris tout suffixe [1m], donc il obtient la même fenêtre de contexte étendu que la conversation principale.
• Claude Code ne peut pas déterminer la famille du modèle de la conversation principale, sur un fournisseur autre que l’API Anthropic : cela peut se produire avec un ARN de profil d’inférence d’application sur Amazon Bedrock que Claude Code n’a pas résolu à un modèle de support. Ce cas couvre uniquement l’alias opus, et ne s’applique pas lorsque vous définissez ANTHROPIC_DEFAULT_OPUS_MODEL, puisque opus se résout alors au modèle que vous définissez.

• Lorsque la valeur bloquée est un alias de famille tel que opus, Claude Code exécute le sous-agent sur la version la plus récente de cette famille que la liste d’autorisation permet, en suivant les mêmes règles de substitution et portée du fournisseur que /model. Avant la v2.1.222, Claude Code exécutait le sous-agent sur le modèle hérité pour un alias de famille bloqué également.
• Pour toute autre valeur bloquée, sur les fournisseurs où cette substitution ne fonctionne pas, ou lorsque la liste d’autorisation ne permet aucune version de la famille, Claude Code exécute le sous-agent sur le modèle hérité à la place. Si vous définissez CLAUDE_CODE_SUBAGENT_MODEL, Claude Code essaie d’abord ce modèle, selon les mêmes règles.

​

Exécuter chaque sous-agent sur un modèle

• Si vous définissez les deux variables, les sous-agents s’exécutent sur le modèle dans CLAUDE_CODE_SUBAGENT_MODEL.
• Si vous définissez uniquement CLAUDE_CODE_SUBAGENT_MODEL_FORCE, les sous-agents s’exécutent sur le modèle de la conversation principale, à ceci près que le sous-agent Explore intégré s’exécute sur le modèle indiqué pour lui sous Sous-agents intégrés.

{
  "env": {
    "CLAUDE_CODE_SUBAGENT_MODEL": "haiku",
    "CLAUDE_CODE_SUBAGENT_MODEL_FORCE": "1"
  }
}

• Un fork
• Un skill qui s’exécute dans un sous-agent avec model: inherit

​

Choisir un niveau d’effort

​

Contrôler les capacités des sous-agents

​

Outils disponibles

• Agent, lorsque le sous-agent est à la limite de profondeur ; dans un fork l’outil reste listé mais retourne une erreur au lieu de générer
• AskUserQuestion
• EndConversation, qui ne peut terminer que la conversation principale ; consultez Comportement de l’outil EndConversation
• EnterPlanMode
• ExitPlanMode, sauf si le permissionMode du sous-agent est plan
• ScheduleWakeup
• WaitForMcpServers
• Workflow

​

Restreindre les outils qu’un sous-agent peut utiliser

---
name: safe-researcher
description: Research agent with restricted capabilities
tools: Read, Grep, Glob, Bash
---

---
name: no-writes
description: Inherits the available tools except file writes
disallowedTools: Write, Edit
---

---
name: local-only
description: Inherits every tool except those from the github MCP server
disallowedTools: mcp__github
---

​

Restreindre les sous-agents qui peuvent être générés

---
name: coordinator
description: Coordinates work across specialized agents
tools: Agent(worker, researcher), Read, Bash
---

tools: Agent, Read, Bash

​

Limiter les serveurs MCP à un sous-agent

---
name: browser-tester
description: Tests features in a real browser using Playwright
mcpServers:
  # Inline definition: scoped to this subagent only
  - playwright:
      type: stdio
      command: npx
      args: ["-y", "@playwright/mcp@latest"]
  # Reference by name: reuses an already-configured server
  - github
---

Use the Playwright tools to navigate, screenshot, and interact with pages.

• --strict-mcp-config et --bare
• Configuration MCP gérée en entreprise
• Politiques allowedMcpServers et deniedMcpServers

​

Confiance requise pour les serveurs MCP en ligne

• La confiance qui ne compte pas : la confiance d’un dossier parent, et la confiance automatique qu’une session -p ou SDK obtient pour les hooks dans les fichiers de paramètres
• Jusqu’à ce moment : Claude Code ignore tous les serveurs en ligne dans ce fichier d’agent et écrit la clé exacte projects["<path>"].hasTrustDialogAccepted pour ~/.claude.json dans le journal de débogage
• Répertoires --add-dir : un répertoire en dehors du dépôt de votre espace de travail de confiance a besoin de sa propre entrée de confiance, car ses fichiers .claude/agents/ n’héritent pas de la confiance de votre espace de travail

• Un nom qui référence un serveur que vous avez déjà configuré
• Un serveur en ligne dans un fichier d’agent de ~/.claude/agents/, dans un que vous passez avec --agents ou l’option agents du SDK, ou dans un que les paramètres gérés fournissent

​

Modes de permission

• Lorsque la conversation principale est en bypassPermissions, acceptEdits ou mode auto, le sous-agent s’exécute dans ce même mode et Claude Code ignore le permissionMode que vous définissez. En mode auto, le classifieur évalue les appels d’outils du sous-agent avec les règles de blocage et d’autorisation de la conversation principale. Lorsque le sous-agent se termine, le classifieur examine également son travail et son rapport final avant que le rapport soit livré, comme Comment le mode auto gère les sous-agents le décrit.
• Lorsque la conversation principale est en mode default, dontAsk ou plan, le sous-agent s’exécute dans le mode de permission que vous définissez. Il conserve plutôt le mode de permission de la conversation principale dans les cas suivants :
  • Vous définissez bypassPermissions. L’exception bypassPermissions nécessite Claude Code v2.1.267 ou ultérieur.
  • Vous définissez auto et le mode auto n’est pas disponible pour le sous-agent, par exemple lorsqu’un fichier de paramètres définit disableAutoMode ou que le modèle du sous-agent ne prend pas en charge le mode auto.

​

Précharger les skills dans les sous-agents

---
name: api-developer
description: Implement API endpoints following team conventions
skills:
  - api-conventions
  - error-handling-patterns
---

Implement API endpoints. Follow the conventions and patterns from the preloaded skills.

​

Activer la mémoire persistante

---
name: code-reviewer
description: Reviews code for quality and best practices
memory: user
---

You are a code reviewer. As you review code, update your agent memory with
patterns, conventions, and recurring issues you discover.

• Le prompt système du sous-agent inclut des instructions pour lire et écrire dans le répertoire de mémoire.
• Le prompt système du sous-agent inclut également les 200 premières lignes ou 25 KB de MEMORY.md dans le répertoire de mémoire, selon la première limite atteinte, avec des instructions pour organiser MEMORY.md s’il dépasse cette limite.
• Les outils Read, Write et Edit sont automatiquement activés pour que le sous-agent puisse gérer ses fichiers de mémoire.

• project est la portée par défaut recommandée. Elle rend les connaissances du sous-agent partageables via le contrôle de version.
• Demandez au sous-agent de consulter sa mémoire avant de commencer le travail : « Examinez cette PR et consultez votre mémoire pour les modèles que vous avez vus auparavant. »
• Demandez au sous-agent de mettre à jour sa mémoire après avoir terminé une tâche : « Maintenant que vous avez terminé, enregistrez ce que vous avez appris dans votre mémoire. » Au fil du temps, cela crée une base de connaissances qui rend le sous-agent plus efficace.
• Incluez les instructions de mémoire directement dans le fichier markdown du sous-agent pour qu’il maintienne proactivement sa propre base de connaissances :
  Update your agent memory as you discover codepaths, patterns, library
  locations, and key architectural decisions. This builds up institutional
  knowledge across conversations. Write concise notes about what you found
  and where.
  

​

Règles conditionnelles avec hooks

---
name: db-reader
description: Execute read-only database queries
tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-readonly-query.sh"
---

#!/bin/bash
# ./scripts/validate-readonly-query.sh

INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

# Block SQL write operations (case-insensitive)
if echo "$COMMAND" | grep -iE '\b(INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|TRUNCATE)\b' > /dev/null; then
  echo "Blocked: Only SELECT queries are allowed" >&2
  exit 2
fi

exit 0

chmod +x ./scripts/validate-readonly-query.sh

​

Désactiver des sous-agents spécifiques

{
  "permissions": {
    "deny": ["Agent(Explore)", "Agent(my-custom-agent)"]
  }
}

claude --disallowedTools "Agent(Explore)"

​

Définir les hooks pour les sous-agents

• Dans le frontmatter du sous-agent : définir les hooks qui s’exécutent uniquement pendant que ce sous-agent est actif
• Dans settings.json : définir les hooks au niveau de la session qui se déclenchent également à l’intérieur des sous-agents. Les événements d’outils tels que PreToolUse et PostToolUse se déclenchent pour les appels d’outils du sous-agent de la même manière qu’ils le font dans la conversation principale, et SubagentStart et SubagentStop se déclenchent lorsqu’un sous-agent démarre ou se termine

​

Hooks dans le frontmatter du sous-agent

---
name: code-reviewer
description: Review code changes with automatic linting
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-command.sh"
  PostToolUse:
    - matcher: "Edit|Write"
      hooks:
        - type: command
          command: "./scripts/run-linter.sh"
---

​

Hooks au niveau du projet pour les événements de sous-agent

{
  "hooks": {
    "SubagentStart": [
      {
        "matcher": "db-agent",
        "hooks": [
          { "type": "command", "command": "./scripts/setup-db-connection.sh" }
        ]
      }
    ],
    "SubagentStop": [
      {
        "hooks": [
          { "type": "command", "command": "./scripts/cleanup-db-connection.sh" }
        ]
      }
    ]
  }
}

​

Travailler avec des sous-agents

​

Comprendre la délégation automatique

​

Invoquer les sous-agents explicitement

• Langage naturel : nommez le sous-agent dans votre prompt ; Claude décide s’il faut déléguer
• @-mention : garantit que le sous-agent s’exécute pour une tâche
• À l’échelle de la session : toute la session s’exécute en tant que ce sous-agent via le flag --agent ou le paramètre agent

Use the test-runner subagent to fix failing tests
Have the code-reviewer subagent look at my recent changes

@"code-reviewer (agent)" look at the auth changes

claude --agent code-reviewer

claude --agent security-reviewer

claude --agent my-plugin:security-reviewer

{
  "agent": "code-reviewer"
}

​

Exécuter les sous-agents au premier plan ou en arrière-plan

• Sous-agents au premier plan bloquent la conversation principale jusqu’à la fin. Les demandes de permission vous sont transmises au fur et à mesure.
• Sous-agents en arrière-plan s’exécutent simultanément pendant que vous continuez à travailler. Lorsqu’un sous-agent en arrière-plan atteint un appel d’outil qui nécessite une permission, Claude Code affiche la demande dans votre session principale et nomme le sous-agent qui demande. Approuvez pour laisser le sous-agent continuer, ou appuyez sur Échap pour refuser cet appel d’outil sans arrêter le sous-agent.

​

Quels sous-agents s’exécutent en arrière-plan

• claude -p et le SDK Agent : Claude peut attendre, de sa propre initiative ou lorsque vous le demandez.
• Sessions de terminal interactives, VS Code et application de bureau sur votre machine : pour laisser Claude attendre un sous-agent, désactivez le mode fork, qui est activé par défaut.

​

Laisser Claude attendre un sous-agent

1. Désactivez le mode fork en définissant CLAUDE_CODE_FORK_SUBAGENT sur 0, par exemple dans settings.json :
   {
     "env": {
       "CLAUDE_CODE_FORK_SUBAGENT": "0"
     }
   }
   
2. Exécutez à nouveau claude depuis votre shell, ou ouvrez une nouvelle conversation VS Code.
3. Demandez à Claude d’attendre lorsque vous avez d’abord besoin d’un résultat, par exemple « run the reviewer subagent and wait for its report ».

​

Outils, permissions et résultats des sous-agents en arrière-plan

​

Sous-agents terminés dans le panneau et la liste des tâches

• Lorsqu’un sous-agent se termine avec succès, Claude Code supprime sa ligne immédiatement et, sauf en mode lecteur d’écran, affiche /tasks to see subagents dans le pied de page pendant 30 secondes. Pendant ces 30 secondes, exécutez /tasks et appuyez sur Entrée sur le sous-agent pour ouvrir sa transcription. Avant la v2.1.232, Claude Code gardait la ligne pendant 30 secondes après la fin du sous-agent, comme un échec, et n’affichait aucun indice de pied de page.
• Lorsqu’un sous-agent échoue ou que vous l’arrêtez, Claude Code garde sa ligne pendant 30 secondes. Pour effacer la ligne plus tôt, sélectionnez-la et appuyez sur x.

​

Noms des sous-agents

​

Erreurs API dans les sous-agents

• Premier plan : si une limite de débit, une surcharge ou une erreur serveur coupe un sous-agent qui a déjà produit une sortie texte, l’outil Agent retourne cette sortie partielle avec une note indiquant que le sous-agent a été coupé et n’a pas terminé sa tâche. Un sous-agent qui n’a rien produit, ou dont la seule sortie était des appels d’outils, échoue avec Agent terminated early due to an API error, suivi du détail de l’erreur.
• Arrière-plan : le sous-agent est marqué comme échoué, et le message que Claude reçoit lorsqu’il se termine nomme l’erreur API et inclut la dernière sortie du sous-agent, de sorte que le travail partiel n’est pas perdu.

⚠ This agent switched to <model> because its earlier model could not be used.

​

Analyse de la sortie des sous-agents

• Insertion de barre oblique inverse : l’analyse insère une barre oblique inverse dans le texte qui imite la sortie propre de Claude Code, comme une balise <system-reminder> ou une ligne commençant par Human: ou Assistant:, de sorte que l’imitation se lit comme du texte ordinaire au lieu d’être prise pour une partie de la conversation.
• Ligne de marqueur : l’analyse ajoute une ligne commençant par [harness: subagent output matched instruction-shaped pattern(s): lorsque le rapport imite une balise comme <system-reminder> ou mentionne des paramètres de permission comme bypassPermissions ou --dangerously-skip-permissions. Les mentions de paramètres de permission reçoivent la ligne de marqueur, mais le texte lui-même reste tel qu’écrit.

​

Modèles courants

​

Isoler les opérations à haut volume

Use a subagent to run the test suite and report only the failing tests with their error messages

​

Exécuter des recherches en parallèle

Research the authentication, database, and API modules in parallel using separate subagents

​

Chaîner les sous-agents

Use the code-reviewer subagent to find performance issues, then use the optimizer subagent to fix them

​

Choisir entre les sous-agents et la conversation principale

• La tâche nécessite des allers-retours fréquents ou un raffinement itératif
• Plusieurs phases partagent un contexte important, comme la planification, l’implémentation et les tests
• Vous apportez une modification rapide et ciblée
• La latence est importante. Un sous-agent qui n’est pas un fork commence à zéro et peut avoir besoin de temps pour rassembler le contexte

• La tâche produit une sortie détaillée dont vous n’avez pas besoin dans votre contexte principal
• Vous voulez appliquer des restrictions d’outils ou des permissions spécifiques
• Le travail est autonome et peut retourner un résumé

​

Laisser les sous-agents générer leurs propres sous-agents

• Session de terminal interactive : seul le résumé du sous-agent de niveau supérieur vous revient, car un sous-agent qui lance des sous-agents en arrière-plan attend leurs résultats avant de se terminer.
• claude -p et le SDK Agent : le sous-agent de lancement attend tant que le mode fork est activé. Si vous désactivez le mode fork, les sous-agents imbriqués démarrent en arrière-plan à la place. Le sous-agent de lancement n’attend pas un sous-agent imbriqué en arrière-plan, qui signale à votre conversation principale s’il survit au sous-agent de lancement.

{
  "env": {
    "CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH": "2"
  }
}

​

Limite de sous-agents concurrents

• Un fork en session que vous démarrez avec /subtask prend un emplacement pendant qu’il s’exécute et n’est jamais bloqué par la limite.
• Reprendre un sous-agent qui a déjà terminé prend un nouvel emplacement sans vérifier la limite, de sorte que les reprises peuvent pousser le nombre en cours d’exécution au-delà.

​

Gérer le contexte des sous-agents

​

Ce qui se charge au démarrage

• Prompt système : le propre prompt de l’agent plus les détails d’environnement que Claude Code ajoute, pas le prompt système de Claude Code. Les sous-agents personnalisés définissent le leur dans le corps markdown ou le champ prompt. Les agents intégrés ont des prompts prédéfinis.
• Message de tâche : le prompt de délégation que Claude rédige lorsqu’il confie le travail.
• Fichiers CLAUDE.md : chaque niveau de la hiérarchie CLAUDE.md que la conversation principale charge, y compris ~/.claude/CLAUDE.md, les règles du projet, CLAUDE.local.md, les fichiers de politique gérés, et tous les fichiers AGENTS.md chargés en tant qu’instructions du projet. Les agents Explore et Plan intégrés ignorent cela. Un sous-agent dont la définition définit omitClaudeMd charge uniquement les fichiers de politique gérés, ou aucun lorsque la définition provient des paramètres gérés.
• Statut Git : un instantané que Claude Code lit de votre dépôt lorsque le sous-agent démarre. Pour un sous-agent dans son propre worktree de ce dépôt, l’instantané affiche la branche, le statut et les commits récents du worktree. Absent en dehors d’un dépôt Git ou chaque fois que l’instantané est désactivé ; voir includeGitInstructions. Explore et Plan l’ignorent indépendamment.
• Skills préchargés : contenu complet de tout skill nommé dans le champ skills de l’agent. Les agents intégrés ne préchargent pas les skills.
• Roster des frères et sœurs : un rappel système listant main et tous les autres agents nommés dans la session, chacun une valeur to valide pour SendMessage. Le roster n’apparaît que lorsque les outils du sous-agent incluent SendMessage et qu’au moins un autre agent a un nom, que Claude l’ait nommé lors de sa génération ou qu’il s’exécute en tant que coéquipier équipe d’agents. C’est un instantané pris lorsque le sous-agent démarre, de sorte que les agents nommés plus tard n’apparaissent pas.

• Style de sortie : un sous-agent exécute son propre prompt système, de sorte que votre style de sortie ne façonne pas ses réponses, sauf dans un fork.
• Mémoire automatique : la mémoire automatique de la conversation principale n’est pas chargée. Pour donner à un sous-agent une mémoire persistante qui lui est propre, utilisez le champ memory.
• Taille de la fenêtre de contexte : la fenêtre de contexte d’un sous-agent est dimensionnée par son propre modèle, pas celle du parent. Déléguer à un modèle avec une fenêtre plus petite donne à ce sous-agent la fenêtre plus petite.

​

Reprendre les sous-agents

• Lorsqu’un sous-agent se termine, Claude reçoit son ID d’agent.
• Les agents Explore et Plan intégrés sont ponctuels et ne retournent pas d’ID d’agent, de sorte que Claude ne peut pas les reprendre. Utilisez general-purpose ou un sous-agent personnalisé lorsque vous avez besoin de continuer le travail.
• Lorsqu’un sous-agent s’arrête à sa limite maxTurns, Claude Code marque la sortie retournée comme partielle, et Claude peut reprendre le sous-agent pour continuer son travail.

Use the code-reviewer subagent to review the authentication module
[Agent completes]

Continue that code review and now analyze the authorization logic
[Claude resumes the subagent with full context from previous conversation]

• Compaction de la conversation principale : lorsque la conversation principale se compacte, les transcriptions des sous-agents ne sont pas affectées. Elles sont stockées dans des fichiers séparés.
• Persistance de la session : les transcriptions des sous-agents persistent dans leur session. Vous pouvez reprendre un sous-agent après avoir redémarré Claude Code en reprenant la même session.
• Nettoyage automatique : Claude Code supprime les transcriptions des sous-agents après la période de rétention cleanupPeriodDays, 30 jours par défaut, en suivant les règles de balayage de rétention.

​

Compaction automatique

{
  "type": "system",
  "subtype": "compact_boundary",
  "compactMetadata": {
    "trigger": "auto",
    "preTokens": 167189
  }
}

---
name: log-reader
description: Reads long log files and reports the errors it finds
autoCompactWindow: 200000
---

• La valeur n’est pas inférieure à la fenêtre de compaction automatique dont le sous-agent hériterait autrement : pour compacter plus tôt, définissez une valeur inférieure à cette fenêtre.
• Vous exécutez toute la session en tant que ce sous-agent avec --agent ou le paramètre agent : le champ n’a aucun effet dans ce cas. Pour définir la fenêtre de la session, voir Définir la fenêtre de compaction automatique.

​

Dupliquer la conversation actuelle

/subtask draft unit tests for the parser changes so far

​

Observer et diriger les forks en cours d’exécution

• /compact, /clear et /rewind agissent sur la conversation principale, donc Claude Code vous demande de confirmer avant d’exécuter l’une d’elles depuis cette vue.
• /model et /fast définissent le modèle et le mode rapide de la conversation principale, et non ceux de l’agent visualisé, donc elles ne s’exécutent pas depuis cette vue. Un avis vous en indique la raison.

​

Comment les forks diffèrent des autres sous-agents

​

Désactiver le mode fork

• Empêcher uniquement les forks : ajoutez "Agent(fork)" à permissions.deny dans vos paramètres.
• Désactiver le mode fork : définissez CLAUDE_CODE_FORK_SUBAGENT sur 0, en suivant les étapes de Laisser Claude attendre un sous-agent.

​

Exemples de sous-agents

​

Examinateur de code

---
name: code-reviewer
description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.
tools: Read, Grep, Glob, Bash
model: inherit
---

You are a senior code reviewer ensuring high standards of code quality and security.

When invoked:
1. Run git diff to see recent changes
2. Focus on modified files
3. Begin review immediately

Review checklist:
- Code is clear and readable
- Functions and variables are well-named
- No duplicated code
- Proper error handling
- No exposed secrets or API keys
- Input validation implemented
- Good test coverage
- Performance considerations addressed

Provide feedback organized by priority:
- Critical issues (must fix)
- Warnings (should fix)
- Suggestions (consider improving)

Include specific examples of how to fix issues.

​

Débogueur

---
name: debugger
description: Debugging specialist for errors, test failures, and unexpected behavior. Use proactively when encountering any issues.
tools: Read, Edit, Bash, Grep, Glob
---

You are an expert debugger specializing in root cause analysis.

When invoked:
1. Capture error message and stack trace
2. Identify reproduction steps
3. Isolate the failure location
4. Implement minimal fix
5. Verify solution works

Debugging process:
- Analyze error messages and logs
- Check recent code changes
- Form and test hypotheses
- Add strategic debug logging
- Inspect variable states

For each issue, provide:
- Root cause explanation
- Evidence supporting the diagnosis
- Specific code fix
- Testing approach
- Prevention recommendations

Focus on fixing the underlying issue, not the symptoms.

​

Data scientist

---
name: data-scientist
description: Data analysis expert for SQL queries, BigQuery operations, and data insights. Use proactively for data analysis tasks and queries.
tools: Bash, Read, Write
model: sonnet
---

You are a data scientist specializing in SQL and BigQuery analysis.

When invoked:
1. Understand the data analysis requirement
2. Write efficient SQL queries
3. Use BigQuery command line tools (bq) when appropriate
4. Analyze and summarize results
5. Present findings clearly

Key practices:
- Write optimized SQL queries with proper filters
- Use appropriate aggregations and joins
- Include comments explaining complex logic
- Format results for readability
- Provide data-driven recommendations

For each analysis:
- Explain the query approach
- Document any assumptions
- Highlight key findings
- Suggest next steps based on data

Always ensure queries are efficient and cost-effective.

​

Validateur de requête de base de données

---
name: db-reader
description: Execute read-only database queries. Use when analyzing data or generating reports.
tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-readonly-query.sh"
---

You are a database analyst with read-only access. Execute SELECT queries to answer questions about the data.

When asked to analyze data:
1. Identify which tables contain the relevant data
2. Write efficient SELECT queries with appropriate filters
3. Present results clearly with context

You cannot modify data. If asked to INSERT, UPDATE, DELETE, or modify schema, explain that you only have read access.

#!/bin/bash
# Blocks SQL write operations, allows SELECT queries

# Read JSON input from stdin
INPUT=$(cat)

# Extract the command field from tool_input using jq
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

if [ -z "$COMMAND" ]; then
  exit 0
fi

# Block write operations (case-insensitive)
if echo "$COMMAND" | grep -iE '\b(INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|TRUNCATE|REPLACE|MERGE)\b' > /dev/null; then
  echo "Blocked: Write operations not allowed. Use SELECT queries only." >&2
  exit 2
fi

exit 0

chmod +x ./scripts/validate-readonly-query.sh

​

Étapes suivantes

• Distribuer les sous-agents avec les plugins pour partager les sous-agents entre les équipes ou les projets
• Exécuter Claude Code par programmation avec le SDK Agent pour CI/CD et l’automatisation
• Utiliser les serveurs MCP pour donner aux sous-agents l’accès aux outils et données externes