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
• Comment créer les vôtres
• Options de configuration complètes
• Modèles de travail avec les sous-agents
• Sous-agents dupliqués
• Exemples de sous-agents

​

Sous-agents intégrés

​

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

/agents

A code improvement agent 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.

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

​

Configurer les sous-agents

​

Utiliser la commande /agents

• Afficher tous les sous-agents disponibles (intégrés, utilisateur, projet et plugin)
• Créer de nouveaux sous-agents avec une configuration guidée ou une génération Claude
• Modifier la configuration des sous-agents existants et l’accès aux outils
• Supprimer les sous-agents personnalisés
• Voir quels sous-agents sont actifs en cas de doublons

​

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."
  }
}
'@

​

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

​

Champs de frontmatter pris en charge

​

Choisir un modèle

• Alias de modèle : Utilisez l’un des alias disponibles : sonnet, opus ou haiku
• ID de modèle complet : Utilisez un ID de modèle complet tel que claude-opus-4-8 ou claude-sonnet-4-6. Accepte les mêmes valeurs que le drapeau --model
• inherit : Utilisez le même modèle que la conversation principale
• Omis : S’il n’est pas spécifié, par défaut inherit (utilise le même modèle que la conversation principale)

1. La variable d’environnement CLAUDE_CODE_SUBAGENT_MODEL, si elle est définie
2. Le paramètre model par invocation
3. Le frontmatter model de la définition du sous-agent
4. Le modèle de la conversation principale

​

Contrôler les capacités des sous-agents

​

Outils disponibles

• Agent
• AskUserQuestion
• EnterPlanMode
• ExitPlanMode, sauf si le permissionMode du sous-agent est plan
• ScheduleWakeup
• WaitForMcpServers

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

---
name: no-writes
description: Inherits every tool except file writes
disallowedTools: Write, Edit
---

​

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

​

Modes de permission

​

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.

• L’invite système du sous-agent inclut des instructions pour lire et écrire dans le répertoire de mémoire.
• L’invite 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 ce qui est le moins important, 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.

Conseils de mémoire persistante

• project est la portée par défaut recommandée. Elle rend les connaissances du sous-agent partageables via le contrôle de version. Utilisez user lorsque les connaissances du sous-agent sont largement applicables dans les projets, ou local lorsque les connaissances ne doivent pas être enregistrées dans 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

​

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

1. Dans le frontmatter du sous-agent : Définir les hooks qui s’exécutent uniquement pendant que ce sous-agent spécifique est actif
2. Dans settings.json : Définir les hooks qui s’exécutent dans la session principale lorsque les sous-agents démarrent ou s’arrêtent

​

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 $TOOL_INPUT"
  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 les sous-agents

​

Comprendre la délégation automatique

​

Invoquer les sous-agents explicitement

• Langage naturel : nommez le sous-agent dans votre invite ; Claude décide s’il faut déléguer
• @-mention : garantit que le sous-agent s’exécute pour une tâche
• Au niveau de la session : la session entière utilise l’invite système, les restrictions d’outils et le modèle de ce sous-agent via le drapeau --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

• Les sous-agents au premier plan bloquent la conversation principale jusqu’à la fin. Les invites de permission vous sont transmises au fur et à mesure qu’elles se produisent.
• Les sous-agents en arrière-plan s’exécutent simultanément pendant que vous continuez à travailler. Ils s’exécutent avec les permissions déjà accordées dans la session et auto-refusent tout appel d’outil qui sinon demanderait une permission. Si un sous-agent en arrière-plan doit poser des questions de clarification, cet appel d’outil échoue mais le sous-agent continue.

• Demander à Claude de « run this in the background »
• Appuyer sur Ctrl+B pour mettre une tâche en arrière-plan

​

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 la recherche 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 (planification → implémentation → test)
• Vous apportez une modification rapide et ciblée
• La latence est importante. Les sous-agents commencent à zéro et peuvent 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 souhaitez appliquer des restrictions d’outils ou des permissions spécifiques
• Le travail est autonome et peut retourner un résumé

​

Gérer le contexte du sous-agent

​

Ce qui se charge au démarrage

• Invite système : l’invite propre de l’agent plus les détails d’environnement que Claude Code ajoute, pas l’invite système complète de Claude Code. Les sous-agents personnalisés définissent la leur dans le corps markdown ou le champ prompt. Les agents intégrés ont des invites prédéfinies.
• Message de tâche : l’invite de délégation que Claude écrit lorsqu’il confie le travail.
• CLAUDE.md et mémoire : chaque niveau de la hiérarchie de mémoire que la conversation principale charge, y compris ~/.claude/CLAUDE.md, les règles du projet, CLAUDE.local.md, et les fichiers de politique gérés. Les agents Explore et Plan intégrés ignorent cela.
• Statut Git : un instantané pris au début de la session parent. Absent lorsque le répertoire de travail n’est pas un référentiel Git ou lorsque includeGitInstructions est false. Explore et Plan l’ignorent de toute façon.
• 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.

​

Reprendre les sous-agents

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 de sous-agent ne sont pas affectées. Elles sont stockées dans des fichiers séparés.
• Persistance de session : Les transcriptions de sous-agent persistent au sein de leur session. Vous pouvez reprendre un sous-agent après le redémarrage de Claude Code en reprenant la même session.
• Nettoyage automatique : Les transcriptions sont nettoyées en fonction du paramètre cleanupPeriodDays (par défaut : 30 jours).

​

Auto-compaction

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

​

Dupliquer la conversation actuelle

• Claude génère un fork chaque fois qu’il utiliserait autrement le sous-agent general-purpose. Les sous-agents nommés tels que Explore se génèrent comme avant.
• Chaque génération de sous-agent s’exécute en arrière-plan, qu’il s’agisse d’un fork ou d’un sous-agent nommé. Définissez CLAUDE_CODE_DISABLE_BACKGROUND_TASKS sur 1 pour garder les générations synchrones.

/fork draft unit tests for the parser changes so far

​

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

​

Comment les forks diffèrent des sous-agents nommés

​

Limitations

​

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