Ingénierie de harnais IA pour les agents de code

Publié le

14 juil. 2026

Mis à jour le

15 juil. 2026

Temps de lecture

20 min de lecture

Périmètre : l'ingénierie de harnais IA, pas une discipline normalisée

Dans ce guide, l'ingénierie de harnais IA (AI Harness Engineering) désigne l'ingénierie pratique de l'environnement autour des agents de code : contrat de tâche, contexte du dépôt, outils, limites d'exécution, boucles de retour et contrôles de mise en production. Elle concerne les agents qui inspectent, modifient, testent et proposent des changements logiciels. Ce n'est pas une discipline établie et normalisée, ni un synonyme de LLMOps de production : la cible reste un changement logiciel vérifiable avant qu'il soit fusionné ou déployé. Elle traite quatre surfaces comme des problèmes de conception distincts — le contrat de tâche, le contexte du dépôt, les limites d'outils et d'exécution, et l'évaluation — car un contrat bien écrit ne compense pas un dépôt illisible, ni un bac à sable généreux un critère de réussite vague.

Cette discipline change d'échelle de la même façon qu'une couche d'orchestration edge managée : dès que des dizaines de services se retrouvent derrière un point d'entrée unique, les garde-fous entourant un changement automatisé doivent rester cohérents et vérifiables indépendamment, sans être réinventés dépôt par dépôt. La valeur se loge dans les contrats et les contrôles qui relient les systèmes entre eux — exactement le principe qu'Optimi applique à l'orchestration de fournisseurs best-of-breed sur l'edge d'un client.

Cette expression est utile, car la capacité d'un modèle ne constitue pas à elle seule un système de livraison : le même modèle peut produire un correctif à faible risque dans un dépôt et un changement dangereux dans un autre si le contexte disponible, les permissions ou les conditions d'arrêt diffèrent. La discussion d'OpenAI de février 2026 sur le harness engineering souligne l'importance de structurer le travail autour de Codex ; les travaux d'Anthropic sur les agents de longue durée montrent de même l'intérêt d'un état propre et d'artefacts explicites de passation.

Définir des contrats de tâche avant d'accorder des outils

Une tâche utile est un contrat borné, et non une simple demande comme « corriger les tests défaillants ». Donnez à l'agent un énoncé du problème, les répertoires autorisés, les éléments hors périmètre, le comportement attendu et la voie d'escalade en cas d'ambiguïté ; liez l'issue ou l'incident plutôt que de coller un historique sans limite dans son contexte.

