Une méthodologie pour construire des agents IA

Le 31 mars 2026, un fichier .map de 59.8 MB a été publié accidentellement dans le package npm de Claude Code. 512 000 lignes de TypeScript, 1 906 fichiers. Tout le harness agentique d'Anthropic exposé au grand jour.

Tout le monde en a parlé et c'est bien normal. Les codenames de futurs modèles (Capybara, Tengu), l'agent autonome KAIROS, les faux outils anti-distillation. C'est du bon matériel pour les gros titres.

Mais ce qui m'intéresse, c'est autre chose. Je précise d'emblée que je n'ai pas eu accès au code leaké moi-même. Ce qui suit est une synthèse des analyses techniques publiées par d'autres dans les jours qui ont suivi la fuite, croisée avec le projet claw-code qui a reproduit l'architecture from scratch en Python et Rust pour des raisons légales. À partir de ces sources, j'ai fini par trouver quelque chose qui me semble plus précieux que des codenames ou que des bouts de code : une méthodologie. Sept principes de conception que je confronte à ce que je construis avec mAIstrow, le système d'IA agentique sur lequel je travaille au quotidien. Ils sont utiles à peu près à tous les gens que je vois se lancer sérieusement dans un système d'agents.

Le chiffre qui change tout

Avant d'entrer dans la méthodologie, deux chiffres qui devraient suffire à convaincre n'importe qui de s'y intéresser.

Le premier vient de SWE-bench Lite. Avec un scaffold basique, GPT-4 résout 2,7 % des problèmes. Avec le framework CodeR [1], le même modèle monte à 28,3 %. Un facteur dix sans toucher une ligne de pondération. Le second vient de Terminal-Bench 2.0 : Opus 4.5 testé avec trois scaffoldings différents (Augment, Cursor, Claude Code) montre 17 problèmes d'écart sur les 731 issues du benchmark [2]. Même modèle, trois infrastructures, trois scores nettement différents.

La conclusion est dure à esquiver. Le choix du modèle n'est pas le facteur déterminant de la performance d'un agent. L'infrastructure autour du modèle (le scaffold [3], le harness, l'outillage) compte autant et souvent plus. C'est aussi ce que les analyses publiées du code de Claude Code décrivent, section après section.

Sebastian Raschka arrive à la même conclusion le jour même du leak, dans un premier post [4] où il liste les mêmes ingrédients que ceux que je vais détailler plus bas : gestion du contexte projet, prompt cache, outils structurés, compression de contexte, mémoire, sous-agents. Il développe ensuite l'analyse dans Components of a Coding Agent avec un mini coding agent en Python et sa formule résume assez bien ce que disent aussi tous les autres analystes du leak : "the surrounding system plays as much of a role as the model itself". Les principes qui suivent sont une lecture des analyses disponibles à travers cette grille.

Principe 1. Le scaffold compte plus que le modèle

Les analyses publiées décrivent un système de plus de cinquante outils organisés en registre plugin. Le modèle ne "code" pas à proprement parler. Il orchestre des appels structurés (lire un fichier, lancer une commande, chercher un pattern dans un dossier) et c'est le scaffold qui les exécute.

Chaque outil a un niveau de risque classé LOW, MEDIUM ou HIGH et c'est le scaffold qui décide en conséquence si l'action passe directement, demande une confirmation, ou est bloquée. Cette séparation a une conséquence qui est moins anodine qu'elle n'en a l'air : on peut changer de modèle sans changer le système. Opus, Sonnet, un modèle tiers, le scaffold reste identique. Les analyses mentionnent d'ailleurs l'existence de feature flags pour basculer entre modèles en cours de route.

