Ingénierie des Harnais d'Agents IA : Ce que 8 Mois en Production M'ont Appris

12 min read
Artificial Intelligence Software Engineering Programming Software Development Productivity
Ingénierie des Harnais d'Agents IA : Ce que 8 Mois en Production M'ont Appris

Même modèle. 36 points de plus aux benchmarks. Le problème n'était pas le modèle.

Anthropic a donné à Opus 4.5 un prompt de haut niveau pour construire une app web en production. Échec total. Pas parce que le modèle était mauvais. Parce qu'il a tenté de tout faire d'un coup (avouez-le, vous faites pareil), laissé des fonctionnalités à moitié implémentées à travers les fenêtres de contexte, et déclaré victoire trop tôt. Ils ont corrigé l'architecture, ajouté un suivi de progression et des workflows incrémentaux : le même modèle s'est mis à livrer. Ils ont appelé l'article "Effective Harnesses for Long-Running Agents."

TL;DR : "Harnais > modèle" est correct mais incomplet. Le mécanisme qui fait que ça marche, c'est la divulgation progressive : ne montrer au modèle que ce dont il a besoin, quand il en a besoin. Le même modèle a gagné 36 points sur CORE-Bench juste en changeant d'architecture. Mon framework après 8 mois et 5 apps en production : contrats plutôt que feeling, contraintes plutôt qu'outils, simplifier chaque trimestre. Templates copier-coller inclus.

Puis le mot s'est répandu partout. OpenAI a publié "Harness Engineering." LangChain a fait passer leur agent de code de 52,8% à 66,5% en ne changeant que le harnais. Mitchell Hashimoto et Martin Fowler en ont parlé. SWE-bench Pro l'a confirmé à grande échelle : même modèle, architecture différente, résultats différents.

J'ai regardé mon CLAUDE.md, mes contrats de prompts, mes wrappers CLI, et j'ai réalisé que c'est exactement ce que je faisais depuis huit mois sur cinq apps en production. Je n'avais juste pas le mot pour le nommer. Harnais. C'est le mot.

Donc oui, le harnais compte plus que le modèle. Cette partie est réglée.

Mais savoir que "le harnais compte" c'est comme savoir "mange sainement et fais du sport." Vrai, inutile si vous ne le faites pas vraiment, et sur le point de générer toute une industrie de frameworks trop compliqués qui passent à côté du sujet.

J'ai passé huit mois à faire toutes les erreurs possibles. Voici ce qui a survécu.

Les trois erreurs que tout le monde va faire

Je le sais parce que je les ai toutes faites.

Erreur 1 : Empiler les outils au lieu d'écrire des contrats

Quand j'ai commencé à construire OpenClaw, mon agent IA multi-modèles, j'ai branché 12 outils MCP. Recherche, mémoire, vérifications de crédit, monitoring RSS, alertes Discord, statut cron, requêtes utilisateur, vérification de sauvegarde. Ça semblait complet. Ça semblait professionnel.

L'agent passait plus de temps à décider quel outil appeler qu'à résoudre le vrai problème.

Sur une simple requête "quelque chose nécessite mon attention ce matin ?", il lançait 4-5 appels d'outils en séquence, parfois touchant le même endpoint deux fois avec des paramètres légèrement différents parce que les descriptions étaient assez vagues pour se chevaucher. Un matin il a appelé check_users, puis check_credits, puis check_users encore avec un filtre différent, puis m'a donné une réponse qui se contredisait entre les paragraphes.

J'ai arraché 8 outils. Remplacé 12 par 4 avec des descriptions précises écrites comme des contrats. Pas "interroger les données de crédit" mais "trouver les utilisateurs dont le solde de crédit actuel dévie de l'attendu de plus de 10%, signaler l'anomalie avec le montant de dérive, et trier par sévérité." Même code sous-jacent. Même modèle. La seule chose qui a changé était la description.

40% d'appels d'outils en moins. Les sorties ont arrêté de se contredire. La description de l'outil était le problème depuis le début.

J'ai construit le framework complet de contrats de prompts autour de ce principe et c'est devenu le changement le plus impactant de tout mon workflow. Vous ne partagez plus de code avec l'agent. Vous partagez l'intention, les contraintes, et le comportement attendu. La description EST le contrat.

Erreur 2 : Choisir la complexité quand la simplicité marche

47 000 tokens. C'est ce que Phil Schmid a mesuré comme coût d'intégration de 6 serveurs MCP de manière standard. Juste les définitions de schémas. Avant même que votre agent commence à réfléchir à votre vrai problème, il mâche quarante-sept mille tokens de descriptions d'outils JSON.

Manus a résolu ça en exposant les outils MCP via un wrapper CLI. Mêmes capacités. Environ 400 tokens.

