À partir de quel moment faut-il découper en plusieurs agents ?

Quand une tâche nécessite de charger plus de 50-60% du context window rien que pour le code source concerné, ou quand la tâche peut être naturellement divisée en deux parties indépendantes et vérifiables chacune. Un signe concret : si tu te retrouves à expliquer à l'agent "comme on en avait parlé avant", c'est que la session est trop longue.

Comment passer le contexte d'un agent à l'autre ?

Via un fichier Markdown — le livrable d'une session devient le contexte d'entrée de la suivante. Structure type : décision prise / pourquoi / ce qui reste à faire. L'agent lit le fichier au début de la session suivante. C'est plus fiable que de compter sur la continuité d'une session longue.

Peut-on vraiment faire tourner plusieurs agents en parallèle ?

Oui, avec OpenCode notamment via son architecture client/serveur multi-sessions. En pratique : un agent sur la refactorisation backend, un autre sur les tests, en parallèle dans deux splits tmux. Ça fonctionne bien quand les tâches sont sur des parties de la codebase disjointes. Les conflits de merge restent à gérer.

Le CLAUDE.md / AGENTS.md suffit-il comme contexte persistant ?

Pour les conventions structurelles du projet, oui. Pour le contexte d'une tâche en cours, non — il faut un fichier dédié par tâche complexe. Le CLAUDE.md est la mémoire permanente du projet ; les fichiers de session sont la mémoire de travail d'une tâche spécifique.

Comment éviter que les agents dans des sessions parallèles entrent en conflit ?

Découper par fichiers ou modules disjoints. Si l'agent A touche OrderService.php et l'agent B touche PaymentService.php, il n'y aura pas de conflit. Si les deux touchent les mêmes fichiers, travaille en séquentiel. Les branches Git aident aussi : chaque session dans sa branche, merge à la fin.

Comment diffuser ces conventions de gestion de contexte au-delà de soi ?

Les mêmes fichiers qui servent de mémoire à l'agent servent de documentation à l'équipe. Un CLAUDE.md/AGENTS.md versionné avec la règle "une session = un livrable vérifiable" et les patterns de handoff (fichier de plan, checkpoints) devient la référence commune — plus besoin de réexpliquer à chaque nouveau dev pourquoi on coupe une session après 3-4 fichiers. Les handoffs standardisés (REFACTOR_PLAN.md, structure décision/pourquoi/ reste à faire) doublent comme onboarding : un dev qui reprend une tâche lit le même fichier que l'agent.

Guide Avancé 10 min

Gérer le contexte dans un workflow multi-agents

Sébastien Giband · Dev Symfony/TypeScript · Claude Code quotidien · 19 février 2026 · Mis à jour le 17 juillet 2026

PHP/Symfony 7 TypeScript/React Claude Code Neovim + tmux

TL;DR

Le context window est une ressource finie qui se dégrade. La clé est de le traiter comme tel : sessions courtes avec livrables vérifiables, fichiers de contexte persistants entre sessions, découpage en agents spécialisés sur les tâches parallèles. Les workflows multi-agents ne sont pas une complexité supplémentaire — ils sont la façon de travailler à grande échelle sans perdre en qualité.

context-window multi-agent workflow context-rot

Le context window d’un LLM n’est pas une mémoire infinie — c’est une fenêtre glissante. Plus une session s’allonge, plus les instructions initiales perdent leur influence. C’est le context rot , et c’est le problème opérationnel central des workflows agentiques en production.

La solution n’est pas d’attendre des modèles avec des contextes plus grands — c’est de structurer le travail pour ne jamais atteindre la dégradation. Ce guide documente les patterns qui fonctionnent sur des projets réels.

Pourquoi les sessions longues se dégradent-elles ?

Les LLMs utilisent un mécanisme d’attention qui pondère les tokens selon leur position dans le contexte. En simplifiant : les tokens récents ont plus de poids que les tokens anciens. Plus la session est longue, plus les instructions du début (conventions du projet, contraintes, ton) perdent de leur influence sur les décisions de l’agent.

En pratique, après 20-30 échanges dans une session, on observe :

