Les sub-agents & Les Core 4 par agent délégué

Les sub-agents : un contexte partiellement forké

L’idée en une phrase

Un sous-agent est un agent secondaire qui s’exécute dans sa propre fenêtre de contexte, isolée de l’agent principal : il fait le travail lourd et bruyant de son côté et ne renvoie que le résumé. C’est le premier levier Delegate du livre — annoncé à la fin du tier débutant (chapitre 5) : au lieu de réduire ce qui entre dans une seule fenêtre, on déporte le bruit vers un contexte séparé.

Analogie : un chef de chantier qui envoie un ouvrier fouiller l’entrepôt. L’ouvrier déballe cinquante cartons, se salit les mains, remet tout en place — puis revient dire « la pièce est dans la travée 3, étagère B ». Le chef reçoit une phrase, pas les cinquante cartons. Le désordre est resté dans l’entrepôt, jamais sur son bureau ; son plan de travail reste net pour la suite.

Points clés

• Un sous-agent est un simple fichier Markdown à frontmatter YAML, dans .claude/agents/ (scope projet, versionné et partagé avec l’équipe) ou ~/.claude/agents/ (scope personnel, présent dans tous les projets). Depuis Claude Code v2.1.198, /agents n’ouvre plus d’assistant interactif : il rappelle de demander à Claude d’écrire le fichier, ou d’éditer .claude/agents/ soi-même. Les fichiers et emplacements, eux, sont inchangés.
• Fenêtre fraîche, pas un clone de la conversation. Un sous-agent (hors fork) ne voit ni l’historique de la conversation, ni les fichiers déjà lus, ni les skills déjà invoqués. Sa fenêtre de départ contient : un message de délégation (le résumé de tâche que l’agent principal rédige), la hiérarchie CLAUDE.md (chapitre 5) et un instantané du git status.
• « Partiellement forké » : une tranche choisie, pas une copie. D’où le terme — ce n’est pas la conversation entière qui est dupliquée, seulement un contexte de projet plus un résumé. Le fork complet, qui hérite vraiment de la conversation du parent, est un mode distinct et explicite (via /subtask), pas le comportement par défaut.
• Seul le résumé revient. Tout le contenu brut manipulé — sorties de grep, dizaines de fichiers, logs — vit et meurt dans la fenêtre du sous-agent. L’agent principal ne récupère que le rapport final : c’est là toute l’économie.

Exemple concret

Question posée à l’agent : « où le rate-limiting est-il géré dans cette base de code ? ». Sans délégation, l’agent principal explore lui-même : grep -r, ouverture d’une quinzaine de fichiers, lecture d’un middleware et de ses tests — soit ~45 000 tokens de contenu brut chargés dans sa fenêtre (~22 % d’une fenêtre de 200k), dont il ne réutilisera presque rien une fois la réponse trouvée. Ce bruit reste ensuite en place et dilue son attention (lois d’échelle inverses, chapitre 2). Avec délégation à un sous-agent researcher, ces ~45 000 tokens vivent dans la fenêtre du sous-agent ; il renvoie un rapport de ~600 tokens (réponse + chemin:ligne). L’agent principal paie ~600 tokens au lieu de ~45 000 : ~44 000 tokens (~22 % d’une fenêtre de 200k) qui ne sont jamais entrés dans la fenêtre principale.

Qui porte le bruit de la recherche ?

Config — un sous-agent minimal

---
name: researcher
description: Localise une information dans la base de code. Use proactively.
tools: Read, Grep, Glob
model: haiku
---
Explore en lecture seule, puis rends un rapport de 10 lignes max : reponse +
fichiers concernes (`chemin:ligne`). Ne recopie aucun contenu brut.

Le corps Markdown est le prompt système du sous-agent ; le frontmatter en fixe le nom, la règle de délégation (description), les outils et le modèle. Placé dans .claude/agents/researcher.md, il est détecté en quelques secondes, sans redémarrage.

