Qu'est-ce que le harness engineering : rendre un agent IA utilisable en pratique

Le harness engineering en termes simples

Le harness engineering est la discipline qui consiste à construire autour d'un modèle de langage un environnement dans lequel il accomplit de manière fiable un travail réel. Le mot « harness » désigne le harnais qui sert à diriger un animal puissant. Le modèle est puissant, mais il ne sait pas, à lui seul, où aller, quels outils utiliser ni quand s'arrêter. Le harnais canalise cette puissance.

La formulation la plus courte est la suivante :

Agent = Modèle + Harnais

Le modèle, ce sont les poids et la capacité à raisonner et à écrire du texte ou du code. Le harnais, c'est tout le reste : les instructions système et les fichiers comme CLAUDE.md ou AGENTS.md, l'ensemble des outils (shell, édition de fichiers, serveurs MCP), le bac à sable dans lequel l'agent exécute ses commandes, les fichiers d'état qui survivent entre les sessions, ainsi que les tests, les linters et les hooks qui signalent à l'agent ses erreurs. Sans harnais, il ne reste qu'un chat capable de répondre par du texte.

Pourquoi l'agent est « tantôt senior, tantôt junior »

Le scénario est familier : dans un dépôt, l'agent travaille comme un développeur chevronné ; dans un autre, il se perd, oublie les décisions de la veille et annonce « terminé » pour une fonctionnalité qui ne marche pas. La première réaction consiste à passer à un modèle plus récent. Cela aide rarement, car le modèle est le même dans les deux cas. La différence tient à l'environnement.

C'est le changement de perspective principal par lequel commence le harness engineering : l'agent n'est pas défectueux, c'est ce qui l'entoure qui l'est. Un agent ne peut pas lancer les tests s'il n'y a pas accès. Il ne se souviendra pas de ce qu'il a déjà essayé si rien ne l'a consigné. Il ne saura pas qu'une fonctionnalité est cassée si aucune vérification ne le lui dit. Ce ne sont pas des « traits de caractère » du modèle, mais des défauts de conception, qui se corrigent de façon systématique.

Symptômes typiques d'un mauvais harnais

• Chaque nouvelle session commence par la réparation de l'environnement : mauvaises dépendances, base de données qui ne démarre pas, variables manquantes.
• L'agent reproduit des solutions déjà rejetées, car il ne se souvient pas de la session précédente.
• Une règle est écrite noir sur blanc dans les instructions, mais l'agent l'ignore.
• « Les tests sont verts », pourtant la fonctionnalité est cassée, parce que les tests vérifiaient autre chose.
• L'agent entreprend trois tâches à la fois et n'en termine aucune.

De quoi se compose un harnais : cinq sous-systèmes

Une erreur fréquente consiste à considérer le harnais comme un simple fichier de prompt. En réalité, ce sont cinq mécanismes, et chacun tombe en panne à sa manière.

Instructions

Les instructions répondent à la question : l'agent trouvera-t-il la règle dont il a besoin ? Un bon fichier d'entrée est une carte, pas un manuel : une courte table des matières avec les commandes de vérification et les contraintes strictes, les détails figurant dans des documents séparés que l'agent ouvre au besoin. De bonnes instructions énoncent des invariants (« toutes les requêtes SQL sont paramétrées ») plutôt que de dicter l'implémentation ligne par ligne.

Outils

L'agent ne peut vérifier que ce à quoi il a accès. S'il ne peut pas lancer le linter, aucune règle du type « lance le linter avant chaque commit » ne fonctionnera. Les outils sont branchés par les capacités intégrées de l'agent (lecture et modification de fichiers, exécution de commandes) et par MCP, un protocole qui donne accès aux bases de données, aux navigateurs et aux gestionnaires de tâches.

Environnement

L'environnement est l'endroit où l'agent exécute ses commandes. Il doit démarrer avec une seule commande, rester identique d'une session à l'autre et limiter les dégâts d'une erreur : un bac à sable sans accès à la production, une branche ou une copie de travail dédiée, et la possibilité de tout remettre dans l'état initial en une minute.

État

Un modèle n'a pas de mémoire entre les sessions : tout ce qui n'est pas écrit dans le dépôt disparaît avec la fenêtre de contexte. C'est pourquoi l'objectif, ce qui a été fait, les décisions prises, les impasses et la prochaine étape doivent vivre dans des fichiers. Test simple : ouvrez une nouvelle session, dites à l'agent « continue » et observez s'il se met au travail ou s'il demande ce qu'il doit faire.

Retour d'information

Les boucles de retour sont le sous-système le plus important. Sans elles, l'agent est son propre seul juge et considère honnêtement la tâche comme terminée. Tests, vérification de types, linter, hook exécuté après chaque modification, scénario E2E dans un navigateur : tout cela renvoie à l'agent un signal rouge tant que l'erreur reste peu coûteuse à corriger.

Le harnais est une boucle, pas une liste

Les cinq sous-systèmes fonctionnent comme une boucle fermée. Le modèle reçoit des instructions, agit par les outils dans l'environnement, apporte des modifications au dépôt, et la vérification contrôle le résultat. Un résultat rouge revient au modèle pour correction, un résultat vert est consigné dans l'état. L'état met à son tour à jour les instructions de la session suivante.

