Claude Code : pourquoi je découpe mon agent en spécialistes

Quand on commence à travailler sérieusement avec un agent de code, le réflexe est de tout lui donner : les conventions du projet, l'historique des décisions, les règles de sécurité, les contraintes de référencement, les pièges de la base de données. Ça paraît évident, puisque plus il en sait, mieux il devrait décider. Sur mes propres projets, j'observe exactement l'inverse depuis des mois.

Un agent travaille mieux quand on le découpe en sous-agents spécialisés, chacun avec son domaine et son contexte propre : un pour la sécurité, un pour le référencement, un pour la relecture produit, un pour l'archivage, et un agent principal qui distribue le travail puis rassemble les retours. Le contexte est une ressource rare, et un spécialiste à qui on a donné ce qu'il lui faut raisonne mieux qu'un généraliste à qui on a tout donné.

Pourquoi un agent qui sait tout décide moins bien

L'intuition contraire est tenace, et je la comprends : on est habitué à ce qu'un collaborateur mieux informé prenne de meilleures décisions. Pour un modèle de langage, ce n'est pas comme ça que ça marche. Tout ce qu'il a sous les yeux au moment d'agir occupe la même place et entre en concurrence pour son attention. Une consigne de sécurité noyée au milieu de trente règles de style a statistiquement moins de poids que la même consigne seule dans un contexte de quatre cents mots. Ce n'est pas un défaut qu'on corrigera par un modèle plus gros : c'est la nature de l'objet. Et plus le contexte grossit, plus il devient contradictoire, parce qu'une règle écrite pour le front-end finit par se heurter à une règle écrite pour la base de données, sans que personne n'ait arbitré le conflit. L'agent, lui, arbitre tout seul, et vous ne saurez jamais lequel des deux il a choisi ni pourquoi.

Ce qu'un sous-agent doit porter pour être utile

Un sous-agent n'est pas un prompt plus court, c'est un rôle écrit. J'y mets quatre choses, et quand l'une manque le résultat se dégrade immédiatement. Son domaine d'abord, défini par ce qu'il regarde et surtout par ce qu'il ignore. Ses critères de jugement ensuite, formulés assez précisément pour qu'un désaccord soit possible : « ce code est propre » n'est pas un critère, « toute entrée venue de l'extérieur est validée avant d'atteindre la base » en est un. Troisième élément, et c'est celui qu'on oublie : ce qu'il doit refuser. Un relecteur qui n'a pas le droit de dire non finit par approuver, parce que la pente naturelle d'un modèle est d'être serviable. Enfin les pièges déjà rencontrés dans ce domaine précis, sur ce projet, avec leur contexte. C'est ce dernier bloc qui fait la différence entre un avis générique qu'on trouverait dans n'importe quel article et un avis qui vous apprend quelque chose. Il ne s'écrit pas à l'avance : il se remplit chaque fois qu'un incident vous coûte une journée.

Le coût de la spécialisation est bien réel

Rien de tout ça n'est gratuit, et ce serait malhonnête de présenter la méthode sans son prix. Ces contextes, il faut les écrire, et un sous-agent utile se compte en pages, pas en lignes. Il faut ensuite les tenir à jour, parce qu'un rôle qui décrit une architecture abandonnée l'an dernier produit des avis faux avec une assurance parfaite, ce qui est pire que pas d'avis du tout. Et il faut savoir reconnaître le moment où on en a trop. Un sous-agent qu'on n'invoque jamais est de la dette : il donne l'impression d'une couverture qui n'existe pas, il périme en silence, et il alourdit la décision de l'agent principal qui doit choisir à qui parler. Sur mes projets, j'en supprime à peu près autant que j'en ajoute, et les candidats à la suppression se repèrent facilement : ce sont ceux dont je ne me rappelle plus le dernier retour utile. La bonne nouvelle, c'est que ce travail ne sert pas qu'aux agents. Un rôle écrit proprement est aussi une fiche de poste et une liste de contrôle que n'importe qui dans l'équipe peut lire.

La difficulté se déplace, elle ne disparaît pas

Voilà ce que personne ne vous dit en vous vendant la spécialisation : elle ne supprime pas le travail difficile, elle le déplace. Quand chaque sous-agent fait bien son métier, la question n'est plus « comment obtenir un bon résultat » mais « comment découper ce chantier en morceaux qui ont du sens séparément, et comment recoller ce qui remonte ». Découper mal, c'est demander à trois spécialistes de se prononcer sur une question dont aucun ne tient le bout décisif. Recoller mal, c'est recevoir quatre avis contradictoires et prendre le dernier arrivé. Ce travail a un nom et il n'est pas nouveau : c'est de l'architecture. Il demande de comprendre les frontières réelles du système, de savoir où passent les dépendances, et d'accepter que l'arbitrage final reste à vous. C'est aussi pour ça que la maîtrise technique compte plus qu'avant, pas moins : l'IA amplifie l'expertise au lieu de la remplacer, et le découpage est précisément l'endroit où ça se vérifie.

Sur un sujet transverse, la spécialisation fragmente

Il y a une classe de problèmes où cette méthode se retourne contre vous, et il vaut mieux la connaître avant de s'y heurter. Prenez une lenteur qui apparaît en production sans cause évidente. Le spécialiste base de données trouve ses requêtes correctes, celui du front-end ne voit rien d'anormal dans le rendu, celui de l'infrastructure constate que les machines respirent. Chacun a raison dans son périmètre, et le problème vit dans la couture entre deux morceaux qu'aucun ne regarde. Quatre rapports rassurants, un bug intact. Dans ces cas-là il faut quelqu'un qui tienne la chaîne entière dans sa tête, et ce quelqu'un est humain. Je n'ai pas trouvé de contournement élégant : je repasse en mode généraliste, j'ouvre le contexte en grand, j'accepte des avis moins tranchés, et je cherche moi-même. La spécialisation ne remplace pas le jugement, elle le concentre ailleurs, sur le découpage et sur l'assemblage.

Ce que j'en retiens après des mois à vivre avec

La chose qui m'a le plus surpris n'est pas le gain de qualité, même s'il est net. C'est que l'exercice d'écriture de ces rôles m'a forcé à formuler des choses que je savais faire sans savoir les dire. Expliquer à une machine ce qu'un relecteur produit doit refuser oblige à décider ce qu'on refuse, et beaucoup d'équipes, y compris les bonnes, ne l'ont jamais mis par écrit. Les sous-agents versionnés à côté du code ne sont que la forme la plus récente d'une idée plus ancienne : faire du dépôt la mémoire du projet, lisible autant par les humains que par les agents. Si le mot « agent » reste flou pour vous, j'ai détaillé ce qu'il y a dans le capot avant de parler d'orchestration.