Piège courant : croire qu’« un sous-agent voit tout mon historique et les fichiers déjà lus » est inexact. Hors fork, il démarre dans une fenêtre fraîche et isolée : il ne reçoit qu’un message de délégation (le résumé que l’agent principal écrit), plus CLAUDE.md et le git status. Le fork complet — qui, lui, hérite de la conversation du parent — est un mode distinct et explicite, pas le défaut. C’est précisément le sens de « partiellement forké ».

Garder le contrôle des Core 4 par agent délégué

L’idée en une phrase

Déléguer proprement, ce n’est pas « lancer un assistant » : c’est réinstancier les Core 4 (Modèle, Prompt, Outils, Contexte — chapitre 3) pour ce worker, afin qu’il soit lui aussi un agent concentré (chapitre 1). Chaque sous-agent est une occasion de tailler ses quatre primitives à la tâche — c’est ce qui fait qu’un Delegate paie réellement, au lieu de simplement déplacer le bruit ailleurs.

Analogie : confier une mission à un intérimaire. On ne lui tend pas le trousseau de clés complet du bâtiment : on choisit le bon profil (le modèle), une fiche de mission courte et précise (le prompt), l’accès aux seules pièces utiles (les outils) et le dossier strictement nécessaire (le contexte). Un intérimaire suréquipé et sous-briefé coûte plus cher et rend un travail plus flou qu’un intérimaire cadré.

Points clés

• Modèle → model:. haiku, sonnet, opus, fable, un ID complet, ou inherit (défaut). Un tri de texte volumineux tourne bien sur un petit modèle — moins cher, plus rapide ; et la fenêtre du sous-agent est dimensionnée par son propre modèle, donc taillée à la tâche.
• Prompt → le corps Markdown. Ce corps devient le prompt système du sous-agent (il ne reçoit pas le prompt système complet de Claude Code). C’est là qu’on borne la mission et qu’on impose un format de sortie court — le levier qui garantit un résumé compact plutôt qu’un pavé.
• Outils → tools:. Restreindre à Read, Grep, Glob, c’est le moindre privilège (pas d’écriture accidentelle) et moins de schémas d’outils injectés au démarrage du sous-agent (le coût des outils, chapitre 3). Champ omis = tous les outils hérités.
• Contexte → la fenêtre fraîche + le message de délégation. On décide de ce qui entre : le résumé de tâche, éventuellement des skills préchargés (skills:). Le bruit, lui, reste dehors.
• Le piège des défauts. Sans model, le sous-agent hérite du gros modèle du parent ; sans tools, il hérite de toute la panoplie. Un sous-agent non réglé est un généraliste, pas un spécialiste.

Exemple concret

Deux façons de déclarer le même researcher. Non réglé : ni model ni tools ni corps ciblé → il hérite du modèle du parent (mettons opus) et de tous les outils (Write, Edit, Bash compris) ; il part explorer large, peut modifier des fichiers par mégarde, et renvoie un résumé verbeux de ~3 000 tokens. Réglé : model: haiku (tri de texte sur un petit modèle), tools: Read, Grep, Glob (lecture seule — quelques schémas d’outils en moins au démarrage, de l’ordre de ~1 500 tokens économisés dans la fenêtre du sous-agent), corps de ~15 lignes qui impose « rapport de 10 lignes max, pas de contenu brut ». Résultat : un spécialiste qui rend ~600 tokens utiles au lieu de ~3 000 bruités, sans aucun risque d’écriture. Même délégation, deux qualités d’attention.

Les Core 4 d’un agent délégué

Config — les quatre boutons, et ce qui arrive si on les omet

---
name: researcher
description: Recherche de localisation, lecture seule. Use proactively.  # -> delegation
model: haiku            # Core 4 · Modele  — sans cette ligne : inherit (le gros modele du parent)
tools: Read, Grep, Glob # Core 4 · Outils  — sans cette ligne : TOUT est herite (Write, Edit, Bash inclus)
---
# Core 4 · Prompt  : ce corps EST le prompt systeme du sous-agent. Il borne la
#                    mission et impose un format de sortie court (le rapport).
# Core 4 · Contexte : fenetre fraiche et isolee ; seul le message de delegation
#                     (un resume de la tache) y entre — pas l'historique du parent.