Je ne connaissais pas ces chiffres quand j'ai construit mon premier serveur MCP fin 2025. Tout le monde en construisait. Le protocole était nouveau, brillant, ça semblait être la bonne abstraction. Alors j'en ai construit un aussi. Flow OAuth personnalisé, gestion du refresh de token, agrégation de données multi-sources, tout le tralala.

Seize commits. Quatre heures à déboguer un token d'auth qui expirait en milieu de session. J'étais dans une chambre d'hôtel à Cancún avec une piscine littéralement à dix mètres, à regarder défiler les logs au lieu de nager. Finalement livré et ça marche bien maintenant. Mais j'ai aussi construit des CLIs qui faisaient la même chose pour d'autres services. Le CLI avait besoin d'un script bash et d'une sortie JSON. A marché du premier coup.

Cool.

Vercel a mené la même expérience à grande échelle. Commencé avec des bibliothèques d'outils complètes, recherche, code, fichier, outils API. Toutes les capacités qu'on pourrait vouloir. Les agents se sont embrouillés, ont fait des appels redondants, pris des étapes inutiles. Ils ont réduit à l'essentiel, donné à l'agent un accès bash direct. Taux de succès monté à 100%, vitesse augmentée de 3,5x.

J'ai écrit sur pourquoi les CLIs battent MCP pour la plupart des setups d'agents et la réaction a été dingue. Il s'avère que beaucoup de builders soupçonnaient la même chose mais se sentaient bizarres de le dire alors que tout l'écosystème poussait MCP comme l'avenir.

MCP a sa place. Mais l'instinct d'aller vers la solution complexe en premier, c'est exactement comme ça que les harnais deviennent gonflés avant de devenir utiles.

Erreur 3 : Ne jamais rien enlever

Celle-ci est sournoise parce que ça semble irresponsable. Vous avez construit quelque chose qui marche. C'est en production. L'enlever, c'est comme enlever une barrière de sécurité sur l'autoroute.

Mais les modèles s'améliorent. Et votre harnais ne le sait pas.

Le mois dernier j'ai supprimé tout un sous-système de mémoire d'OpenClaw. Récupération de contexte externe, lookups d'embeddings, injection d'historique de conversation. Ça avait pris deux semaines à construire et quatre mois à maintenir. Je l'ai supprimé un jeudi. Vendredi les chiffres racontaient l'histoire :

La latence de réponse a chuté de 2,3 secondes par requête. L'agent a arrêté d'halluciner du contexte "mémorisé" qui était en fait des données périmées d'il y a trois mois. La satisfaction utilisateur sur les interactions de support a augmenté parce que l'agent répondait à ce que les gens disaient vraiment au lieu de ce que le système de mémoire pensait être pertinent.

Le modèle (Kimi K2.5) était devenu assez bon pour maintenir le contexte dans les sessions que la couche de mémoire externe empirait activement les choses. Je payais pour une infrastructure qui dégradait mon produit.

Manus, probablement l'agent autonome le plus éprouvé en production actuellement, a appris ça à la dure cinq fois. Ils ont réécrit tout leur harnais cinq fois en six mois. Pas parce que les modèles ont changé. Parce que chaque réécriture supprimait de la complexité.

Leur version initiale utilisait un fichier todo.md que l'agent réécrivait à chaque étape pour suivre les progrès. Environ 30% de tous les tokens allaient à mettre à jour ce fichier. Ils l'ont remplacé par un planificateur sous-agent qui retourne un objet structuré et l'injecte seulement quand nécessaire.

Ils ont réduit leurs outils de dizaines de schémas MCP dynamiques à moins de 20 fonctions atomiques : bash, système de fichiers, exécution de code. Les outils MCP ne sont même plus dans la fenêtre de contexte. Ils sont exposés via CLI que l'agent appelle à travers bash.

Peak Ji, leur Chief Scientist, l'a dit sans détour : "À mesure que les modèles deviennent plus forts, on ne devrait pas construire plus d'échafaudage, on devrait se retirer du chemin du modèle."

Anthropic dit la même chose : "À mesure que les capacités des modèles augmentent, les outils dont vos modèles avaient besoin pourraient maintenant les contraindre."

Si votre harnais n'a pas rétréci en trois mois, il est probablement déjà trop gros.

Le seul pattern qui fait que tout ça marche

Les trois erreurs partagent la même cause racine : donner au modèle trop, trop tôt, trop longtemps. Douze outils quand il en fallait quatre. L'overhead MCP quand un script bash aurait suffi. Un système de mémoire injectant du contexte périmé que le modèle avait dépassé.

La solution a un nom. Divulgation progressive. Ne montrer au modèle que ce dont il a besoin, quand il en a besoin. Cacher tout le reste.

