L'ingénierie du harness agent

Problème : Tu as mis à jour le modèle. Les performances ont à peine bougé. Tu vois les mêmes modes d'échec, session après session, peu importe la version du modèle.

Victoire rapide : Arrête de tuner le modèle. Tune le harness. Une équipe a réduit de 15 outils à un seul appel bash et a vu la précision passer de 80% à 100% pendant que la consommation de tokens chutait de 37%.

Compréhension : Agent = Modèle + Harness. Le modèle gère le raisonnement. Le harness gère tout le reste : quels outils l'agent peut atteindre, quel contexte il reçoit, comment les erreurs remontent, comment les résultats sont vérifiés. En pratique, le harness est la contrainte principale sur les performances réelles, pas le modèle.

Ce qu'est vraiment le harness

Le harness est la couche logicielle qui entoure un modèle IA et gère tout sauf le raisonnement du modèle. Il appelle les outils. Il gère la mémoire. Il route les tâches. Il exécute les vérifications. Il décide quel contexte arrive dans la fenêtre de prompt et sous quelle forme.

La définition de Martin Fowler est précise : le harness, c'est tout dans un agent sauf le modèle lui-même. Deux directions de contrôle le traversent :

• Feedforward (guides) : oriente l'agent avant qu'il agisse. Prompts système, injection de contexte, restrictions d'outils. Ça augmente la probabilité que le premier output soit correct.
• Feedback (capteurs) : observe après que l'agent a agi et lui permet de se corriger. Linters, vérificateurs de types, exécuteurs de tests, build hooks. Ça attrape les erreurs avant qu'elles arrivent aux yeux humains.

Aucune direction seule ne suffit. Le feedback sans feedforward produit un agent qui corrige les mêmes erreurs en boucle. Le feedforward sans feedback produit un agent qui encode des règles mais n'apprend jamais quand elles ont échoué.

Pourquoi le design du harness surpasse les mises à jour de modèle

Le classement SWE-bench dit les choses clairement. Sur les benchmarks de code, le même modèle peut scorer 42% avec un scaffold et 78% avec un meilleur. Le modèle n'a pas changé. Le harness si.

Le cas Vercel est l'exemple le plus clair en circulation. Leur équipe a réduit un agent de 15+ outils à un seul outil bash. Sur leur benchmark : la précision est passée de 80% à 100%, les tokens ont chuté de 37%, et la vitesse s'est améliorée de 3,5x. Ils n'ont pas touché le modèle. Ils ont enlevé la complexité du harness.

Le pattern se répète dans toutes les équipes. L'équipe d'IA juridique de Harvey a amélioré le taux de complétion des tâches de 40,8% à 87,7% en améliorant le système autour du modèle. L'équipe d'outillage interne d'OpenAI a conclu : "Nos défis les plus difficiles portent maintenant sur la conception des environnements, des boucles de feedback et des systèmes de contrôle."

Le modèle, c'est le moteur. Le harness, c'est la voiture. Améliorer le moteur aide. Construire une meilleure voiture est généralement le levier le plus puissant.

Les cinq leviers

Tout harness est construit à partir du même ensemble de points de contrôle. Tirer les bons dans le bon ordre, c'est là que réside le savoir-faire.

1. Design des outils

Les outils disponibles pour un agent définissent sa surface de capacités. Trop d'outils et l'agent gaspille du contexte sur la désambiguïsation. Trop peu et il se rabat sur des contournements. Le résultat Vercel est la référence canonique : moins d'outils, mais plus précis, surpassent un grand toolkit généraliste.

Conçois les outils autour des résultats, pas des capacités. Un outil appelé run_tests surpasse un appelé execute_command parce que l'agent n'a pas à décider quoi exécuter.

2. Injection de contexte

Ce que l'agent sait avant d'agir détermine ce qu'il produit. L'injection de contexte, c'est mettre la bonne information dans la fenêtre de prompt au bon moment : docs d'architecture, standards de code, erreurs récentes, l'arborescence de fichiers actuelle.

Le mode d'échec, c'est la sur-injection : inonder la fenêtre avec tout ce qui est disponible. Un contexte pertinent au bon moment surpasse un grand dump indifférencié.

3. Architecture mémoire

