Harness vs context engineering : en quoi le harness engineering diffère du prompt et du context engineering

En bref : trois niveaux pour une même tâche

Le prompt engineering répond à la question « comment demander ? », le context engineering à la question « que doit savoir le modèle à l'instant présent ? », le harness engineering à la question « dans quel environnement l'agent travaille-t-il, et comment apprend-il qu'il s'est trompé ? ». Il ne s'agit pas de trois approches concurrentes, mais de niveaux imbriqués : un bon prompt fait partie d'un bon contexte, et un contexte bien pensé est l'un des sous-systèmes du harnais.

La confusion vient de ce que les trois modifient le comportement du modèle, mais avec des leviers différents. Si l'agent ne peut pas lancer les tests, aucune formulation du prompt ne le corrigera. Si l'agent oublie les décisions de la veille, le problème ne réside pas dans les mots de la requête mais dans l'endroit où l'état est conservé. Comprendre la différence entre harness et context engineering fait gagner des semaines : vous cessez de réécrire les instructions là où c'est l'environnement qui est défaillant.

Prompt engineering : la formulation d'une requête

Le prompt engineering consiste à travailler le texte de la requête : rôle, tâche, format de réponse, exemples (few-shot), contraintes, ordre des étapes. L'unité de travail est un appel au modèle. Le résultat se juge sur la réponse : est-elle correcte, dans le bon format, le modèle est-il resté sur le sujet ?

Techniques typiques :

• décrire explicitement le format de sortie (schéma JSON, tableau, liste) ;
• donner 2 à 3 exemples « entrée → sortie correcte » ;
• demander un raisonnement étape par étape avant la réponse ;
• séparer les instructions et les données par des délimiteurs clairs ;
• énumérer ce qui ne doit pas être fait.

Le prompt engineering fonctionne bien pour les tâches « une entrée — une sortie » : classification, extraction de données, traduction, génération de texte à partir d'un modèle. Son plafond apparaît lorsque le modèle se met à agir : appeler des outils, modifier des fichiers, enchaîner des dizaines d'étapes. Là, la qualité ne dépend plus d'une phrase, mais de tout ce qui entoure le modèle.

Context engineering : ce qui entre dans la fenêtre du modèle

Le context engineering consiste à gérer le contenu de la fenêtre de contexte à chaque étape. La fenêtre est limitée, et l'agent accumule, au fil d'une longue session, les sorties de commandes, le contenu des fichiers et l'historique de la conversation. L'enjeu est d'avoir à chaque instant ce qui est nécessaire, et rien de superflu.

Cela recouvre :

• la sélection : quels fichiers, documents et extraits de code charger pour la tâche (recherche, RAG, lecture à la demande) ;
• la compression : résumer un long historique, tronquer les sorties de commandes, compacter la session ;
• la structure : un fichier d'instructions d'entrée qui fait office de table des matières, les détails étant placés dans des documents séparés que l'agent ouvre quand il en a besoin ;
• l'isolation : confier une sous-tâche à un sous-agent doté de son propre contexte propre, afin que le fil principal ne soit pas encombré.

La métrique du context engineering est de savoir si l'agent a trouvé la bonne règle ou la bonne information au bon moment, et s'il ne s'est pas noyé dans le bruit. Symptôme typique du problème : une règle est écrite dans CLAUDE.md, mais l'agent la transgresse, parce que le fichier fait cinq pages et que la règle s'est perdue parmi le ton à adopter et les motifs préférés du responsable d'équipe.

Harness engineering : tout ce qui entoure le modèle

Le harnais (harness, « le harnachement ») est l'environnement dans lequel travaille l'agent. Le modèle n'y est qu'un composant, qui entre dans la boucle une seule fois. Tout le reste — instructions, outils, environnement, état et retour d'information — est conçu par un ingénieur. Le harness engineering veille à ce que l'agent puisse non seulement écrire du code, mais aussi l'exécuter, le vérifier, apprendre qu'il y a une erreur et reprendre le lendemain au même endroit.

Il est pratique de décomposer le harnais en cinq sous-systèmes :

Dans ce schéma, le context engineering vit à l'intérieur des deux premiers sous-systèmes : il décide comment les instructions et les sorties d'outils entrent dans la fenêtre. Le harnais ajoute ce qu'on ne peut pas mettre dans le contexte : une commande de vérification qui fonctionne, un environnement reproductible, un fichier d'état qui survit à un redémarrage.

Tableau comparatif

Pourquoi un prompt et un contexte ne suffisent pas

Scénario classique : l'équipe constate que l'agent se trompe et passe une semaine à rédiger un AGENTS.md de cinq pages. L'agent ne lance toujours pas le linter avant le commit. La cause ne tient pas au texte : l'agent n'a tout simplement pas accès à un shell avec les bons droits, et le linter n'est pas installé dans l'image. C'est un problème d'outils et d'environnement, et on le traitait avec des instructions.

Deuxième scénario : pour la troisième session d'affilée, l'agent corrige le même bug, parce qu'après un redémarrage il ne se souvient pas de ce qu'il avait déjà essayé. Le context engineering à l'intérieur d'une session n'aide pas ici : la fenêtre est vidée. Il faut le sous-système d'état — un fichier dans lequel l'agent consigne ses tentatives et ses décisions, et une règle qui l'oblige à le lire au début du travail.

