En bref

Claude Code permet de configurer des agents avec des rôles précis : lecture seule, modèle économique, isolation filesystem, workflows packagés, coordination de session. Ces patterns se combinent. Certains sont triviaux à mettre en place, d’autres ont des contraintes non documentées officiellement. Ce guide documente les 7 patterns disponibles à partir de nos observations et de la documentation officielle.

Les 3 patterns de base

Pattern 1 — System prompt personnalisé

Le moyen le plus simple de spécialiser un agent : lui donner un rôle précis dans le corps Markdown de son fichier de définition.

---
name: reviewer
description: Expert en revue de code. Utilisé pour analyser la qualité.
tools: Read, Grep, Glob
---
Tu es un expert en revue de code. Tu identifies les problèmes de lisibilité,
les bugs potentiels et les violations de conventions. Tu ne modifies rien.

Rôle : orienter le comportement, le ton et le focus de l’agent. Outils autorisés : tous, selon le champ tools. Modèle recommandé : selon la complexité de la tâche. Cas d’usage : spécialiser un agent pour un domaine métier (reviewer, analyste de sécurité, rédacteur de docs). Limite : le system prompt n’isole pas l’agent — il partage le même filesystem et le même contexte que le thread principal.

Pattern 2 — Restriction d’outils

Définir explicitement quels outils un agent peut utiliser via les champs tools et disallowedTools.

---
name: reader
description: Agent en lecture seule. Ne peut pas modifier de fichiers.
tools: Read, Grep, Glob, Bash
disallowedTools: Write, Edit
---

Rôle : limiter les capacités de l’agent de façon déterministe. Modèle recommandé : indépendant du modèle. Cas d’usage : agents d’analyse, de recherche, de revue — tout ce qui ne doit pas modifier le codebase. Limite : la restriction est binaire (un outil entier est autorisé ou non). Pas de granularité sur les sous-commandes d’un outil (ex : autoriser bash mais bloquer git push). Pour ce cas, voir le pattern 5.

Pattern 3 — Modèle dédié

Assigner un modèle différent à chaque agent selon la nature de sa tâche via le champ model du frontmatter (haiku, sonnet, opus, ou un ID complet).

Rôle : optimiser le coût et la latence par type d’opération cognitive. Modèle recommandé : Haiku pour l’extraction et le listage de faits, Sonnet pour l’analyse et la rédaction. Cas d’usage : dans une orchestration multi-agents, ne pas faire tourner Sonnet sur des tâches que Haiku gère aussi bien. Limite : aucune isolation n’est créée par ce paramètre seul. Le choix de modèle n’affecte pas les droits d’accès.

Les 4 patterns avancés

Pattern 4 — Isolation filesystem (worktree)

Lancer un agent dans une copie git isolée du dépôt. Chaque agent travaille dans son propre répertoire de travail sans affecter les autres.

---
name: parallel-worker
isolation: worktree
tools: Read, Edit, Write, Bash
model: opus
---

Rôle : permettre à plusieurs agents d’écrire simultanément sans conflits. Modèle recommandé : Opus uniquement. Nos observations montrent que Sonnet et Haiku échouent silencieusement avec ce pattern : ils rapportent être dans le répertoire isolé, mais leurs modifications s’appliquent en réalité sur le dépôt principal. Ce comportement n’est pas documenté officiellement. Cas d’usage : modifications parallèles sur un même codebase, tâches de refactoring à grande échelle (le skill /batch fourni par Anthropic utilise ce mécanisme en production). Limites :

  • Nécessite un dépôt git initialisé.
  • Overhead de durée significatif : 27-64 secondes avec worktree contre 5-17 secondes sans.
  • Les conflits de merge éventuels sont à résoudre manuellement après coup.

Pattern 5 — Hooks de validation dans le frontmatter

Définir des scripts de validation scopés à l’agent, déclenchés avant ou après chaque utilisation d’un outil.

---
name: db-reader
tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-readonly-query.sh"
---

Le script reçoit l’input de l’outil via stdin et peut bloquer l’exécution (code de sortie 2) ou la laisser passer (code 0).

