Sous-agents Claude Code : guide pratique pour déléguer sans perdre le contrôle

Quand un travail Claude Code devient volumineux, ce n’est généralement pas le modèle qui échoue en premier. C’est la façon de découper le travail. Une seule conversation qui cherche, rédige, traduit, modifie du code, lance des vérifications et relit dix fichiers localisés devient vite lourde. L’agent relit les mêmes fichiers, les logs remplissent le contexte, et la livraison finale manque de preuves.

Les sous-agents sont utiles parce qu’ils permettent de déléguer une tâche bornée dans un contexte séparé. Déléguer ne veut pas dire “laisse un autre agent tout faire”. Cela veut dire fournir un petit contrat : objectif, fichiers autorisés, fichiers interdits, critères de fin et format de retour. Sans ce contrat, le travail parallèle devient facilement du travail en double.

Ce guide s’appuie sur le flux de production de ClaudeCodeLab : écrire un article canonical en japonais, le localiser dans dix langues, vérifier les templates de prompt et relire les risques avant publication. Les mêmes principes s’appliquent aux changements de code, à la documentation, aux migrations et aux préparations de release.

Qu’est-ce qu’un sous-agent

Un sous-agent est un travailleur spécialisé qui s’exécute hors du contexte principal. Le contexte est la mémoire de travail visible par Claude : conversation, fichiers lus, sorties de commandes, règles du projet et résumés intermédiaires. Quand une tâche produit beaucoup de résultats de recherche ou de logs, un sous-agent peut faire la lecture lourde et ne renvoyer que le résumé utile.

Pour la référence officielle, consultez les pages Claude Code sur les subagents, la memory et les slash commands. Les points opérationnels à retenir : un sous-agent démarre avec un contexte isolé, les agents de projet peuvent vivre dans .claude/agents/, et une réponse trop longue consomme tout de même le contexte principal une fois renvoyée.

Terme	Sens pratique
sous-agent	Travailleur spécialisé pour recherche, implémentation, traduction ou revue
contexte	Mémoire de travail actuellement visible par Claude
disjoint write set	Ensemble de fichiers éditables qui ne chevauche pas celui d’un autre worker
explorer	Agent de recherche en lecture seule
worker	Agent qui modifie seulement les fichiers assignés
handoff contract	Contrat de portée, limites, fin attendue et format de livraison

Quand déléguer

Les sous-agents ne sont pas une solution automatique. Une petite correction peut devenir plus lente si chaque agent doit reconstruire le contexte. La bonne question est : séparer le contexte a-t-il de la valeur, et peut-on découper les fichiers sans chevauchement ?

Travail	Déléguer ?	Pourquoi
Localiser un article dans dix langues	Oui	Chaque langue a son fichier et ses critères de qualité
Explorer un grand codebase	Oui	Le fil principal a besoin de la carte, pas de tous les résultats
Corriger une faute dans un fichier	Non	Le coût de coordination dépasse le travail
Refactoriser l’authentification	Peut-être	Commencer par un explorer pour mesurer l’impact
Concevoir une fonctionnalité floue	Pas encore	Clarifier les exigences dans le fil principal

Ma règle pratique : déléguer seulement si la tâche génère beaucoup d’information intermédiaire, si chaque worker peut être limité à des fichiers explicites et si le résultat peut revenir sous forme de tableau, checklist ou reçu court.

Le modèle de base : explorer, worker, reviewer

Pour un travail sérieux, ne commencez pas par plusieurs agents qui éditent. Commencez par un explorer. Il lit en mode lecture seule, repère les fichiers importants, les conventions existantes et les risques, puis propose les write sets. Ensuite les workers modifient des ensembles séparés. Enfin un reviewer ou un verification agent relit sans modifier.

flowchart TD
  A["Main: goal and constraints"] --> B["Explorer: read only, map scope"]
  B --> C["Main: decide disjoint write sets"]
  C --> D["Worker: canonical article or code module"]
  C --> E["Worker: localized files or separate module"]
  D --> F["Reviewer: quality, metadata, verification"]
  E --> F
  F --> G["Main: final checks and handoff"]

Cet ordre évite l’erreur la plus courante : plusieurs agents lisent et modifient les mêmes fichiers parce que la consigne était trop large.

Cas 1 : production d’articles localisés

Dans ClaudeCodeLab, le flux le plus sûr consiste à finaliser l’article canonical japonais, puis à localiser le guide complet. Si le canonical est trop mince, toutes les traductions seront minces. S’il contient exemples, pièges, templates et CTA, chaque langue peut rester riche tout en sonnant naturelle.

