« J'utilise Claude Code, mais à mesure que l'échelle augmente, le contexte déborde et la précision chute. »
« Au final, donner moi-même des instructions de correction à l'IA est devenu le principal goulot d'étranglement. »
Beaucoup de gens sont probablement bloqués à ce stade. J'étais comme ça au début, à jeter du code, des tests et des discussions de conception dans une seule session, et à voir la précision de Claude baisser à mesure que l'historique s'allongeait.
Ce que j'ai récemment réalisé, c'est que Claude Code lui-même fournit officiellement trois mécanismes pour exécuter plusieurs sessions en parallèle.
De plus, ces trois mécanismes sont similaires mais distincts ; les confondre peut entraîner des accidents. À l'inverse, si vous les divisez par rôle, vous pouvez passer du côté « donneur d'ordres » sans écrire une seule ligne de code vous-même.
Aujourd'hui, je vais organiser ces trois mécanismes et la bonne façon de fixer les limites des rôles tout en consultant les informations principales de la documentation officielle.
Plus précisément, je vais décomposer cela en une configuration où 8 sessions sont réparties sur trois couches : Commande, Implémentation et Qualité.
En prime, j'expliquerai aussi, à l'aide d'informations principales, pourquoi des explications courantes comme « écrire des ID de rôle dans CLAUDE.md pour changer » ou « partager la mémoire avec SQLite » s'écartent légèrement du mécanisme officiel.
Je m'appelle tatsuki (@nobel_824).
J'accompagne les PME dans l'utilisation de l'IA, en aidant à l'implémentation métier de Claude / Codex tout en utilisant moi-même Claude Code à longueur de journée. L'opération en parallèle est un domaine que j'aborde quotidiennement, tant pour le travail que pour les projets personnels.
Article connexe : Introduction au Vibe Coding : 6 étapes pour les non-codeurs afin de créer des applications avec Claude. L'ère de la production en interne en un week-end
https://note.com/nobel/n/n8192ec07d689
1. Pourquoi « Fourrer Tout dans une Seule Session » Échoue
Le premier piège est de surcharger une seule session avec trop d'informations. Aussi intelligent que soit le modèle Claude, il rencontre des limites structurelles.
Plus précisément, vous rencontrez ces trois problèmes :
- Contamination du contexte : Lorsque le code d'implémentation, les tests, l'historique de débogage et les discussions de conception se mélangent dans le même contexte, la base du raisonnement devient trouble et la précision chute.
- Conflit d'instructions : Si « implémenter en priorisant la rapidité » et « être strict sur la sécurité » existent au même endroit, les jugements deviennent approximatifs.
- Gonflement des tokens : Charger un historique massif à chaque fois est une perte de temps et d'argent.
La solution est l'idée de « devenir un seul commandant et d'aligner des Claudes spécialisés ». C'est similaire à un CTO qui a un Tech Lead et un Backend Lead, mais l'important n'est pas l'ambiance : c'est d'utiliser correctement les mécanismes officiels de Claude Code.
Une action que vous pouvez entreprendre aujourd'hui : Pensez à votre session actuelle et vérifiez si « implémentation », « recherche » et « révision » coexistent dans un seul contexte. Si c'est le cas, c'est votre point de départ pour les diviser.
2. Corriger les « Trois Mécanismes Parallèles » Fournis Officiellement
C'est le cœur de l'article. Claude Code dispose de trois mécanismes pour le parallélisme, chacun avec une portée différente.
Le premier est le sous-agent (une IA auxiliaire qui s'exécute dans un contexte séparé de la conversation principale). Il exécute des tâches secondaires comme la recherche ou les révisions en utilisant sa propre fenêtre de contexte, une invite système dédiée et des permissions d'outils limitées, et ne renvoie qu'un résumé des résultats à la session principale. Le point clé est que les sous-agents s'exécutent dans la même session, ne font rapport qu'au principal, et les sous-agents ne communiquent pas entre eux (Documentation officielle).
Le deuxième est les équipes d'agents (un mécanisme où plusieurs sessions Claude Code collaborent en tant qu'équipe). Une session devient le chef d'équipe et génère des coéquipiers, collaborant via une liste de tâches partagée et une boîte aux lettres. Contrairement aux sous-agents, les coéquipiers peuvent s'envoyer des messages directement. Il s'agit d'une fonctionnalité expérimentale et elle est désactivée par défaut. Vous devez définir CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 et utiliser Claude Code v2.1.32 ou ultérieur (Documentation officielle).
Le troisième est le git worktree (une fonctionnalité Git qui permet plusieurs répertoires de travail à partir du même dépôt). En démarrant avec claude --worktree feature-auth, Claude se lance dans un environnement isolé sur une branche/répertoire différent. Si vous en exécutez un autre dans un terminal différent, ils peuvent s'exécuter en parallèle sans interférer avec les fichiers des autres (Documentation officielle). Lors de l'utilisation de l'application de bureau, un worktree est automatiquement créé pour chaque nouvelle session.
Voici un tableau comparant les trois :
Vous ne serez pas confus si vous vous souvenez que le worktree gère l'isolation des fichiers, tandis que les sous-agents et les équipes d'agents gèrent la coordination du travail lui-même.
Une action que vous pouvez entreprendre aujourd'hui : D'abord, essayez de taper claude --worktree bugfix-test pour avoir une idée du lancement d'une session isolée. Lorsque vous avez terminé après avoir effectué des modifications, il vous demandera si vous souhaitez conserver ou supprimer le worktree.
3. Pratique : Déployer 8 Sessions dans une « Structure à 3 Couches »
Comment ces trois mécanismes se traduisent-ils en 8 sessions ? J'utilise une disposition divisée en couches Commande, Exécution et Qualité.
Couche Commande/Conception (2 Sessions)
- Session 1 PM (Chef de projet) : Gestion globale de l'avancement, décomposition des tâches, reporting aux humains.
- Session 2 Architecte : Décide de la cohérence technique et de la structure des répertoires. Nécessite l'approbation du plan pour produire des conceptions sans écrire de code.
Couche Exécution/Implémentation (4 Sessions)
- Session 3 Frontend : Création de composants, ajustements de l'interface utilisateur.
- Session 4 Backend : Implémentation des points de terminaison, optimisation des requêtes.
- Session 5 Infra/DevOps : Maintenance Docker, CI/CD.
- Session 6 Sécurité : Vérifications des vulnérabilités, durcissement de l'authentification.
Couche Qualité/Maintenance (2 Sessions)
- Session 7 QA/Relecteur : Révisions des PR, signalement des cas limites.
- Session 8 Rédacteur technique : Maintenance du README, de la documentation API.
Il y a trois conseils pour cette disposition : Isolez les quatre sessions de la couche d'implémentation avec des worktrees afin qu'elles n'interfèrent pas avec les fichiers des autres. Fixez les rôles pour la couche qualité en tant que définitions de sous-agents ou coéquipiers d'équipe d'agents. Et faites en sorte que chaque session relaie les informations via des fichiers Markdown partagés (notes de conception ou résultats de révision). L'Architecte met à jour la conception, la couche d'implémentation avance en se basant sur celle-ci, et le Relecteur écrit les résultats en retour. Les humains n'ont qu'à donner des instructions à chaque session déclenchée par ces mises à jour de fichiers.
Une remarque : La directive officielle pour une équipe d'agents est de 3 à 5 personnes, donc ne mettez pas les 8 dans une seule équipe à la fois (Documentation officielle). Il est plus sûr de combiner des sessions isolées par worktree avec une équipe d'agents de 3 à 5 personnes et des sous-agents au besoin pour atteindre un total de 8 travailleurs.
Une action que vous pouvez entreprendre aujourd'hui : Choisissez deux rôles parmi les 8 ci-dessus qui semblent faciles à séparer dans votre projet actuel. Dans de nombreux cas, l'Architecte et le Relecteur sont les premiers points de division.
4. Fixer les Limites des Rôles avec des « Définitions de Sous-Agents », Pas « CLAUDE.md »
Permettez-moi de corriger un malentendu courant concernant l'opération en parallèle. Vous pourriez voir des explications comme « Écrire des rôles (ID : arch, ID : dev-main...) dans CLAUDE.md et changer de persona au démarrage », mais ce mécanisme n'existe en fait pas.
CLAUDE.md est un fichier d'instructions partagé que Claude Code lit au démarrage. Cependant, la documentation officielle indique clairement que CLAUDE.md est « un contexte, pas un paramètre forcé ». Comme il est passé sous forme de message utilisateur après l'invite système, la conformité stricte n'est pas garantie. Si vous voulez absolument empêcher quelque chose, vous devez utiliser des hooks (Documentation officielle). Considérez-le comme une forte recommandation plutôt qu'une « constitution » absolue.
Alors, où fixez-vous les rôles ? La réponse est les définitions de sous-agents. En plaçant un fichier sous .claude/agents/ avec un nom, une description, les outils disponibles et le modèle dans le frontmatter, vous créez un expert réutilisable. Voici un exemple minimal :
name: security-reviewer
description: Audite de manière critique le code du point de vue de l'authentification, la validation des entrées et la gestion des sessions.
tools: Read, Grep, Bash
model: sonnet
Vous êtes un relecteur sécurité senior. Concentrez-vous sur la gestion des tokens,
la gestion des sessions et la validation des entrées, et rapportez les résultats avec des niveaux de gravité.
De plus, ces définitions peuvent être appelées par leur nom en tant que coéquipiers dans les équipes d'agents. Si vous demandez de « configurer un coéquipier avec le type d'agent security-reviewer pour auditer le module d'authentification », il devient un membre héritant des outils et du modèle de cette définition (Documentation officielle). La conception vous permet d'écrire un rôle une fois en tant que définition de sous-agent et de le réutiliser à la fois comme sous-agent et comme membre d'équipe.
Exemple d'invite à essayer (laisser Claude créer une définition de rôle) :
Créez une définition de sous-agent à placer dans .claude/agents/.
Le rôle est « un relecteur qui signale les problèmes de performance et les requêtes N+1 dans le code d'implémentation. »
Incluez name / description / tools / model dans le frontmatter,
et rédigez le corps dans la personnalité d'un ingénieur senior.
5. Construire une Équipe « Architecte-Relecteur » avec des Équipes d'Agents pour Améliorer la Précision
Une configuration très efficace en opération parallèle consiste à séparer un « créateur » et un « douteur ». Ce n'est pas seulement théorique ; la documentation officielle fournit des exemples concrets.
Dans l'exemple officiel « Révision de code en parallèle », pour une seule PR, trois coéquipiers sont configurés pour la sécurité, les performances et la couverture de test, chacun regardant d'une perspective différente tandis que le chef intègre les résultats. De plus, dans l'exemple « Hypothèses concurrentes », cinq coéquipiers se voient attribuer différentes hypothèses pour un bug afin d'argumenter et de réfuter les théories des autres, la théorie survivante étant traitée comme la cause racine (Documentation officielle). Comme un enquêteur unique a tendance à être attiré par la première théorie, cette approche crée intentionnellement un conflit pour améliorer la précision.
Vous pouvez également implémenter une opération où l'Architecte n'a « pas la permission d'écrire du code » en utilisant des fonctionnalités officielles. En exigeant l'approbation du plan pour un coéquipier, celui-ci reste dans un mode de planification en lecture seule, ne produisant que des conceptions jusqu'à ce que le chef approuve. Les critères d'approbation peuvent être écrits dans l'invite du chef, comme « n'approuver que les plans qui incluent la couverture de test. »
Exemple d'invite à essayer (mettre en place une structure de conflit en une fois) :
Créez une équipe d'agents pour réviser la PR #142. Configurez trois coéquipiers :
un pour la sécurité, un pour les performances et un pour la couverture de test.
Faites-les réviser indépendamment et produire des résultats avec des niveaux de gravité, puis intégrez-les à la fin.
Il existe deux modes d'affichage : in-process (tous les coéquipiers s'exécutent dans le même terminal, cycle avec Shift+Flèche Bas) et split panes (chaque coéquipier dans un volet séparé ; nécessite tmux ou iTerm2). Il est plus facile de commencer avec in-process car il ne nécessite pas de configuration supplémentaire.
6. Partager la Mémoire via la Mémoire Automatique Officielle (Markdown), Pas « SQLite »
Lors de l'exécution de plusieurs sessions, le prochain défi est le « partage de la mémoire entre les sessions ». Bien que des techniques avancées comme « stocker la mémoire balisée dans SQLite et l'injecter dynamiquement » soient parfois présentées, ce n'est pas une fonctionnalité standard de Claude Code. C'est possible si vous construisez une base de données via MCP (Model Context Protocol), mais vous devez distinguer cela du mécanisme de mémoire fourni officiellement.
La mémoire automatique officielle fonctionne avec des fichiers markdown. Dans ~/.claude/projects/<project>/memory/, des fichiers comme MEMORY.md (index) et des fichiers spécifiques à un sujet comme debugging.md sont placés, et Claude y écrit au fur et à mesure de son travail. Les règles de chargement sont claires : chaque session lit les 200 premières lignes ou 25 Ko de MEMORY.md, et Claude ne va lire les fichiers spécifiques à un sujet que lorsque cela est nécessaire. Ceci est disponible à partir de Claude Code v2.1.59, sauvegardé par dépôt (donc partagé entre les worktrees), et stocké localement (Documentation officielle).
La beauté de cette conception est qu'en « chargeant toujours l'index et en récupérant les détails uniquement en cas de besoin », vous pouvez garder la fenêtre de contexte propre. Même avec des milliers de petites règles, le contexte ne sera pas contaminé à chaque fois tant que l'index ne gonfle pas.
En termes d'ordre, utilisez la mémoire automatique officielle basée sur Markdown au maximum avant d'essayer de construire une solution SQLite personnalisée.
Une action que vous pouvez entreprendre aujourd'hui : Taper /memory pendant une session affiche la liste des fichiers CLAUDE.md et de la mémoire automatique actuellement chargés. D'abord, jetez un œil à l'endroit et au nombre de mémoires que vous avez.
7. Trois Pièges de l'Opération Parallèle (Coût, Base de Données, Permissions)
Maintenant que vous comprenez le mécanisme, voici trois points de prudence pour l'opération.
Le premier est le coût en tokens. La documentation officielle indique que, comme chaque coéquipier dans une équipe d'agents a un contexte indépendant, l'utilisation des tokens augmente proportionnellement au nombre de personnes. Utiliser 5 personnes pour des tâches de routine entraînera une perte de coût. C'est pourquoi la recommandation officielle est de 3 à 5 personnes, notant que « trois membres concentrés surpassent souvent cinq membres distraits » (Documentation officielle).
Le deuxième est le périmètre d'isolation des worktrees. Un worktree est simplement un mécanisme Git pour la séparation des fichiers ; les bases de données, les variables d'environnement et les services en cours d'exécution sont toujours partagés. Si deux sessions exécutent des migrations sur la même base de données locale, cela cassera. La documentation officielle prévient de « se souvenir d'initialiser l'environnement de développement (installer les dépendances, configurer les environnements virtuels) dans chaque worktree », et si les tâches touchent à la base de données, vous devez séparer les schémas, les conteneurs Docker ou les fichiers .env (Documentation officielle).
Le troisième concerne les permissions. Les coéquipiers héritent des paramètres de permission du chef lorsqu'ils sont générés. Si vous exécutez le chef avec --dangerously-skip-permissions, tous les coéquipiers seront également dans ce même état non confirmé. Comme l'impact d'un accident se propage en parallèle, il est plus sûr de restreindre les permissions du côté du chef.
8. FAQ pour les Utilisateurs Intermédiaires : Effectif, Extension et Passerelles de Qualité
Pour finir, quelques réponses supplémentaires aux questions courantes.
Q. Combien de sessions sont réalistes ?
Une bonne ligne directrice est la structure à 3 couches et 8 sessions mentionnée précédemment. La clé n'est pas de fourrer 8 personnes dans une seule équipe d'agents, mais d'utiliser une équipe de 3 à 5 personnes comme noyau et d'ajouter des sessions de worktree ou des sous-agents. Cela correspond aux recommandations officielles (3 à 5 personnes par équipe, 5 à 6 tâches par coéquipier). La limite ultime est la portée que vous pouvez surveiller et diriger. Si vous augmentez le nombre au-delà de ce que vous pouvez commander, l'efficacité diminuera.
Q. Que faire si je dépasse les sous-agents et les équipes d'agents ?
Si vous souhaitez surveiller un grand nombre de sessions indépendantes depuis un seul endroit, la page officielle des sous-agents mentionne un mécanisme appelé agents d'arrière-plan (background agents). Pensez-y en couches : les sous-agents pour l'aide au sein d'une session, les équipes d'agents pour une équipe parallèle conversationnelle, et les agents d'arrière-plan pour gérer de nombreuses sessions indépendantes.
Q. Comment puis-je garantir la qualité ?
Les recommandations dans CLAUDE.md ne sont que des « instructions faciles à suivre ». Pour les vérifications que vous voulez absolument exécuter, forcez-les avec des hooks. Les équipes d'agents disposent de hooks comme TeammateIdle, TaskCreated et TaskCompleted ; renvoyer le code de sortie 2 envoie un retour et force la suite du travail (Documentation officielle). Cela signifie que vous pouvez appliquer par programmation des règles comme « ne pas terminer tant que les tests ne sont pas au vert ».
Résumé : Passer de Surveillant à Concepteur/Délégateur
La valeur de Claude Code réside davantage dans la capacité d'une seule personne à contrôler plusieurs Claudes spécialisés que dans le simple fait d'écrire du code plus rapidement. Voici les points clés :
Ne confondez pas les trois mécanismes : les sous-agents renvoient des résultats, les équipes d'agents sont des équipes conversationnelles, et les worktrees isolent les fichiers. Divisez 8 sessions en couches Commande, Implémentation et Qualité ; isolez l'implémentation avec des worktrees et fixez les rôles qualité avec des définitions de sous-agents ou des équipes d'agents. Fixez les limites des rôles dans les définitions de sous-agents plutôt que dans CLAUDE.md, et appliquez des règles absolues avec des hooks. Organisez la mémoire automatique officielle basée sur Markdown avant de construire une solution SQLite personnalisée. Visez 3 à 5 personnes par équipe et montez jusqu'à 8 travailleurs en ajoutant des couches.
3 étapes à essayer dès aujourd'hui :
- [ ] Tapez
claude --worktree test-1pour avoir une idée du lancement d'une session isolée. - [ ] Écrivez une définition de sous-agent pour un rôle de « relecteur » dans
.claude/agents/et demandez-lui de réviser votre implémentation. - [ ] Définissez
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1et essayez d'exécuter une révision de PR en parallèle avec trois coéquipiers.
Le temps que vous passiez à taper constamment des instructions de correction dans une seule session se transformera en temps passé à concevoir et déléguer des rôles. Décider de quoi se décharger et quoi superviser est le travail le plus humain qu'il reste dans l'opération en parallèle.
Liens de Référence (Sources Officielles Primaires)
- Créer des sous-agents personnalisés
- Orchestrer des équipes de sessions Claude Code
- Exécuter des sessions parallèles avec des worktrees
- Comment Claude se souvient de votre projet / CLAUDE.md et la mémoire automatique
Je prévois de partager des informations utiles que je ne peux pas publier sur X dans cet Open Chat. Si vous êtes intéressé, rejoignez-nous maintenant.