Piège courant : croire que « déléguer réduit forcément les tokens » est inexact. Par défaut, un sous-agent hérite du modèle du parent (model: inherit) et de tous les outils ; sans corps de prompt ciblé ni format de sortie imposé, il explore large et peut renvoyer un résumé long et bruité — voire modifier des fichiers. La délégation ne paie que si l’on règle ses Core 4 : petit modèle pour le tri, outils en lecture seule, prompt qui borne la mission et la sortie.

Fil rouge — Reduce ou Delegate ?

Ce chapitre fait basculer le livre du côté Delegate. Un sous-agent est une fenêtre de contexte séparée : le travail lourd et bruyant — grep sur toute la base, lecture de dizaines de fichiers, logs — s’y déroule, et seul le résumé revient dans l’agent principal. Sur l’exemple, ~45 000 tokens de contenu brut (~22 % d’une fenêtre de 200k) ne sont jamais entrés dans la fenêtre principale ; il n’en revient que ~600. Ce n’est pas du Reduce (on ne coupe pas ce qui entre dans une même fenêtre) mais du Delegate : on déporte le bruit vers un contexte isolé. Et déléguer proprement, c’est réinstancier les Core 4 (chapitre 3) pour ce worker — petit modèle, prompt ciblé, outils minimaux, contexte amorcé — pour qu’il soit lui aussi un agent concentré (chapitre 1). L’agent principal, lui, garde une fenêtre dense et son attention intacte (chapitre 2).

Travaux pratiques

À chaque leçon, un petit artefact à déposer dans ton .claude/ — commande, sous-agent, hook, mémo… — pour te bâtir, au fil du livre, une boîte à outils de context engineering réutilisable.

Un sous-agent maison — researcher

Le tier débutant a rempli le tiroir des commandes (/prime, chapitre 5). On ouvre ici celui des sous-agents. Ce researcher incarne Delegate de bout en bout : il absorbe le travail bruyant de recherche — grep, lecture de dizaines de fichiers — dans sa fenêtre isolée, et ne renvoie à l’agent principal qu’un rapport compact. Ses Core 4 sont réglés : petit modèle pour le tri (haiku), outils en lecture seule (Read, Grep, Glob — aucune écriture possible), et un prompt qui impose le format de sortie. À déposer dans .claude/agents/researcher.md.

---
name: researcher
description: >-
  Agent de recherche en lecture seule. Localise une information dans la base de
  code (« ou est gere X ? », « qui appelle Y ? »). Use proactively des qu'une
  recherche risque d'inonder la fenetre principale de grep, de logs et de fichiers.
tools: Read, Grep, Glob
model: haiku
---

Tu es un agent de recherche en LECTURE SEULE. Ta mission : localiser dans la base
de code l'information demandee, puis rendre un rapport COURT. Tu ne modifies rien.

# Methode
- Pars du message de delegation : il contient la question et le contexte utile.
- Cible avec Grep/Glob, confirme avec Read. N'ouvre QUE les fichiers necessaires.
- Ne recopie jamais de gros blocs de code dans ton rapport : cite `chemin:ligne`.

# Rapport (obligatoire, 10 lignes maximum)
1. Reponse directe a la question, en une a deux phrases.
2. Emplacements pertinents, sous forme `chemin/fichier:ligne`.
3. Le cas echeant, une piste de suite — rien de plus. Pas de contenu brut,
   pas de digression, pas de reformulation de la question.

Invoque-le en demandant à Claude une recherche (« où le rate-limiting est-il géré ? ») : la description déclenche la délégation, le travail bruyant (~45 000 tokens de fichiers) reste dans la fenêtre du sous-agent, et l’agent principal ne reçoit que le rapport (~600 tokens). Soit ~44 000 tokens (~22 % d’une fenêtre de 200k) qui n’entrent jamais dans la fenêtre principale — Delegate appliqué, attention préservée pour la vraie tâche.