Rôle	Fichiers autorisés	Travail
ja-worker	site/src/content/blog/claude-code-subagent-patterns.mdx	Construire structure, exemples, prompts et CTA
western-locale-worker	blog-en, blog-es, blog-fr, blog-de, blog-pt	Localiser naturellement sans résumer
asia-locale-worker	blog-zh, blog-ko, blog-hi, blog-id	Adapter les termes aux lecteurs locaux
review-agent	dix fichiers du slug, lecture seule	Vérifier frontmatter, mojibake, liens, fences et risque de publication

Prompt prêt à coller :

Use a translation subagent for the assigned locale files only.

Source:
- Japanese canonical file: site/src/content/blog/claude-code-subagent-patterns.mdx

Allowed write set:
- site/src/content/blog-en/claude-code-subagent-patterns.mdx
- site/src/content/blog-es/claude-code-subagent-patterns.mdx

Rules:
- Do not summarize. Localize the full guide.
- Keep frontmatter valid and preserve heroImage.
- Use natural SEO terms for each language.
- Keep prompt templates copy-pasteable.
- Do not edit Japanese or other locale files.

Return:
- Files changed
- Localization choices
- Any terms that may need human review
- Checks performed

Cas 2 : vérifier les exemples de code d’un article

Le rédacteur et l’agent de vérification ne doivent pas avoir le même rôle. Le rédacteur construit l’explication. Le verification agent extrait les blocs de code, vérifie la syntaxe, valide les chemins et indique ce qui est réellement copiable.

---
name: article-reviewer
description: Reviews ClaudeCodeLab articles for originality, implementation detail, SEO, and publication risk.
tools: Read, Grep, Glob
---

You review article drafts critically.
Check whether the draft has concrete examples, pitfalls, working prompts,
official links, internal links, and a clear CTA.
Return findings first, then a short pass/fail recommendation.

Cette définition peut être placée dans .claude/agents/article-reviewer.md. Le name doit rester unique et la description doit expliquer quand utiliser l’agent. Évitez d’écrire un prompt système énorme ; les règles durables sont plus faciles à maintenir dans CLAUDE.md ou dans une checklist d’équipe. Voir aussi le guide de gestion du contexte et les bonnes pratiques CLAUDE.md.

Cas 3 : changements de code avec write sets séparés

Le même principe fonctionne pour le code. Imaginons un site de blog où il faut modifier les cartes d’articles, la génération OGP et la sélection des articles liés. Ces zones sont connectées, mais les fichiers peuvent être séparés.

We will use three workers with disjoint write sets.

Worker A:
- May edit: site/src/components/BlogCard.astro
- Must not edit: layouts, pages, content files
- Goal: improve card metadata rendering only

Worker B:
- May edit: site/src/pages/og/[...slug].png.ts
- Must not edit: components or article files
- Goal: verify OGP title and hero behavior

Worker C:
- May edit: site/src/lib/relatedPosts.ts
- Must not edit: components, pages, content files
- Goal: improve related-post selection without changing routes

All workers return a handoff receipt with changed files, reasoning, tests, and risks.

“Améliore l’UI en parallèle” est une consigne faible. Une consigne solide nomme les fichiers autorisés, les fichiers interdits et les preuves attendues.

Cas 4 : reviewer et verification agent en lecture seule

Le dernier agent devrait souvent être en lecture seule. Un reviewer cherche la valeur lecteur, les manques SEO, les répétitions et les pièges absents. Un verification agent vérifie les métadonnées, les liens, les commandes, les code fences et le risque de build.

Use a review subagent in read-only mode.

Scope:
- Read only these 10 localized files for slug claude-code-subagent-patterns.
- Do not edit anything.

Review checklist:
- description is 120 characters or fewer
- updatedDate is 2026-06-02
- heroImage is retained
- each locale is a full localized article, not a thin summary
- at least 3 concrete use cases are present
- pitfalls and failure modes are concrete
- code fences are balanced
- official external links and internal links are present
- CTA is natural and relevant

Return findings by severity with file paths and line numbers where possible.

Cette étape est précieuse en publication multilingue. Un texte peut être naturel tout en gardant une date ancienne, un bloc non fermé ou un CTA absent. Pour le code, combinez-la avec la checklist de code review Claude Code.

Templates de délégation

Prompt d’orchestration :

You are the orchestrator. Before using subagents, create a delegation plan.

Goal:
- [one sentence goal]

Hard constraints:
- Work only on: [exact files or directories]
- Do not edit: [out of scope]
- Preserve: [metadata, public API, routes, screenshots, etc.]
- Verification required: [commands or manual checks]

Ask explorer agents to read first. Do not start workers until write sets are disjoint.
For every worker, define:
- allowed write set
- forbidden files
- expected output
- done condition

Final response must include:
- changed files
- checks run
- remaining risks

Prompt d’exploration :

Use an explorer subagent in read-only mode.

Task:
- Map the current state of [feature/article/slug].
- Find existing conventions, related files, internal links, and quality gaps.