Cursor fait ça agressivement. Leur système de découverte de contexte dynamique filtre environ 47% des tokens disponibles du modèle à n'importe quelle étape donnée. Pas par accident, par architecture. Le modèle ne voit que ce qui est pertinent pour cette tâche spécifique, ce moment spécifique.

Claude Code le fait avec les skills. Vous créez un répertoire skills/, Claude ne voit que les noms de skills et de courtes descriptions au début de session. Il charge le contenu complet seulement quand il décide en avoir besoin. Lazy loading pour LLMs.

Manus le fait avec leur espace d'action en couches. Niveau 1 : 20 outils atomiques, toujours visibles. Niveau 2 : utilitaires sandbox appelés via bash, ne polluant jamais le contexte. Niveau 3 : l'agent écrit ses propres scripts pour les chaînes complexes au lieu de faire trois allers-retours LLM séparés.

L'impact sur les benchmarks est réel. Même modèle, Claude Opus 4.5, a scoré 42% sur CORE-Bench avec un scaffold générique. Avec Claude Code comme harnais, 78%. Ce n'est pas que la divulgation progressive, Claude Code apporte une meilleure gestion d'outils, configuration d'environnement, et compaction. Mais les chercheurs qui ont mené le test ont été directs : le scaffold a presque doublé le score. Le modèle n'a pas changé.

Les trois piliers ci-dessous sont comment j'applique la divulgation progressive en pratique. Outils, configuration, maintenance.

Le framework : contrats, contraintes, nettoyage

Pas un diagramme d'architecture à 47 couches. Pas un repo GitHub avec 41 définitions de skills et 11 sous-agents. Trois choses qui ont vraiment survécu au contact avec la production.

Pilier 1 : Contrats plutôt que feeling

Vous avez vu ce qui s'est passé avec les descriptions d'outils d'OpenClaw. La raison pour laquelle ça marche est mécanique : le modèle fait du pattern matching au niveau token sur votre description pour décider si un outil est pertinent pour la requête actuelle. Les descriptions vagues matchent tout. Les descriptions précises ne matchent que ce que vous voulez.

Le template que j'utilise maintenant pour toutes mes définitions d'outils, et je suggère que vous fassiez pareil pour vos trois outils les plus utilisés ce soir :

name: [tool_name]
description: [CE QUE spécifiquement il retourne, pas des noms vagues 
mais la forme réelle de sortie utile]. 
Appelez ceci quand [conditions de déclenchement spécifiques]. 
N'appelez PAS quand [cas de mauvaise utilisation commun]. 
Sortie attendue: [format et champs clés].

La ligne "N'appelez PAS quand" est celle qui change tout. Sans elle, le modèle traite chaque outil comme un peut-être. Avec elle, le modèle a un contrat.

Pilier 2 : Contraintes plutôt qu'outils

Chaque fois que vous pensez "j'ai besoin d'un nouvel outil pour ça," arrêtez-vous. Demandez d'abord : est-ce qu'une seule ligne dans CLAUDE.md peut résoudre ça à la place ?

Au lieu d'un serveur MCP de linter, une contrainte : "Lance les tests avant chaque commit." Au lieu d'un agent de vérification de style, une contrainte : "Suis les conventions dans CONVENTIONS.md." Au lieu d'un outil de planification, une contrainte : "Écris toujours plan.md avant de toucher au code."

Une contrainte dans CLAUDE.md coûte zéro token au runtime et ajoute zéro surface d'échec. Un outil coûte des tokens chaque fois qu'il est appelé, ajoute un point de décision que le modèle peut rater, et nécessite de la maintenance. Les maths sont évidentes une fois qu'on les voit.

Un CLAUDE.md de base que j'utilise vraiment comme base sur les projets. Pas un monolithe, une couche de navigation qui pointe vers des fichiers spécialisés :

## CLAUDE.md

## Rôle
Ingénieur senior. Tu planifies avant de coder. Tu testes avant de push.

## Workflow
1. Lis ce fichier + tout progress.md au début de session
2. Planifie d'abord. Écris plan.md avant l'implémentation.
3. Une fonctionnalité à la fois. Commit après chaque.
4. Lance les tests existants AVANT ET après les changements
5. Met à jour progress.md avant la fin de session

## Contraintes
- Ne jamais écraser des fichiers sans montrer un diff d'abord
- Si une tâche nécessite plus de 3 fichiers changés, la décomposer
- En cas de doute, demande. Ne devine pas la logique métier.
- Garde les commits petits et descriptifs

## Spécificités du projet
[Votre stack, conventions, fichiers clés ici]
Voir CONVENTIONS.md pour les règles de style de code.