L’agent commence à ignorer des contraintes formulées au début (“utilise les helpers existants”)
Il produit du code dans un style légèrement différent du début de session
Il répète des explications déjà données
Il fait des choix d’architecture qui contredisent ce qui avait été établi

Ce n’est pas un bug — c’est la mécanique du modèle. La réponse est une organisation du travail.

Comment structurer une session efficace ?

Règle fondamentale : une session = un livrable vérifiable

Avant de lancer une session, définir la condition de sortie. Pas “refactoriser le service de paiement”, mais :

Session : Extraire la logique de calcul des remises de OrderService dans DiscountCalculator
Condition de sortie : 
  - Les tests existants passent toujours (phpunit --filter OrderServiceTest)  
  - DiscountCalculator a ses propres tests unitaires
  - L'interface publique de OrderService est inchangée

Quand la condition est atteinte, on coupe la session. Même si l’agent a l’air encore en forme. Surtout si l’agent a l’air en forme — c’est le moment de capitaliser, pas de continuer.

Charger le minimum de contexte utile

Le context window n’est pas un tampon à remplir. Sur OpenCode :

# Charger uniquement les fichiers directement liés à la tâche
> /add src/Service/OrderService.php
> /add src/Repository/OrderRepository.php  
> /add tests/Service/OrderServiceTest.php

# Pas besoin de charger tout src/Service/ "au cas où"

Sur Kilo Code, même logique : ouvrir dans VS Code uniquement les fichiers pertinents, pas tout le workspace.

Le fichier de contexte projet (CLAUDE.md / AGENTS.md)

Ce fichier est lu automatiquement par la plupart des agents au démarrage de chaque session. Il remplace la mémoire inter-sessions — ce que l’agent doit savoir sur le projet de façon permanente :

# Contexte projet

## Stack
- PHP 8.3 + Symfony 7.1 + API Platform 3
- TypeScript 5 + React 18 + Vite
- Tests : PHPUnit 11 (backend), Vitest (frontend)

## Conventions critiques  
- Les repositories héritent de AbstractRepository, jamais directement de Doctrine
- Les tests unitaires mockent via PHPUnit MockObject, jamais via `new` en dur
- Les endpoints API Platform : annotation #[ApiResource] sur la Resource class, 
  pas sur l'Entity directement

## Ce que l'agent NE fait PAS sans demander
- Modifier l'interface publique d'un service existant
- Créer des migrations de base de données
- Modifier les fichiers de configuration Symfony

## Commandes utiles
- Tests : `php bin/phpunit --filter NomDuTest`
- Serveur dev : `symfony serve -d`
- TypeScript check : `npx tsc --noEmit`

Ce fichier est vivant — on l’enrichit à chaque fois qu’on identifie une convention qui manque.

Comment enchaîner plusieurs sessions sur une tâche complexe ?

Pour une tâche qui dépasse une session, le handoff doit être explicite. Structure type avec un fichier de travail :

Session 1 — Analyse et plan

Instruction : "Analyse le service PaymentService.php et le repository 
PaymentRepository.php. Identifie les responsabilités mélangées et propose 
un plan de refactoring. Écris le plan dans REFACTOR_PAYMENT.md avec :
- Les problèmes identifiés
- L'architecture cible
- Les étapes dans l'ordre (chaque étape doit être indépendamment testable)
Ne touche pas au code."

Le fichier REFACTOR_PAYMENT.md est le livrable de la session 1 et le contexte d’entrée des sessions suivantes.

Session 2 — Implémentation des étapes 1 et 2

Instruction : "Lis REFACTOR_PAYMENT.md. Implémente les étapes 1 et 2 du plan.
Condition de sortie : les tests existants passent, chaque étape est dans 
son propre commit avec un message explicite."

Session 3 — Suite et validation finale

Instruction : "Lis REFACTOR_PAYMENT.md (étapes 3 et 4 restantes). 
Implémente. Une fois terminé, vérifie que tous les tests passent 
et marque les étapes comme Done dans le fichier."

Ce pattern a plusieurs avantages : chaque session est courte (contexte frais), les fichiers de travail sont des artefacts vérifiables et commitables, et on peut reprendre à n’importe quelle étape si une session est interrompue.