Rules:
- Do not edit files.
- Prefer search and targeted reads over full-directory dumps.
- Return only the useful summary, not raw command output.

Return:
- Files that matter
- Existing patterns to follow
- Risks or unclear requirements
- Suggested write sets for workers

Prompt pour un worker :

Use a worker subagent for this isolated edit.

Allowed write set:
- [file 1]
- [file 2]

Forbidden:
- Do not edit files outside the allowed write set.
- Do not stage, commit, push, deploy, or rewrite unrelated changes.
- If the task requires another file, stop and report why.

Implementation goal:
- [specific behavior or article quality outcome]

Return a handoff receipt:
- Files changed
- Summary of changes
- Commands or checks run
- Evidence of success
- Remaining risk

Pièges fréquents

Le premier piège est de paralléliser avant d’avoir des limites. Si trois workers reçoivent “améliore l’article”, ils toucheront tous le titre, l’introduction, les exemples et le CTA. Il y aura plus de diff, mais moins de contrôle.

Le deuxième piège est de renvoyer trop de contenu. Le sous-agent protège le contexte pendant son travail, mais son résultat final revient dans le fil principal. Demandez des décisions, tableaux et reçus, pas des logs complets.

Le troisième piège est un contrat trop vague. “Traduis naturellement” ne suffit pas. Dites “ne pas résumer”, “préserver le frontmatter”, “garder les pièges”, “utiliser les termes SEO locaux” et “signaler les phrases à relire par un natif”.

Le quatrième piège est de laisser l’implémenteur valider ses propres hypothèses. Le reviewer doit lire avec scepticisme et commencer par les problèmes.

Le cinquième piège est d’oublier le chargement des agents. Les fichiers dans .claude/agents/ peuvent nécessiter une nouvelle session pour être disponibles. Pour un agent réutilisable, une définition courte en fichier est souvent meilleure qu’un long prompt ponctuel.

Budget de contexte

Les sous-agents n’économisent le contexte que si vous limitez ce qui revient.

Context budget rule:
- Explorer returns at most 20 bullets and 1 table.
- Worker returns changed files, decisions, and checks only.
- Reviewer returns findings by severity, no full rewritten article.
- Logs longer than 80 lines must be summarized.
- If uncertainty remains, ask one focused question instead of dumping raw output.

Le livrable peut être long. Le handoff doit rester court. Sinon, la conversation principale se remplit de brouillons, notes de traduction et logs de vérification.

Sous-agent relecteur prêt à copier

Le premier sous-agent le plus sûr est un relecteur en lecture seule. Ce script crée .claude/agents/article-reviewer.md; il peut inspecter les brouillons et signaler les risques, mais pas modifier les fichiers. C’est idéal pour ajouter une revue critique avant publication.

mkdir -p .claude/agents
cat > .claude/agents/article-reviewer.md <<'EOF'
---
name: article-reviewer
description: Reviews ClaudeCodeLab articles for originality, implementation detail, SEO, and publication risk.
tools: Read, Grep, Glob
---

Review the assigned files only. Do not edit.

Checklist:
- title and description match the search intent
- intro gives a concrete reader problem in the first three lines
- examples, pitfalls, official links, internal links, and CTA are present
- code fences are balanced and labeled
- the article is not a thin summary or duplicated from another page

Return:
- findings by severity
- pass/fail recommendation
- one highest-leverage fix
EOF

Checklist de délégation

# Subagent Delegation Checklist

## Before delegation
- [ ] Goal is one sentence.
- [ ] In-scope files are listed explicitly.
- [ ] Out-of-scope files and actions are listed explicitly.
- [ ] Explorer runs before worker when scope is unclear.
- [ ] Write sets do not overlap.

## During work
- [ ] Each worker edits only allowed files.
- [ ] Large outputs are summarized.
- [ ] Any need to expand scope is reported before editing.
- [ ] Prompts include done conditions.

## Review
- [ ] Reviewer runs in read-only mode.
- [ ] Metadata and links are checked.
- [ ] Code fences and commands are checked.
- [ ] Localization is full, not summarized.
- [ ] Remaining risks are written in the handoff.

Résultat observé

Dans le travail éditorial de ClaudeCodeLab, le plus grand gain n’a pas été une traduction plus rapide. Le vrai gain est venu de la séparation entre canonical, workers de langue et reviewer en lecture seule. Avant, on obtenait facilement une langue forte et neuf versions trop courtes. Avec des règles explicites de non-résumé, des write sets fixes et un reçu de vérification, la revue finale devient beaucoup plus concrète.

Si votre équipe adopte Claude Code, présentez les sous-agents comme une méthode de conception du travail, pas comme un bouton magique. ClaudeCodeLab structure ces contrats de délégation, rubriques de revue et habitudes de contexte dans ses pages training et product templates pour les équipes.