Vingt lignes qui disent à l'agent comment travailler, pas quoi savoir. Le propre harnais d'Anthropic pour les agents long-running utilise un fichier de progression, une liste de fonctionnalités, et des commits git structurés par-dessus un noyau similaire. L'équipe Codex d'OpenAI a appris à la dure qu'un AGENTS.md géant échoue. Leur conseil : "donnez à Codex une carte, pas un manuel d'instructions de 1 000 pages."

La clé c'est la divulgation progressive appliquée à la config : un CLAUDE.md court qui pointe vers des fichiers détaillés que l'agent lit quand il en a besoin. Pas un monolithe de 500 lignes qu'il survole et ignore. Pas un stub de 10 lignes qui ne dit rien. Une couche de navigation.

Pilier 3 : Nettoyage trimestriel

Tous les trois mois, je m'assois avec mon harnais et pose cinq questions :

  1. Quels outils l'agent n'a-t-il pas appelés en 30 jours ? Les supprimer.
  2. Quelles règles CLAUDE.md existent parce que l'ancien modèle était bête ? Les enlever.
  3. Quelles barrières de sécurité sont maintenant gérées nativement par le modèle ? Les retirer.
  4. L'injection de contexte est-elle encore nécessaire ou la récupération du modèle s'est-elle assez améliorée ? Tester sans.
  5. Deux outils peuvent-ils fusionner en un avec une meilleure description ? Le faire.

Dernier trimestre sur OpenClaw : j'ai supprimé un fallback retry-with-different-model qui ne s'était pas déclenché en 6 semaines (Kimi K2.5 était devenu assez stable). J'ai enlevé trois règles CLAUDE.md sur le formatage JSON que le modèle gère maintenant nativement. J'ai fusionné deux outils de monitoring en un avec un contrat plus spécifique.

Résultat net : 30% de pièces mobiles en moins. Zéro fonctionnalité perdue. Réponses plus rapides. Moins à maintenir.

Manus fait ce processus en continu. Le test de Peak Ji : lance ta suite d'éval d'agent contre un modèle plus fort. Si les performances ne s'améliorent pas, ton harnais l'entrave. Cette question seule te dit tout sur si tu construis un échafaudage ou une cage.

Ce que ça signifie pour vous ce soir

Quinze minutes. C'est tout ce dont vous avez besoin pour vraiment commencer.

Réécrivez vos trois descriptions d'outils les plus utilisées. Trouvez les outils que votre agent appelle le plus. Ouvrez leurs descriptions. Si elles disent ce que l'outil fait au lieu de quand l'appeler et quoi attendre, réécrivez-les avec le template de contrat ci-dessus. Cinq minutes par outil. L'impact est immédiat, l'agent arrête de deviner et commence à suivre les instructions.

Puis structurez votre CLAUDE.md comme une couche de navigation. Si vous n'en avez pas encore, collez le template de base ci-dessus et remplissez les détails de votre stack. Si vous en avez déjà un, vérifiez : est-ce un monolithe ou une carte ? Déplacez les règles détaillées vers des fichiers séparés (CONVENTIONS.md, ARCHITECTURE.md) et gardez votre CLAUDE.md autour de 20-40 lignes. L'agent lit CLAUDE.md à chaque session. Il devrait trouver des directions, pas une encyclopédie.

Et supprimez une chose. Un outil. Une règle CLAUDE.md. Un hook middleware. Choisissez quelque chose que vous n'avez pas touché en un mois. Enlevez-le. Lancez votre workflow normal. Si rien ne casse, ça n'avait rien à faire là. Et si quelque chose casse, félicitations, vous venez d'apprendre ce qui compte vraiment dans votre harnais. Ça vaut plus que n'importe quel diagramme d'architecture posté sur X 💀

L'ingénierie de harnais est tendance. Donnez-lui six mois. Il y aura des cours. Des certifications. Des repos GitHub avec 41 définitions de skills, 11 sous-agents, et un README plus long que la plupart des codebases. Trois mille étoiles, zéro déploiement en production.

Pendant ce temps, les builders qui livrent vraiment des agents continueront à faire ce qu'ils faisaient avant que le mot existe. Écrire des instructions claires. Choisir des outils simples. Supprimer ce qui a arrêté de marcher.

Le harnais n'est pas un nouveau job. C'est le même job avec un meilleur nom.

Sources :

Si ces patterns vous font économiser du temps de debug ou des coûts de tokens, j'écris régulièrement sur ce genre de trucs. Contrats de prompts, architecture d'agents, les décisions d'infrastructure chiantes qui font que les agents IA marchent en production au lieu de juste dans les démos. Suivez si vous voulez les notes de terrain, pas le hype.

L'IA a fait cette image de couverture. J'alloue mon budget pixels exclusivement aux fenêtres de terminal.