Comment travailler avec plusieurs agents en parallèle ?

La parallélisation est intéressante quand deux tâches sont suffisamment indépendantes pour ne pas se marcher dessus. Sur OpenCode avec tmux, c’est immédiat :

# Split tmux vertical
# Panneau gauche : agent sur le backend
tmux split-window -h
opencode  # session backend

# Panneau droit : agent sur les tests
# (dans le split de droite)
opencode  # session tests

Règle de non-conflit : deux agents parallèles ne doivent pas toucher aux mêmes fichiers. Si c’est inévitable, travailler en branches séparées :

# Agent 1 : branch feature/refactor-payment
# Agent 2 : branch feature/add-stripe-webhook
# Merge séquentiel après validation des deux

En pratique sur notre projet, le gain de temps des sessions parallèles est réel sur les tâches de migration ou de mise à jour de tests en masse : pendant qu’un agent refactorise un service, un autre met à jour les tests correspondants dans le même temps.

Quels sont les signaux d’un contexte qui se dégrade ?

À surveiller :

L’agent invoque une fonction qui n’existe pas dans la codebase (hallucination de contexte)
Il utilise un pattern qu’il n’avait pas utilisé en début de session
Il répète une explication mot pour mot sans l’adapter
Il propose de faire quelque chose qu’on lui avait dit de ne pas faire

Quand un de ces signaux apparaît : couper, ouvrir une nouvelle session, charger le contexte minimal, reprendre. Ne pas essayer de “corriger” l’agent dans une session dégradée — le contexte est pollué.

Ressources

Questions fréquentes

À partir de quel moment faut-il découper en plusieurs agents ?: Quand une tâche nécessite de charger plus de 50-60% du context window rien que pour le code source concerné, ou quand la tâche peut être naturellement divisée en deux parties indépendantes et vérifiables chacune. Un signe concret : si tu te retrouves à expliquer à l'agent "comme on en avait parlé avant", c'est que la session est trop longue.
Comment passer le contexte d'un agent à l'autre ?: Via un fichier Markdown — le livrable d'une session devient le contexte d'entrée de la suivante. Structure type : décision prise / pourquoi / ce qui reste à faire. L'agent lit le fichier au début de la session suivante. C'est plus fiable que de compter sur la continuité d'une session longue.
Peut-on vraiment faire tourner plusieurs agents en parallèle ?: Oui, avec OpenCode notamment via son architecture client/serveur multi-sessions. En pratique : un agent sur la refactorisation backend, un autre sur les tests, en parallèle dans deux splits tmux. Ça fonctionne bien quand les tâches sont sur des parties de la codebase disjointes. Les conflits de merge restent à gérer.
Le CLAUDE.md / AGENTS.md suffit-il comme contexte persistant ?: Pour les conventions structurelles du projet, oui. Pour le contexte d'une tâche en cours, non — il faut un fichier dédié par tâche complexe. Le CLAUDE.md est la mémoire permanente du projet ; les fichiers de session sont la mémoire de travail d'une tâche spécifique.
Comment éviter que les agents dans des sessions parallèles entrent en conflit ?: Découper par fichiers ou modules disjoints. Si l'agent A touche OrderService.php et l'agent B touche PaymentService.php, il n'y aura pas de conflit. Si les deux touchent les mêmes fichiers, travaille en séquentiel. Les branches Git aident aussi : chaque session dans sa branche, merge à la fin.
Comment diffuser ces conventions de gestion de contexte au-delà de soi ?: Les mêmes fichiers qui servent de mémoire à l'agent servent de documentation à l'équipe. Un CLAUDE.md/AGENTS.md versionné avec la règle "une session = un livrable vérifiable" et les patterns de handoff (fichier de plan, checkpoints) devient la référence commune — plus besoin de réexpliquer à chaque nouveau dev pourquoi on coupe une session après 3-4 fichiers. Les handoffs standardisés (REFACTOR_PLAN.md, structure décision/pourquoi/ reste à faire) doublent comme onboarding : un dev qui reprend une tâche lit le même fichier que l'agent.