Ce que j'en retiens pour mes propres projets, c'est qu'il est plus rentable de commencer par le scaffold que par le choix du modèle. Le modèle, vous finirez par en changer ; le scaffold, c'est ce que vous construisez vraiment. C'est la ligne que suit mAIstrow côté système, comme le fait aussi herbert-rs un cran plus bas côté moteur d'inférence : le moteur y est délibérément découplé du modèle qu'il charge, le format des poids, l'architecture du transformer et les opérateurs sont traités comme des modules interchangeables. J'ai fait cet effort dès le départ précisément parce que je savais qu'aucun modèle choisi aujourd'hui ne me servirait encore dans deux ans.

Principe 2. Le prompt est l'architecture

D'après les analyses, le system prompt [3] de Claude Code ferait entre 38 000 et 50 000 tokens. C'est un document structuré, qui ressemble davantage à une spécification qu'à une instruction en langage naturel.

Le point qui m'a le plus marqué à la lecture de ces analyses, c'est qu'une bonne partie de l'orchestration multi-agent serait définie dans le prompt lui-même et non dans le code. Le mode Coordinator, qui répartit le travail entre sous-agents, serait décrit textuellement, comme une directive adressée au modèle et non comme du branching TypeScript. L'avantage est concret : pour changer le comportement de l'orchestration, il suffit de réécrire une section du prompt et d'activer un feature flag [3] GrowthBook, là où un équivalent codé en dur aurait demandé une compilation, une release, un déploiement et sans doute une revue de pull request.

Le prompt contiendrait aussi des directives comportementales assez précises. Pas d'emojis sauf demande explicite, réponses concises, action d'abord et raisonnement ensuite et surtout l'obligation d'évaluer la réversibilité et le rayon d'impact de chaque action avant de l'exécuter. Ce dernier point est d'ailleurs ce que je trouve le plus sage dans toute la méthodologie : ce sont des critères qu'un bon sysadmin applique depuis toujours et qu'il est rassurant de voir codifiés explicitement pour un agent.

Ce que j'en conclus, c'est que dans un système agentique le prompt n'est pas une configuration mais une véritable architecture et qu'il mérite le même soin que votre code. C'est-à-dire une revue, une structure, des règles de cohérence et probablement une forme de versionnement.

Principe 3. La mémoire est un hint, pas une vérité

Claude Code implémente un système mémoire à 3 couches :

L'index est limité à 200 lignes. Chaque entrée est un pointeur, pas du contenu. Quand le modèle a besoin de détails, il charge le topic file correspondant. L'historique brut n'est accessible qu'en recherche.

La consolidation se fait en arrière-plan via un sous-agent forké (autoDream) qui fusionne les observations, supprime les contradictions et met à jour l'index. Trois conditions doivent être remplies : 24h depuis la dernière consolidation, 5+ sessions accumulées et un verrou acquis.

Mais le principe de design le plus important est celui-ci :

"La mémoire dit que X existe" ≠ "X existe maintenant."

Le modèle est instruit de vérifier contre le code réel avant d'agir sur un souvenir. Si la mémoire contredit la réalité, c'est la réalité qui gagne et la mémoire est mise à jour dans la foulée.