Un agent à session unique oublie tout quand la fenêtre se ferme. Un agent correctement harnaché conserve : les décisions prises, les patterns observés, les erreurs déjà vues. La mémoire peut être à court terme (état de la conversation), à moyen terme (logs de session), ou à long terme (fichiers persistants que l'agent lit au démarrage).

Le fichier CLAUDE.md de Claude Code est un levier de mémoire à long terme. L'agent le lit au début de la session. Ce que tu y mets façonne chaque session qui suit.

4. Boucles de vérification

Le harness exécute des vérifications que l'agent ne peut pas sauter. Vérificateurs de types, linters, commandes de build, suites de tests. Quand ceux-ci s'exécutent comme des capteurs automatisés après chaque action de l'agent, les erreurs remontent dans la même session qui les a créées. Le coût de correction chute.

Le principe : garde les vérifications qualité aussi à gauche que possible. Une erreur de type attrapée avant le commit coûte des secondes. La même erreur attrapée en review coûte une heure.

5. Design des contraintes

Ce que l'agent ne peut pas faire compte autant que ce qu'il peut. Restreindre l'accès en écriture aux configs de production, bloquer certains appels d'outils, limiter quels fichiers un agent peut toucher sont tous des leviers de contrainte. L'objectif n'est pas d'entraver l'agent mais d'éliminer la classe d'erreurs que les contraintes rendent impossibles.

Le paradoxe des contraintes

Ajouter plus de règles à un agent ne produit pas forcément un meilleur comportement. C'est le paradoxe des contraintes : un harness surchargé d'instructions peut dégrader les performances en dessous de ce que l'agent atteint avec un guidage minimal.

Le mécanisme est simple. Chaque contrainte prend du contexte. Des règles contradictoires créent du bruit que l'agent doit naviguer. Un long jeu d'instructions qui couvre chaque cas limite performe souvent moins bien qu'un court et clair qui couvre les cinq plus importants.

La résolution pratique, c'est la priorisation. Identifie les modes d'échec qui se répètent vraiment. Écris des contraintes pour ceux-là. Laisse tout le reste au jugement du modèle. Le harness doit éliminer les échecs qui arrivent souvent, pas tenter d'énumérer chaque mauvais résultat possible.

Contrôles computationnels vs. inférentiels

Les contrôles du harness se divisent en deux types.

Les contrôles computationnels sont déterministes et rapides. Vérificateurs de types, linters, exécuteurs de tests, systèmes de build. Ils s'exécutent en millisecondes à secondes. Les résultats sont fiables et assez bon marché pour tourner sur chaque action de l'agent.

Les contrôles inférentiels utilisent un modèle comme juge. Agents de code review, vérifications qualité sémantiques, patterns "LLM-as-evaluator". Ils sont plus lents, plus coûteux, et non-déterministes. Ils attrapent ce que les contrôles computationnels ratent : la duplication sémantique, les patterns mal appliqués, les instructions mal comprises.

Le découpage pratique : exécute les contrôles computationnels sur chaque changement, automatiquement. Exécute les contrôles inférentiels de façon sélective, sur les changements à plus fort enjeu ou post-intégration. Les deux couches sont complémentaires, pas concurrentes.

Trois catégories de harness

Un harness régule différentes dimensions de l'output agent. Les distinguer aide parce que les bons contrôles diffèrent selon la catégorie.

Harness de maintenabilité : guides et capteurs autour de la qualité du code, du style, et de la structure. C'est la catégorie la plus facile à construire. L'outillage existant (linters, vérificateurs de types, outils de couverture) se branche directement. La plupart des équipes commencent ici.

Harness de fitness architecturale : guides et capteurs qui appliquent des contraintes structurelles. Frontières de modules, règles de dépendances, budgets de performance. Les fitness functions s'exécutent comme des vérifications automatisées. La dérive architecturale est attrapée plutôt que découverte des mois plus tard en review.

Harness de comportement : guides et capteurs autour de la correction fonctionnelle. C'est la catégorie la plus difficile. Les suites de tests générées par IA ne sont pas encore assez fiables pour se substituer entièrement au comportement spécifié. La plupart des équipes combinent actuellement des documents de spécification (feedforward) avec des tests générés par IA plus une vérification manuelle sélective (feedback). Le problème ouvert est de construire suffisamment de confiance dans les tests générés par l'agent pour réduire la supervision manuelle.

Points de départ pour Claude Code

Claude Code expose plusieurs leviers de harness directement.

CLAUDE.md est ton principal contrôle feedforward. Décisions d'architecture, conventions de nommage, patterns à suivre ou éviter, règles explicites sur ce que l'agent ne doit pas faire. Ce fichier se charge à chaque démarrage de session. Ce que tu y mets façonne le comportement par défaut de l'agent sans aucun prompting.

.claude/agents/ les définitions de spécialistes te permettent de contraindre la portée par agent. Un agent de base de données qui ne peut toucher que les fichiers de migration ne peut pas accidentellement modifier des composants frontend. La restriction de portée est l'une des contraintes les moins coûteuses à ajouter.

Les hooks te permettent de câbler des capteurs computationnels dans la boucle de l'agent. Un hook post-édition qui exécute le vérificateur de types signifie que chaque changement de fichier est validé avant que l'agent passe à la tâche suivante.

Les règles de permissions dans settings.json définissent quels outils l'agent peut accéder. Commencer avec moins d'outils et élargir est mieux que commencer avec tout et essayer de restreindre ensuite.

Le bon harness ne vise pas à éliminer entièrement l'input humain. Il dirige l'attention humaine là où elle compte le plus : les décisions que les capteurs ne peuvent pas attraper et que le jugement, pas les règles, doit résoudre.

Questions fréquentes

C'est quoi l'ingénierie du harness agent ?

L'ingénierie du harness agent, c'est la pratique de concevoir tout autour d'un modèle IA sauf le modèle lui-même. Ça inclut la sélection d'outils, l'injection de contexte, l'architecture mémoire, les boucles de vérification, et le design des contraintes. Le harness détermine quelle information l'agent reçoit, quelles actions il peut prendre, et comment les erreurs sont détectées et corrigées avant d'atteindre la review humaine.

Pourquoi le harness compte plus que le modèle ?

Sur les benchmarks de code SWE-bench, le même modèle score 42% avec un scaffold et 78% avec un meilleur. Vercel a retiré 80% des outils de leur agent et a vu la précision passer de 80% à 100% avec 37% moins de tokens utilisés. Le raisonnement du modèle est fixe. Le harness détermine quelle part de cette capacité de raisonnement atteint réellement la tâche.

C'est quoi un scaffold d'agent IA ?

Un scaffold est la couche structurelle construite autour d'un modèle IA pour permettre des tâches complexes multi-étapes. Il fournit à l'agent des outils à appeler, de la mémoire à lire et écrire, une boucle à re-exécuter après des erreurs, et des signaux de feedback pour se corriger. Scaffold et harness sont utilisés de façon interchangeable dans la plupart des contextes. La distinction, quand elle est faite, est qu'un harness met l'accent sur le contrôle et la gouvernance tandis qu'un scaffold met l'accent sur la structure et l'enablement.

Comment construire un bon harness agent ?

Commence avec les cinq leviers dans l'ordre : design des outils d'abord, puis injection de contexte, puis mémoire, puis boucles de vérification, puis contraintes. Pour chaque levier, identifie les modes d'échec que tu observes vraiment, pas les théoriques. Construis le contrôle le plus simple qui prévient chaque échec. Exécute les vérifications computationnelles (vérificateur de types, linter, tests) automatiquement après chaque action de l'agent. Ajoute les contrôles inférentiels seulement là où les computationnels ne peuvent pas atteindre.

C'est quoi le paradoxe des contraintes dans les agents IA ?

Ajouter plus de contraintes n'améliore pas forcément le comportement de l'agent. Un long jeu de règles exhaustif performe souvent moins bien qu'un court et clair parce que chaque contrainte consomme du contexte et des règles contradictoires créent du bruit. La résolution, c'est la priorisation : identifie les modes d'échec qui se répètent le plus souvent et écris des contraintes seulement pour ceux-là. Laisse tout le reste au jugement du modèle.

Pourquoi Vercel est passé de 15+ outils à un seul ?

L'équipe de Vercel a trouvé qu'un large ensemble d'outils forçait leur agent à dépenser du contexte sur la désambiguïsation, décidant quel outil appeler plutôt que comment résoudre le problème. Passer à un seul outil bash a supprimé cette surcharge. La précision est passée de 80% à 100%, les tokens ont chuté de 37%, et la vitesse s'est améliorée de 3,5x sur leur benchmark. Le principe : moins d'outils, mais plus précis, surpassent un grand toolkit généraliste.

Explorer plus de concepts agents :

• Patterns d'agent - Formes d'orchestration pour le travail multi-agent
• Fondamentaux des agents - Sub-agents, slash commands, et personas CLAUDE.md
• Design de sub-agent - Patterns d'architecture pour coordonner plusieurs agents
• Orchestration d'équipe - Boucles builder et validator en pratique
• Agents personnalisés - Écrire des définitions d'agent spécialiste