Rôle : contrôle fin des sous-commandes d’un outil, là où la restriction binaire est insuffisante. Modèle recommandé : indépendant du modèle. Cas d’usage : autoriser Bash mais bloquer les commandes d’écriture SQL, ou les git push, ou les rm -rf. Créer une trace automatique de toutes les actions d’un agent via un hook PostToolUse. Limites :

  • Nécessite de maintenir des scripts de validation dans le dépôt.
  • Complexité disproportionnée pour les cas simples (préférer le pattern 2 si une restriction d’outil entier suffit).
  • Non disponible pour les agents distribués via plugins (restriction de sécurité).

Pattern 6 — Skill fork (workflow packagé)

Créer un skill qui s’exécute dans un agent isolé, avec injection optionnelle de contexte dynamique. Le champ context: fork dans le frontmatter du skill déclenche ce comportement. La syntaxe !commande“ capture la sortie shell au moment de l’invocation et l’injecte dans le prompt de l’agent.

Rôle : packager un workflow récurrent dans une commande réutilisable et partageable. Modèle recommandé : défini par le champ agent (ex : Explore utilise Haiku). Cas d’usage : workflows de recherche, résumés de PR, pipelines de déploiement documentés, tâches récurrentes qui doivent toujours s’exécuter de la même façon. Limites :

  • L’agent créé n’a pas accès à l’historique de la conversation parente.
  • Le prompt est largement fixe (seul $ARGUMENTS est variable). Peu adapté aux tâches ad hoc.
  • Pas de parallélisme natif : un skill fork crée un seul agent.

Pattern 7 — Agent de session

Démarrer une session entière dans l’identité d’un agent prédéfini via claude --agent <nom> ou via le champ agent dans .claude/settings.json. C’est le main thread lui-même qui adopte le system prompt, les restrictions d’outils et le modèle de l’agent.

Ce pattern a une propriété unique : un agent lancé comme main thread peut spawner d’autres agents — ce qu’un sous-agent standard ne peut pas faire — à condition que Agent(...) soit listé dans son champ tools.

Rôle : spécialiser la session entière et, si nécessaire, coordonner d’autres agents depuis le thread principal. Modèle recommandé : Opus pour la coordination (capacité d’instruction plus fiable sur les workflows complexes). Cas d’usage : sessions de revue de code contraintes en lecture seule, projets où toutes les sessions doivent adopter un rôle par défaut, coordination multi-agents. Limites :

  • Le system prompt par défaut de Claude Code est remplacé intégralement. Les instructions de base (conventions git, comportements sécurité) doivent être intégrées dans le prompt de l’agent ou dans un fichier CLAUDE.md.
  • Un seul agent de session par session. Pas de changement en cours de session.

Matrice de décision rapide

BesoinPattern
Spécialiser le rôle d’un agent1 — System prompt
Limiter les outils (un outil entier)2 — Restriction d’outils
Optimiser coût ou vitesse3 — Modèle dédié
Écriture parallèle sans conflits4 — Isolation filesystem
Bloquer des sous-commandes spécifiques5 — Hooks de validation
Packager un workflow récurrent6 — Skill fork
Spécialiser ou coordonner toute la session7 — Agent de session

Les patterns 1, 2 et 3 se combinent systématiquement. Les patterns 4 et 5 s’ajoutent selon les besoins. Le pattern 7 est le seul qui s’applique au thread principal.

Ce qu’il faut retenir

  • Les 3 premiers patterns (system prompt, restriction d’outils, modèle dédié) sont cumulables et couvrent la majorité des cas.
  • L’isolation filesystem (pattern 4) est fiable uniquement avec Opus — Sonnet et Haiku échouent silencieusement d’après nos observations.
  • Les hooks de validation (pattern 5) permettent une granularité fine là où la restriction binaire d’outils ne suffit pas.
  • Les skills fork (pattern 6) sont le meilleur choix pour les workflows récurrents avec injection de contexte dynamique.
  • L’agent de session (pattern 7) est le seul mécanisme permettant au thread principal de coordonner d’autres agents.

Sources