instructions → modèle → outils → environnement → modifications
                ↑                                  ↓
                └──── rouge ── vérification ────────┘
                                     ↓ vert
                                 état → (session suivante)

Supprimez une flèche et la boucle se rompt à cet endroit. Sans vérification, l'agent n'apprend pas ses erreurs. Sans état, la session suivante commence par de l'archéologie au lieu du travail. C'est pourquoi investir dans un sous-système ne compense pas une lacune dans un autre : un AGENTS.md de cinq pages ne remplace pas des tests manquants.

En quoi le harness engineering diffère du prompt et du context engineering

Ces notions sont imbriquées les unes dans les autres ; elles ne se concurrencent pas.

Le prompt engineering fait partie du sous-système des instructions. Le context engineering couvre les instructions et l'état : ce que l'agent voit à chaque instant. Le harness engineering ajoute ce qui ne tient pas du tout dans la fenêtre de contexte : les droits d'accès, le bac à sable, les tests, les hooks, le processus de travail. Un prompt bien écrit ne sert à rien si l'agent ne peut pas physiquement lancer les tests.

Pourquoi un harnais est nécessaire : les mathématiques des tâches longues

Il paraît intuitif qu'un modèle qui réussit 95 % des étapes soit presque parfait. Mais une tâche d'agent comporte de nombreuses étapes, et les erreurs s'accumulent. Si les étapes sont indépendantes, la probabilité de les franchir toutes sans erreur est le produit de leurs probabilités :

0.95 ^ 10 ≈ 0.60
0.95 ^ 20 ≈ 0.36
0.95 ^ 50 ≈ 0.08

À la dixième étape, seule environ 60 % des exécutions passent sans la moindre erreur ; à la cinquantième, moins d'une sur dix. Améliorer le modèle jusqu'à 97 % coûte cher et ne dépend pas de vous. En revanche, attraper l'erreur à l'étape même où elle survient et la renvoyer à l'agent relève du harnais. Une boucle de retour transforme une chaîne où « une erreur entraîne la suivante » en une suite de petites étapes corrigeables.

Exemple : le même agent dans deux dépôts

Tâche : ajouter à un backend de paiement en FastAPI une remise par code promo.

Sans harnais

L'agent lit quelques fichiers, écrit une fonction de calcul de la remise et un test unitaire qui vérifie cette fonction de façon isolée. Le test est vert, l'agent écrit « terminé ». Il ignorait que le total final est calculé dans un autre module, et il ne pouvait ni démarrer la base de données ni dérouler tout le scénario de commande. Un jour plus tard, on constate que la remise n'est pas appliquée au panier.

Avec harnais

À la racine se trouve un AGENTS.md de quelques dizaines de lignes : comment préparer l'environnement, quelles commandes de vérification sont obligatoires, où est décrite l'architecture des paiements. L'environnement démarre avec docker compose up -d. Le dépôt contient un fichier de plan avec un critère d'achèvement : « le scénario E2E de commande avec code promo passe ». Après chaque modification, un hook lance le linter et la vérification de types ; avant de conclure, l'agent doit exécuter le test E2E.

# AGENTS.md (extrait)
## Vérification — obligatoire avant d'écrire « terminé »
make lint        # ruff + mypy
make test        # pytest, unitaires et d'intégration
make e2e         # scénario de commande

## MUST
- Les montants sont calculés en centimes (int), jamais en float
- Toutes les requêtes SQL sont paramétrées
- Ne pas toucher aux migrations déjà appliquées en production

Le modèle est le même. Mais désormais, l'agent trouve le module qui calcule le total grâce à la carte du projet, le test E2E échoue dès la première tentative, l'agent voit que la remise n'atteint pas le panier, la corrige, et ne rend compte qu'après une exécution verte. La différence de résultat est entièrement le fait du harnais.

Par où commencer

1. Décrivez comment l'agent vérifie son propre travail : une à trois commandes qu'il doit impérativement lancer. Le retour d'information produit le plus grand effet, commencez donc par lui.
2. Rendez l'environnement reproductible : il démarre avec une seule commande, et il existe un moyen rapide de revenir en arrière.
3. Créez un fichier d'état : l'objectif, ce qui a été fait, les décisions et les impasses, la prochaine étape.
4. Réduisez les instructions à une carte : commandes de vérification, contraintes strictes, liens vers les documents détaillés.
5. Tenez un journal des échecs de l'agent : pour chaque échec, notez le sous-système qui l'a laissé passer. Ce journal indiquera quoi corriger ensuite.

Une pratique utile consiste à noter chacun des cinq sous-systèmes de 1 à 5, à consacrer une demi-heure au plus faible, puis à exécuter le même lot de tâches types avant et après. Les améliorations du harnais deviennent ainsi mesurables, au lieu d'être jugées « au ressenti ».

Synthèse

Le harness engineering porte non sur le modèle, mais sur tout ce qui l'entoure : instructions, outils, environnement, état et boucles de retour. La fiabilité d'un agent est déterminée par le maillon le plus faible de cette boucle ; c'est pourquoi changer de modèle guérit rarement l'instabilité, alors qu'un test ajouté ou un fichier de plan y parvient souvent. Les cinq sous-systèmes et l'assemblage complet du harnais sont traités en pratique dans le cours sur le harness engineering.