Le troisième scénario est le plus coûteux : l'agent écrit « terminé », les tests unitaires sont verts, mais la fonctionnalité ne marche pas. Ni un prompt du type « vérifie soigneusement », ni des documents supplémentaires dans le contexte ne donneront à l'agent une vérification indépendante. Seul un retour d'information venant d'une machine le peut : un test de bout en bout, un script de vérification, un vérificateur distinct sans accès aux raisonnements de l'exécutant.

Conclusion générale : le prompt et le contexte agissent sur ce que le modèle pense. Le harnais agit sur ce que le modèle peut faire et sur ce qu'il apprend après une action.

Pourquoi changer de modèle ne suffit pas

Une réaction courante face à un agent instable consiste à prendre un modèle plus puissant. Cela ne guérit généralement rien : le même modèle travaille comme un senior sûr de lui dans un dépôt bien organisé, mais se perd dans un dépôt sans commandes de vérification ni description de la pile technique. Un modèle plus puissant ne devinera pas les conventions de votre équipe, n'obtiendra pas un accès à une base de données auquel il n'a pas droit, et n'apprendra pas qu'une migration est cassée si personne ne l'a exécutée.

Le harnais, en revanche, ne devient pas obsolète avec l'arrivée de nouveaux modèles. Des instructions, un environnement reproductible et des vérifications sont nécessaires à tout modèle. Ce qui change, c'est la quantité de micromanagement manuel qu'on peut supprimer : un modèle fort se contente d'invariants (« les données sont validées à la frontière du domaine »), et non de consignes pas à pas.

Comment savoir quel niveau corriger

Le diagnostic par symptômes est plus rapide que n'importe quelle expérimentation :

Par où commencer le harnais

Si l'on construit à partir de zéro, l'ordre pratique est : retour d'information → instructions → état → environnement → outils. Le retour d'information vient en premier, car sans lui on ne peut pas mesurer l'effet des autres changements. Tant qu'il n'existe pas de commande qui indique honnêtement « ça marche ou non », toute amélioration des instructions se juge à l'œil.

Un démarrage minimal ressemble à ceci :

# AGENTS.md (extrait)
## Comment vérifier
- make check   # lint, types, tests unitaires
- make e2e     # scénarios de bout en bout
Une fonctionnalité n'est prête que si les deux commandes se terminent avec le code 0.

## Règles
- MUST : toutes les requêtes SQL sont paramétrées
- MUST : lancer make check avant chaque commit
- Détails sur les paiements : docs/payments.md (à lire si la tâche concerne les paiements)

Remarquez la dernière ligne : c'est le context engineering à l'intérieur du harnais. Le fichier d'entrée est une carte, non un manuel ; les détails se chargent sous la condition « si ».

Comment mesurer la contribution de chaque élément

Le harnais dispose d'une métrique que n'a pas un prompt : la part des tâches que l'agent a déclarées prêtes et qu'une vérification indépendante n'a pas confirmées. On l'appelle l'écart de vérification (verification gap). Prenez 10 tâches à la suite et notez pour chacune si l'agent a dit « terminé » et si la vérification a réussi : vous obtenez un chiffre auquel comparer les changements.

Pour voir quel sous-système a un effet, on recourt à l'ablation : on fixe le modèle et l'ensemble des tâches, puis on désactive tour à tour une partie du harnais et on observe la chute. Deux points importent. Mieux vaut commencer non pas par l'ablation, mais par un journal des échecs : étiqueter la couche où les choses ont cassé montre le goulot d'étranglement plus vite. Et une chute nulle ne prouve pas qu'un composant est inutile : il se peut simplement que les tâches choisies ne l'aient pas sollicité.

Erreurs fréquentes

• Prendre un fichier de prompt pour le harnais. Les instructions ne sont qu'un sous-système sur cinq. Une étagère de recettes n'est pas encore une cuisine.
• Corriger l'absence d'outils par du texte. « Lance toujours les tests » ne sert à rien si les tests ne peuvent pas être lancés dans l'environnement de l'agent.
• Alourdir les instructions. Plus le fichier d'entrée est long, plus il y a de risques qu'une règle importante ne soit pas lue. Mieux vaut transformer les règles importantes en vérifications exécutables.
• Faire confiance à l'auto-évaluation de l'agent. Un modèle qui évalue son propre travail tend à le surestimer. La vérification doit être faite par un script ou par un agent distinct au contexte propre.
• Configurer le harnais une fois pour toutes. Il vieillit comme le code : les règles s'écartent de la réalité, les commandes changent. Il doit être révisé régulièrement.

Synthèse

Le prompt engineering améliore la formulation, le context engineering sélectionne ce qui entre dans la fenêtre du modèle, le harness engineering conçoit tout l'environnement de l'agent, y compris les outils, l'environnement, l'état et les vérifications. Quand un agent travaille longtemps et modifie lui-même le code, le harnais devient l'élément principal : il transforme « l'agent a dit terminé » en « le système a vérifié que ça marche ». Le choix entre harness et context engineering n'est donc pas un dilemme : le contexte fait partie du harnais, et il faut corriger le sous-système que désignent les symptômes. Ce sujet est traité en pratique dans le cours sur le harness engineering, à travers un projet de backend de paiement.