Guide d'ingénierie

AI Harness Engineering pour les agents de code

Concevez l'environnement d'un agent de code afin que ses modifications soient délimitées, testables, observables et sûres à examiner.

Périmètre : la livraison logicielle, pas une discipline normalisée

Dans ce guide, AI Harness Engineering désigne l'ingénierie pratique de l'environnement autour des agents de code : instructions du dépôt, outils, limites d'exécution, contrats de tâche, 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. Les LLMOps de production portent sur l'exploitation d'applications reposant sur des modèles en production ; un environnement pour agent de code vise à fiabiliser le travail de livraison logicielle avant qu'un changement soit fusionné ou déployé.

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, non testable dans un autre si le contexte disponible, les permissions, la validation 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, d'un travail incrémental et d'artefacts explicites de passation.

Traitez l'environnement comme une infrastructure de livraison de code

L'environnement détermine ce qu'un agent peut voir, modifier, exécuter et considérer comme réussi. Versionnez-le, examinez-le et mesurez ses effets comme tout autre contrôle de livraison.

Définir un contrat 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, les vérifications requises et la voie d'escalade en cas d'ambiguïté. Liez l'issue, la décision de conception ou les éléments de l'incident plutôt que de coller un historique sans limite dans son contexte.

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. Rendez les décisions d'architecture, les limites de dépendances, la responsabilité des services 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 du dépôt, 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, sont gérés par un fournisseur ou sont interdits ?
Quels comportements visibles par l'utilisateur et quelles contraintes de compatibilité comptent ?
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 et des changements incrémentaux pour préserver l'état entre les sessions. Adoptez cette idée de manière sélective : utilisez les liens vers les issues, l'historique des commits, les rapports de test et de 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.

Construire des boucles de retour déterministes

Les agents progressent lorsque l'environnement renvoie des éléments de preuve spécifiques et répétables. Préférez une courte séquence de vérifications rapides et déterministes : formatage, vérification des types, tests unitaires ciblés, analyse statique, validation de build et test d'intégration ou de navigateur ciblé lorsque la tâche l'exige. Renvoyez des échecs concis avec chemins, commandes et identifiants d'erreur stables.

Évitez une boucle qui demande seulement au modèle de « relire son travail ». Cela peut servir de vérification supplémentaire, mais ne remplace pas un vérificateur. Pour les tâches de code, rendez les critères d'acceptation exécutables lorsque possible :

Reproduire la défaillance déclarée ou démontrer le comportement manquant.
Effectuer le plus petit changement qui satisfait le contrat.
Exécuter les vérifications requises dans un environnement propre et déclaré.
Comparer le diff aux chemins autorisés et aux changements interdits.
Consigner les commandes, les résultats et le risque non résolu pour un examinateur.

Lorsqu'une vérification est lente, fournissez un sous-ensemble rapide et déterministe pour l'itération et réservez la suite complète pour la barrière. Des échantillons aléatoires peuvent être utiles pour la couverture, mais initialisez-les avec une graine et consignez-la afin qu'une régression puisse être reproduite.

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. Par exemple, un outil d'inspection de déploiement peut renvoyer l'état d'une release sans accepter de shell arbitraire ; un outil d'écriture dans le dépôt peut rejeter 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. L'agent qui peut modifier un dépôt applicatif n'a pas besoin d'accéder aux identifiants cloud. Les guides d'OWASP sur les LLM et l'IA générative s'appliquent ici : l'injection de prompt, la divulgation d'informations sensibles, les risques de chaîne d'approvisionnement, la gestion incorrecte des sorties et l'autonomie excessive deviennent des risques concrets de livraison lorsque du contenu de dépôt non fiable peut influencer un agent privilégié.

Utilisez une couche de politique hors des instructions du modèle pour les contrôles qui doivent impérativement tenir. 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.

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

Chaque exécution consomme de la capacité de livraison. Définissez des budgets pour la latence de bout en bout, le coût du modèle et des outils, la taille de contexte, les tentatives, la durée des commandes et les agents simultanés. Les budgets rendent les modes de défaillance visibles : 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 peuvent engendrer des coûts sans nouvelles preuves.

Parmi les conditions d'arrêt utiles figurent un nombre fixé de tentatives de validation échouées, un refus de politique insoluble, une dépendance manquante, une référence modifiée ou une décision humaine requise. À l'arrêt, conservez le diff, la sortie des tests, les identifiants de trace pertinents et une brève explication de ce qui a bloqué l'avancement. Le résultat correct est parfois une passation exploitable, non un correctif forcé.

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.

Mesurez le système de livraison plutôt que de célébrer l'activité brute des agents. Suivez les taux d'achèvement des tâches et de régression par catégorie, les reprises demandées par les examinateurs, l'instabilité des tests, le délai jusqu'à un correctif validé, les conflits de fusion, les refus de politique, le coût par changement accepté et la proportion d'exécutions qui se terminent par une escalade utile. Segmentez ces métriques par dépôt, version de l'environnement, modèle, ensemble d'outils et suite d'évaluation ; un score agrégé peut masquer une régression dangereuse dans un service critique.

Liste de contrôle de mise en œuvre

Publiez des instructions de dépôt concises 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 et règles d'escalade.
Isolez les espaces de travail et donnez à chaque exécution une branche, une trace et un emplacement d'artefacts uniques.
Imposez les permissions de système de fichiers, réseau, identifiants et fusion hors des prompts.
Exécutez des vérifications rapides et déterministes durant l'itération, puis les vérifications qui font autorité avant l'acceptation.
Bornez latence, coût, contexte, tentatives et concurrence ; conservez les preuves lorsqu'une exécution s'arrête.
Examinez les changements de l'environnement avec autant de soin que les changements de code qu'ils permettent.

Références faisant autorité

Construisez une boucle de livraison d'ingénierie mesurable

Échangez avec Optimi sur l'observabilité du parcours de livraison, l'accès edge sécurisé et les fondations de performance autour des workflows d'ingénierie critiques.

Discuter de l'architecture de performance