Prenons un même scénario du début à la fin de ce guide : le service checkout-api d'Acme Shop doit rejeter un calcul de taxe lorsque le pays du panier est manquant. L'issue ACME-1842 relie une requête en échec et un test d'acceptation ; l'agent ne peut modifier que services/checkout-api/** et ses tests, jamais le paiement, l'infrastructure, les verrous de dépendances ou la configuration de déploiement. Une exécution bien bornée produit soit un petit correctif avec preuves reproductibles, soit une escalade concise qui conserve la branche, les échecs et la décision attendue d'un humain.

Les contrats de tâche devraient aussi porter un budget de changement : un plafond numérique de fichiers touchés et de lignes modifiées, fixé avant le démarrage de l'exécution. ACME-1842 porte sur un seul fichier, donc un plafond de deux fichiers et quarante lignes reste généreux plutôt que strict — et comme c'est la barrière CI qui l'impose, et non le prompt, toute dérive de périmètre est arrêtée plutôt que justifiée après coup, pas seulement signalée.

Pour chaque tâche, décidez du résultat maximal autorisé :

• Investigation en lecture seule : constats et étapes de reproduction, sans écriture.
• Correctif local : un diff et des tests, avec approbation humaine avant fusion.
• Branche ou pull request : une proposition validée par CI, toujours soumise aux règles de protection du dépôt.
• Fusion ou déploiement automatisé : uniquement pour une catégorie de changements étroite et évaluée à plusieurs reprises, avec restauration et responsabilité explicites.

Commencez par l'option la moins autonome capable d'accomplir le travail. Un test qui réussit constitue une preuve sur le comportement, pas une autorisation générale de fusionner, faire tourner des identifiants, modifier l'infrastructure ou contacter des systèmes externes.

Rendre le contexte du dépôt navigable

Les agents de code ont besoin d'un chemin vers les faits pertinents, pas d'un export complet du dépôt. Placez des instructions stables près du travail : un guide de contribution à la racine, des conventions au niveau des répertoires lorsqu'elles diffèrent réellement, et des commandes qui expliquent comment valider un changement — par exemple un fichier services/checkout-api/AGENTS.md qui nomme la commande de test de contrat propre au service et interdit l'export de fixtures depuis des données de production. Rendez les décisions d'architecture, les limites de dépendances et les exigences de déploiement faciles à découvrir par de courts documents et des noms prévisibles.

Une séquence initiale efficace est déterministe : identifier l'arbre de travail et la branche courante, lire les instructions racine puis locales, inspecter les changements récents et la zone concernée par la tâche, exécuter une vérification de référence rapide, puis sélectionner les plus petits fichiers pertinents. Cela réduit le contexte gaspillé et révèle une défaillance préexistante avant qu'un agent ne l'attribue à son propre correctif.

Le contexte du dépôt doit répondre à ces questions sans inférence :

• Quelle commande est la vérification locale rapide et laquelle fait autorité dans la CI ?
• Quels fichiers sont générés, contiennent des secrets, ou sont interdits ?
• Qui est responsable du composant et quelles preuves sont requises pour un changement risqué ?
• Comment un agent ultérieur ou un examinateur peut-il reconstituer la décision depuis la branche et les journaux ?

Les conseils d'Anthropic pour les agents de longue durée utilisent des artefacts structurés d'avancement pour préserver l'état entre les sessions. Adoptez cette idée de manière sélective : liens vers les issues, historique des commits, rapports de test et courtes notes de passation comme état durable. Ne laissez pas la mémoire libre d'un agent devenir la seule trace d'une décision qui affecte la production. Le format ouvert AGENTS.md, désormais partagé par plusieurs éditeurs d'agents de code, donne un emplacement prévisible pour ces instructions plutôt qu'une convention propre à chaque outil.

Concevoir la boucle d'agent de code : un parcours déterministe court

La conception de la boucle d'agent de code décide de ce que l'agent fait tour par tour, pas seulement de ce qu'il a le droit de toucher. Les instructions racine doivent dire à tout contributeur — humain ou agent — comment établir une référence propre, localiser la carte du dépôt, exécuter la vérification rapide et rapporter des preuves ; les instructions locales ne s'y ajoutent que là où les règles diffèrent réellement.

Le premier passage doit être déterministe :

1. Consigner la branche, le commit de base, l'identifiant de tâche et la version du harnais.
2. Lire les instructions racine et locales, puis exécuter le test de référence déclaré avant toute modification.
3. Effectuer le plus petit changement autorisé et un test de régression ciblé.
4. Exécuter les vérifications locales requises, puis soumettre le diff et les preuves à la CI et à la revue.
5. Plafonner les relances d'appels d'outils et la taille des sorties ; une commande qui échoue deux fois de la même manière est un signal d'arrêt, pas une invitation à réessayer.

Ne remplacez pas cette boucle par « relire son propre travail » : une critique produite par le modèle peut fournir un contexte utile, mais elle ne remplace pas un vérificateur. La discussion d'OpenAI sur le harness engineering et les conseils d'Anthropic pour les agents de longue durée insistent tous deux sur l'idée de structurer le travail, l'état et les retours autour de l'agent plutôt que de s'appuyer sur la seule capacité du modèle.

Deux modes de défaillance appartiennent à la boucle elle-même. Une sortie d'outil non bornée donne à l'agent davantage d'éléments à perdre de vue, pas davantage d'information utile : tronquez et résumez plutôt que de tout renvoyer. Et les tentatives silencieuses, où une commande en échec est relancée avec des changements cosmétiques au lieu de s'arrêter, masquent un blocage réel derrière une activité apparente. Traitez un échec identique répété comme un arrêt automatique, au même titre qu'un test de référence en échec.

Concevoir des outils et permissions bornés

Les définitions d'outils font partie de l'interface entre l'agent et l'ordinateur. Un outil doit exposer la plus petite action utile, valider ses entrées, renvoyer des échecs lisibles par machine et rendre les actions dangereuses difficiles à exprimer : un outil d'inspection de déploiement renvoie l'état d'une release sans accepter de shell arbitraire ; un outil d'écriture dans le dépôt rejette les chemins hors de l'arbre de travail de la tâche.

Séparez les capacités de lecture, écriture, exécution, réseau et approbation. L'agent qui peut inspecter un incident n'a pas besoin d'un accès shell à la production ; celui qui peut modifier un dépôt applicatif n'a pas besoin des identifiants cloud. Les guides d'OWASP sur les LLM et l'IA générative s'appliquent ici : injection de prompt, divulgation d'informations sensibles, risques de chaîne d'approvisionnement et autonomie excessive deviennent des risques concrets de livraison dès qu'un contenu de dépôt non fiable peut influencer un agent privilégié.

Le texte d'un prompt peut orienter le comportement ; il ne peut pas imposer l'isolation du système de fichiers, la sortie réseau, la protection des branches ou le périmètre des identifiants. C'est pourquoi une couche de politique hors du modèle doit porter les contrôles qui doivent impérativement tenir : pour Acme Shop, un service de politique de chemins rejette une modification dans infra/ même si la tâche reste ambiguë, un bac à sable refuse une requête sortante non approuvée même si un README y invite l'agent, et la barrière CI rejette un diff qui dépasse le budget de changement d'ACME-1842. Ces contrôles réduisent l'autorité disponible ; ils ne prouvent pas qu'une plateforme est impossible à mal configurer.

Gérer un travail qui dépasse une seule session

Toutes les tâches n'ont pas la forme d'ACME-1842. ACME-1843 — appliquer une tarification toutes taxes comprises sur cinq services de paiement — est trop volumineuse pour une seule fenêtre de contexte et trop interdépendante pour un périmètre de chemins unique : traitée en une seule exécution surdimensionnée, elle fait perdre à l'agent le fil de son propre raisonnement et laisse à l'examinateur un diff inexplicable. Découpez-la plutôt en sous-tâches bornées par session, en conservant l'état hors du contexte du modèle selon le principe d'Anthropic pour les agents de longue durée : un initialisateur construit une liste de tâches, une entrée par service, et chaque session lit l'historique git et une note d'avancement avant de revendiquer une entrée et de valider un commit en sortie. Le budget de changement et le périmètre de chemins s'appliquent toujours par session — l'historique git et la note, non la mémoire du modèle, font foi lorsqu'une session en désaccord doit escalader plutôt que réécrire silencieusement le travail déjà fait.

Définir des budgets, règles d'arrêt et validations explicites

Chaque exécution consomme de la capacité de livraison. Définissez des budgets pour la latence, le coût du modèle et des outils, la taille de contexte, les tentatives et les agents simultanés : une recherche large dans le dépôt peut épuiser le contexte, un test d'intégration instable peut consommer tout le budget de latence, et des tentatives sans limite engendrent des coûts sans nouvelles preuves.

Parmi les conditions d'arrêt utiles figurent un nombre fixé de tentatives échouées, un refus de politique insoluble, une dépendance manquante ou une décision humaine requise. À l'arrêt, conservez le diff, la sortie des tests et les identifiants de trace pertinents. Le résultat correct est parfois une passation exploitable, non un correctif forcé.

Validez chaque contrat à trois niveaux avant de lui faire confiance : positif — une requête sans country renvoie 400 avec TAX_COUNTRY_REQUIRED, le test ciblé et la vérification de types passent, seuls les chemins autorisés ont été modifiés ; négatif — un panier français valide continue de renvoyer le bon montant de taxe et le vérificateur de chemins rejette une tentative de modification dans infra/ ; et défaillance — un test de référence en échec ou un hôte de paquets bloqué doit arrêter l'exécution, qualifier le blocage et demander l'escalade nommée plutôt que de contourner le contrôle en relançant la tâche.

La reprise reste délibérée : restaurer l'arbre de travail de référence, joindre la commande en échec et l'identifiant de trace à la tâche, puis laisser son responsable réparer la référence, élargir le contrat via une revue, ou scinder le travail. N'accordez jamais un jeton d'accès plus large pour transformer une exécution ambiguë en succès de façade.

Exploiter une boucle de livraison vérifiable

Pour la plupart des équipes, une boucle initiale sûre consiste à attribuer une tâche bornée dans un espace de travail isolé, exiger une validation déterministe, ouvrir une pull request vérifiable et recueillir des preuves avant la fusion. N'élargissez l'autonomie qu'après que la même catégorie de tâche a démontré une performance d'évaluation stable et un faible risque opérationnel.

Versionnez le modèle de tâche, la politique, les outils, l'image d'exécution et la suite d'évaluation. Mesurez le système de livraison plutôt que l'activité brute des agents : taux d'achèvement et de régression par catégorie, reprises demandées par les examinateurs, instabilité des tests, délai jusqu'à un correctif validé et coût par changement accepté. Segmentez par dépôt, version du harnais et modèle ; un score agrégé peut masquer une régression dangereuse dans un service critique comme le paiement.

La suite d'évaluation mérite la même rigueur que le harnais qu'elle note. Commencez petit : vingt à cinquante tâches tirées d'incidents réels d'Acme Shop surpassent un grand ensemble synthétique, car chacune dispose déjà d'un résultat connu et correct. Notez ce que l'exécution a réellement produit, pas les commandes exactes utilisées pour y arriver — un agent trouve régulièrement une voie valide que l'auteur de l'évaluation n'avait pas anticipée. Gardez aussi le correcteur sous revue : trop littéral, il recale un résultat correct pour un écart de mise en forme ; trop permissif, un juge fondé sur un LLM valide au contraire un résultat faux.

La plupart des blocages relèvent de quelques causes récurrentes, à reconnaître tôt plutôt qu'à diagnostiquer après coup : un test de référence déjà en échec trahit une régression préexistante, pas le correctif de l'agent ; un diff qui touche à infra/ ou dépasse le budget de changement doit être rejeté et scindé en tâche séparée ; un test qui passe en local mais échoue en CI signale un écart d'environnement, à reproduire dans l'image déclarée avant de toucher aux instructions ; et une session qui contredit le travail précédent trahit une note d'avancement obsolète, à réconcilier avec l'historique git avant de reprendre.

Liste de contrôle de mise en œuvre

• Publiez des instructions de dépôt concises, y compris via des fichiers AGENTS.md locaux, et gardez les commandes de validation exécutables.
• Créez des contrats de tâche avec périmètre autorisé, preuves, éléments hors périmètre, budget de changement et règles d'escalade.
• Isolez les espaces de travail et imposez les permissions de fichiers, réseau, identifiants et fusion hors des prompts, via une couche de politique et la CI.
• Validez chaque contrat à trois niveaux — cas positif, cas négatif et simulation de défaillance — avant de lui faire confiance en production.
• Bornez latence, coût, contexte, tentatives et concurrence ; conservez les preuves lorsqu'une exécution s'arrête.
• Découpez tout travail qui dépasse une session en sous-tâches suivies par une note d'avancement et l'historique git, jamais par la seule mémoire du modèle.
• Examinez les changements de l'environnement, la suite d'évaluation et son correcteur avec autant de soin que le code qu'ils permettent.

Références faisant autorité

• OpenAI: Harness engineering: leveraging Codex in an agent-first world, February 11, 2026
• Anthropic: Effective harnesses for long-running agents
• Anthropic: Demystifying evals for AI agents
• AGENTS.md: a shared, open format for guiding coding agents
• OWASP Top 10 for LLM and GenAI
• OpenTelemetry semantic conventions for Generative AI