Ce pattern n'est pas un choix arbitraire d'Anthropic. Andrej Karpathy décrit indépendamment la même architecture dans un thread récent sur la mémoire personnalisée des agents IA. Il y défend quatre principes : une mémoire explicite et inspectable plutôt qu'une boîte noire, des fichiers markdown plutôt qu'une base de données (c'est son "file over app"), des données qui restent sous le contrôle de l'utilisateur et un modèle interchangeable ("BYOAI"). Ce que fait MEMORY.md dans Claude Code correspond très exactement à cette description : fichiers markdown, vérifiables, locaux, indépendants du modèle.

Et dans les réponses au thread de Karpathy, je suis tombé sur un utilisateur qui décrit son propre système avec "cron jobs and a dream cron to clean up stale memories/contradictions", de la mémoire partagée entre providers et de la synchronisation en temps réel. Sans connaître le code de Claude Code, il venait de réinventer autoDream et KAIROS. Quand le même pattern émerge indépendamment chez Anthropic, chez Karpathy et chez un praticien isolé, il est difficile de continuer à le considérer comme un simple choix d'implémentation.

La manière dont je formule cela pour mes propres systèmes, c'est que la mémoire d'un agent est un cache, pas une base de données. Elle accélère, elle donne du contexte, mais elle ne fait pas autorité. Dès qu'on accepte cette distinction, on évite toute une classe de comportements erratiques liés à des souvenirs périmés qui contredisent silencieusement la réalité.

Principe 4. La sécurité en profondeur, pas en largeur

Les analyses décrivent un fichier bashSecurity.ts qui contiendrait 23 vérifications numérotées appliquées à chaque commande avant exécution. 18 builtins Zsh bloqués (eval, exec, source, trap...). Détection d'injection Unicode (zero-width spaces). Vérification de traversée de chemin avec normalisation Unicode.

Mais les 23 checks ne sont que la première couche. L'architecture complète en compte cinq :

Le système de permissions offre cinq modes qui vont du plus strict au plus permissif : Default (confirmations fréquentes), Allow Edits (fichiers OK, bash confirmé), Auto (où un classifieur ML détermine le risque des commandes), Bypass et YOLO (tout passe, pour le développement ou les utilisateurs qui savent ce qu'ils font). Cinq CVEs [3] publiques documentent par ailleurs des bypasses trouvés et corrigés via HackerOne, ce qui est à la fois rassurant sur la maturité du processus et inquiétant sur la surface d'attaque réelle.

Ce que j'en retiens, c'est que la sécurité d'un agent IA ne peut pas reposer sur un firewall unique. Elle ressemble davantage à une pile de tamis dont chacun suppose que le précédent a laissé passer quelque chose. Le fait qu'Anthropic maintienne un bug bounty actif me semble confirmer que cette discipline n'est jamais "terminée" et c'est probablement la seule attitude raisonnable dans ce domaine.

Principe 5. Read parallèle, Write sériel

Le système multi-agent de Claude Code définit trois types de sous-agents :

L'orchestration suit quatre phases : Research (parallèle, lecture seule) → Synthesis (coordinateur fusionne) → Implementation (sérielle, un seul agent écrit) → Verification (parallèle, tests et reviews).

La règle de concurrence est simple : les opérations de lecture (Glob, Grep, Read) s'exécutent en parallèle. Les opérations d'écriture (Edit, Write, Bash) s'exécutent en série. Un seul agent modifie les fichiers à un instant donné.

Les analyses rapportent des directives explicites dans le prompt du coordinateur, du genre "Do not rubber-stamp weak work" ou "You must understand findings". Elles sont là pour empêcher un travers classique de ce type d'architecture, dans lequel le coordinateur se contente de relayer passivement les productions des sous-agents sans y apporter de jugement.

Ce principe rejoint directement ce que n'importe quel ingénieur connaît en programmation concurrente. Les lectures peuvent se paralléliser sans douleur, les écritures demandent une sérialisation. Et dans un système où le coordinateur ne comprend pas ce qu'il coordonne, il devient un goulot d'étranglement qui n'apporte rien de plus qu'un reroutage de messages.

Principe 6. Concevoir pour le coût dès le départ

D'après les analyses, le system prompt de Claude Code est divisé en deux par un marqueur SYSTEM_PROMPT_DYNAMIC_BOUNDARY :

• Section statique : outils, règles de base, instructions. Identique pour tous les utilisateurs d'une organisation. Cacheable.
• Section dynamique : MEMORY.md, CLAUDE.md, contexte projet. Spécifique à chaque session.

Le prompt caching [3] facture les tokens cachés à 1/10e du prix. Cette division réduit le coût du system prompt d'environ 90%, soit la différence entre ~$0.75 et ~$0.075 par requête avec Opus 4.6.

Les analyses mentionnent un fichier promptCacheBreakDetection.ts qui surveillerait quatorze vecteurs susceptibles d'invalider ce cache : changement de MEMORY.md, toggle de mode, ajout d'outil, changement de modèle... Chaque vecteur a sa mitigation. Les "sticky latches" empêchent les oscillations de mode (plan → normal → plan) de casser le cache à chaque toggle.

Et un commentaire dans autoCompact.ts, rapporté par les analyses, révèle un bug historique :

"1,279 sessions had 50+ consecutive failures wasting ~250K API calls/day globally"

Le correctif documenté dans le code est un circuit breaker [3] plafonné à trois échecs consécutifs. C'est simple, efficace et à l'échelle d'Anthropic ça représente très probablement plusieurs dizaines de milliers de dollars par jour.

Ce que ce genre de détail me rappelle, c'est que dans un système IA en production le coût n'est pas un problème d'optimisation qu'on traite plus tard, c'est une contrainte architecturale qu'on intègre dès le début. Structurer le prompt pour tirer parti du cache, surveiller les vecteurs d'invalidation, mettre des circuit breakers sur chaque boucle où l'agent pourrait s'acharner, tout cela relève de la conception initiale, pas de l'optimisation de fin de projet.

Je retrouve la même préoccupation à deux niveaux dans ce que je construis. Côté mAIstrow, c'est une discipline de budget tokens qui ressemble beaucoup à celle décrite dans les analyses de Claude Code. Côté herbert-rs, la ressource rare n'est plus le token facturé mais le cycle CPU ou GPU. Chaque opération matricielle inutile devient du temps perdu qui se traduit par de la latence côté utilisateur. Les deux niveaux partagent la même logique : profiler, identifier le gaspillage, refuser ce qui ne sert à rien.

Principe 7. Du réactif au proactif : KAIROS

KAIROS serait référencé 150+ fois dans le codebase selon les analyses. C'est un agent daemon [3], un processus persistant qui tourne en continu, compilé à false dans les builds publics mais entièrement présent dans le code.

L'architecture : un cron toutes les 5 minutes, des webhooks GitHub, des daemon workers et un budget de 15 secondes par cycle d'action proactive. L'agent vérifie l'état des PRs, exécute des tâches planifiées, consolide sa mémoire via le skill /dream.

Des outils exclusifs lui sont réservés : envoi de fichiers à l'utilisateur, notifications push, abonnement aux événements de PR. Le mode Brief est activé par défaut, avec des réponses minimales et un focus sur l'action.

Aucun concurrent connu n'a aujourd'hui d'équivalent. Cursor, OpenHands et Copilot sont réactifs, Devin est autonome mais sans la persistance daemon ni la consolidation mémoire. KAIROS décrit un régime différent, celui où l'agent cesse d'attendre qu'on lui parle pour commencer à travailler sur ce qu'il estime pertinent.

C'est probablement là que se joue une bonne partie de l'avenir des agents IA et ce ne sera pas dans l'interface de chat. Ce sera dans ce type de daemon qui tourne en arrière-plan, priorise ses propres tâches et n'interrompt l'humain que quand il a quelque chose d'utile à lui dire. Le budget de quinze secondes par cycle d'action proactive est à ce titre un détail que je trouve particulièrement bien pensé : il empêche l'agent de monopoliser les ressources tout en lui laissant assez de marge pour faire quelque chose d'utile à chaque passage.

Bonus. L'anti-distillation, ou comment protéger sa valeur

Un aspect inattendu rapporté par les analyses : les mécanismes anti-distillation. La distillation [3] comportementale (entraîner un petit modèle sur les outputs d'un gros) est la menace existentielle des agents propriétaires.

D'après ces analyses, Claude Code implémenterait quatre contre-mesures :

Les faux outils sont activés par quatre conditions simultanées : flag compile-time, lancement via CLI, provider Anthropic first-party et flag GrowthBook actif. Si un distilleur entraîne sur ces données, son modèle apprend des outils qui n'existent pas.

La stratégie est pragmatique. Elle ne bloque pas un attaquant déterminé, puisqu'un proxy MITM suffit à contourner les fake tools, mais elle augmente le coût de la distillation au-dessus du seuil de rentabilité pour la majorité des acteurs qui pourraient être tentés par l'exercice.

Ce que cette partie moins spectaculaire du leak m'a appris, c'est que la valeur dans l'économie actuelle de l'IA a glissé. Les modèles deviennent progressivement des commodités ; ce qui les entoure est devenu, pour Anthropic comme pour ses concurrents, le véritable actif. Et cet actif ne se protège pas par l'obscurité du code, puisque ce leak prouve que le code finit toujours par fuiter d'une manière ou d'une autre. Il se protège par des mécanismes d'empoisonnement de données qui rendent la copie comportementale coûteuse. Le projet claw-code apporte une illustration presque parfaite de cette lecture : ses auteurs ont pu reproduire l'architecture entière from scratch en Python et Rust, uniquement à partir des analyses publiques, ce qui montre que la méthodologie n'est pas un secret. Le secret, s'il en reste un, c'est la discipline d'exécution.

Ce que j'en retiens pour mAIstrow

Aucun de ces sept principes n'est resté théorique pour moi. Je les retrouve dans mAIstrow, le système d'IA agentique sur lequel je travaille au quotidien. Je les retrouve aussi dans une moindre mesure dans herbert-rs, le moteur d'inférence LLM en Rust et en assembleur qui en constitue la couche basse.

Côté mAIstrow, la liste des principes applicables est essentiellement celle des sept décrits plus haut. Le scaffold est découplé du modèle sous-jacent pour que je puisse en changer sans réécrire le reste. Le prompt système y est traité comme une véritable architecture structurée, avec ses règles de cohérence et sa section statique cacheable. La mémoire suit la discipline "hint, pas vérité" avec un index en tête et des topic files chargés à la demande. Les actions sensibles passent par plusieurs couches de validation plutôt que par un contrôle unique. Le coût est intégré comme contrainte de conception, avec une attention particulière au ratio tokens cachés / tokens frais. Et l'orchestration multi-agent suit la règle "lectures en parallèle, écritures en série" dont j'ai découvert à l'usage qu'elle évite toute une classe de bugs d'état partagé.

Côté herbert-rs, l'analogie est plus limitée, parce qu'un moteur d'inférence n'est pas un agent. Trois principes y cascadent néanmoins. La modularité, d'abord, avec chaque opérateur (matmul, attention, RoPE) traité comme un module remplaçable indépendamment des autres, au même titre que les outils dans Claude Code. L'obsession du coût, ensuite, transposée du token facturé au cycle CPU ou GPU consommé, avec la même discipline de profiling systématique. Et la sécurité en couches, enfin, sous une forme particulière : Rust élimine par construction toute une classe de bugs mémoire, ce qui joue le rôle d'une couche structurelle posée une fois pour toutes au niveau du langage plutôt que d'un contrôle à l'exécution.

Ce que le leak de Claude Code confirme, pour moi, c'est ce que beaucoup de praticiens savaient déjà sans l'avoir formulé aussi clairement. Le modèle est une condition nécessaire pour qu'un agent fonctionne, mais le scaffold est ce qui détermine à quel point il sera utile en pratique. Et c'est sur la méthodologie de construction de ce scaffold que se joue aujourd'hui l'essentiel de la différence entre les projets qui tiennent la route et ceux qui restent à l'état de démonstration.

Sources

Les analyses sur lesquelles cet article s'appuie :

• Alex Kim, Claude Code Source Leak : analyse technique détaillée
• Kuber Studio, 512K Lines Analysis : l'analyse la plus complète
• WaveSpeedAI, Architecture Analysis : architecture du harness
• Marc Bara, What the Leak Actually Reveals : prompt as architecture
• Anthropic Engineering, Infrastructure Noise : source officielle
• Penligent, Security Analysis : CVEs et sécurité

[3] Glossaire

• Scaffold (ou harness) : l'infrastructure logicielle qui entoure le modèle IA. C'est le code qui reçoit les demandes du modèle, exécute les actions (lire un fichier, lancer une commande), gère les permissions et retourne les résultats. Le modèle "pense", le scaffold "fait".
• System prompt : le texte d'instruction envoyé au modèle au début de chaque conversation. Il définit son comportement, ses outils, ses règles. Dans Claude Code, il fait ~50 000 tokens.
• Tool call : un appel structuré du modèle vers un outil. Le modèle émet du JSON ("je veux lire tel fichier"), le scaffold l'exécute et retourne le résultat.
• Prompt caching : technique qui évite de retransmettre les parties invariantes du prompt à chaque requête. Les tokens cachés coûtent 10x moins cher.
• Circuit breaker : pattern qui coupe une opération après N échecs consécutifs, pour éviter de gaspiller des ressources en boucle.
• MoE (Mixture of Experts) : architecture de modèle où seule une fraction des paramètres est activée par requête. Permet d'avoir un gros modèle (120B) avec un coût d'inférence d'un petit (5B actifs).
• Distillation : technique qui entraîne un petit modèle à reproduire le comportement d'un gros. "Anti-distillation" désigne les mécanismes pour empêcher ce clonage.
• Feature flag : interrupteur dans le code qui active ou désactive une fonctionnalité sans redéployer. GrowthBook est un outil de feature flags.
• Daemon : processus qui tourne en arrière-plan en continu, par opposition à un programme lancé puis terminé.
• SWE-bench : benchmark qui mesure la capacité d'un agent IA à résoudre de vraies issues GitHub. 2 294 problèmes issus de projets Python open-source.
• Token : unité de texte utilisée par les modèles de langage. Un mot courant = 1 token, un mot rare ou technique = 2-3 tokens. Les coûts API sont facturés au token.
• CVE (Common Vulnerabilities and Exposures) : identifiant unique pour une faille de sécurité connue. CVE-2025-XXXXX = une vulnérabilité documentée publiquement.
• Webhook : mécanisme où un service externe (GitHub, Slack...) envoie automatiquement une notification HTTP quand un événement se produit (nouvelle PR, commentaire...).
• MITM (Man-In-The-Middle) : attaque où un intermédiaire intercepte les communications entre deux parties. Un proxy MITM peut modifier les requêtes API en transit.
• RAG (Retrieval-Augmented Generation) : technique qui enrichit le prompt d'un modèle avec des documents retrouvés par recherche, plutôt que de compter uniquement sur ce que le modèle a mémorisé.
• Blast radius : terme emprunté à la sécurité militaire. En ingénierie logicielle, désigne l'étendue des dégâts potentiels si une action tourne mal.

[1] CodeR: Issue Resolving with Multi-Agent and Task Graphs (arXiv 2406.01304). CodeR utilise un framework multi-agent avec des graphes de tâches prédéfinis pour résoudre des issues GitHub. Le même GPT-4 passe de 2.7% (scaffold RAG basique) à 28.3% avec cette orchestration. Code source : NL2Code/CodeR.

[2] Terminal-Bench 2.0 : 6 points d'écart entre la configuration d'infrastructure la plus riche et la plus pauvre, avec le même modèle.

[4] Sebastian Raschka. Le jour du leak : Claude Code's Real Secret Sauce (Probably) Isn't the Model (31 mars 2026, 2 830 likes). Puis l'analyse développée : Components of a Coding Agent, avec un mini coding agent en Python. Raschka est l'auteur de Build a Large Language Model (From Scratch) et Build a Reasoning Model (From Scratch).

Reproduction indépendante :

• claw-code : port clean-room de l'architecture en Python/Rust, maintenu par des agents IA

Mon travail connexe :

• herbert-rs : moteur d'inférence LLM en Rust et assembleur
• Panorama LLM open-source 2026 : l'article compagnon sur les modèles
• Répertoire de benchmarks (71 benchmarks) : référence des benchmarks utilisés dans cet article

Des questions sur cet article ou votre propre projet ? Réserver une consultation