Harness engineering : utiliser Codex dans un monde agent-first

• Cas d’expérimentation d’une équipe interne d’OpenAI ayant construit et lancé la bêta interne d’un produit logiciel sans écrire manuellement de code pendant 5 mois, tout le code étant généré par l’agent Codex
• Partie avec 3 ingénieurs, l’équipe a traité environ 1 million de lignes de code et 1 500 pull requests, soit en moyenne 3,5 PR fusionnées par ingénieur et par jour
• Le rôle des ingénieurs est passé du codage direct à la conception de l’environnement, l’explicitation de l’intention et la mise en place de boucles de feedback, la clé étant de construire le scaffolding permettant aux agents de travailler de façon fiable
• Utilisation de AGENTS.md non comme une encyclopédie mais comme une table des matières, avec application mécanique de la cohérence architecturale via une documentation structurée, des linters et des tests structurels
• Plus l’autonomie des agents augmente, plus la gestion de l’entropie et un rangement continu de type garbage collection deviennent indispensables, la discipline de construction logicielle se déplaçant du code vers le scaffolding

---

Une expérimentation démarrée depuis un dépôt git vide

• Fin août 2025, le premier commit a été effectué dans un dépôt vide ; le scaffold initial (structure du dépôt, configuration CI, règles de formatage, configuration du gestionnaire de paquets, framework applicatif) a été généré dans Codex CLI à partir de templates existants avec GPT-5
• Le fichier initial AGENTS.md, qui explique à l’agent comment travailler dans le dépôt, a lui aussi été rédigé directement par Codex
• Dès le départ, sans base de code préexistante écrite par des humains, le dépôt a été façonné par les agents
• Cinq mois plus tard, il contenait environ 1 million de lignes de code couvrant la logique applicative, l’infrastructure, le tooling, la documentation et les utilitaires internes pour développeurs
• Une petite équipe de 3 personnes a ouvert et fusionné environ 1 500 pull requests, soit un débit moyen de 3,5 PR par ingénieur et par jour
• Le débit a même augmenté lorsque l’équipe est passée à 7 personnes
• Le produit a été utilisé chaque jour en interne par plusieurs centaines d’utilisateurs, y compris des power users internes
• À aucun moment du processus de développement, les humains n’ont directement contribué au code
• « Il n’y a pas de code écrit manuellement » est devenu la philosophie centrale de l’équipe

Redéfinir le rôle de l’ingénieur

• Puisque les humains ne codent pas directement, il faut une autre forme d’ingénierie centrée sur les systèmes, le scaffolding et l’effet de levier
• Si les débuts ont été plus lents qu’attendu, ce n’était pas à cause des limites de Codex mais d’un environnement insuffisant
  • L’agent manquait d’outils, d’abstractions et de structure interne pour atteindre des objectifs de haut niveau
• Le travail principal de l’équipe d’ingénierie s’est déplacé vers le fait d’aider les agents à accomplir des tâches utiles
• Les grands objectifs sont découpés en blocs plus petits (conception, code, revue, tests, etc.), puis l’agent assemble ces blocs avant d’attaquer des tâches plus complexes, selon une approche de travail en profondeur
• En cas d’échec, la question clé n’est pas « faire plus d’efforts », mais « quelle capacité manque, et comment la rendre lisible et exécutable pour l’agent ? »
• Les humains interagissent presque exclusivement avec le système via des prompts
  • pour décrire une tâche, lancer un agent, ouvrir une pull request, etc.
• Pour finaliser une PR, ils demandent à Codex de relire ses modifications en local, de solliciter d’autres revues d’agents en local et dans le cloud, de répondre aux retours et de répéter jusqu’à satisfaction de tous les relecteurs agents
  • en pratique, une boucle de type Ralph Wiggum Loop
• Codex utilise directement les outils de développement standard comme gh, des scripts locaux et des skills intégrés au dépôt pour collecter le contexte
• La revue humaine des pull requests reste possible, mais n’est pas obligatoire ; avec le temps, presque toute la revue est passée à un traitement entre agents

Améliorer la lisibilité de l’application

• À mesure que le débit de code augmentait, la capacité de QA humaine est devenue le goulot d’étranglement
• Le temps et l’attention des humains étant des ressources fixes, l’équipe a ajouté des capacités aux agents pour que Codex puisse lire et comprendre directement l’interface, les logs et les métriques applicatives
• Grâce à une fonction de démarrage de l’application par git worktree, Codex peut lancer et contrôler une instance distincte pour chaque changement
• Le Chrome DevTools Protocol a été connecté au runtime de l’agent, avec des skills créés pour les snapshots DOM, les captures d’écran et les opérations de navigation
  • Codex peut ainsi reproduire des bugs, vérifier des correctifs et raisonner directement sur le comportement de l’UI
• Le même principe a été appliqué à l’outillage d’observabilité
  • logs, métriques et traces sont exposés à Codex via une stack locale d’observabilité temporaire pour chaque worktree
  • les logs et métriques sont supprimés une fois la tâche terminée
  • l’agent peut interroger les logs avec LogQL et les métriques avec PromQL
• Une fois ce contexte disponible, il devient facile de formuler des prompts comme « faire en sorte que le démarrage du service se termine en moins de 800 ms » ou « qu’aucun span ne dépasse 2 secondes dans quatre parcours utilisateur clés »
• Une seule exécution de Codex peut travailler sur une même tâche pendant plus de 6 heures (souvent pendant que les humains dorment)

Utiliser la connaissance du dépôt comme système d’enregistrement

• La gestion du contexte est l’un des plus grands défis pour permettre aux agents de traiter efficacement des tâches grandes et complexes
• Première leçon : il faut donner à Codex une carte, pas un manuel de 1 000 pages
• Après avoir essayé l’approche du gros AGENTS.md unique, l’échec a été prévisible
  • Le contexte est une ressource rare : un énorme fichier d’instructions complique la tâche, le code et les documents connexes, ce qui pousse l’agent à manquer des contraintes majeures ou à optimiser pour les mauvaises
  • Trop d’instructions tuent l’instruction : si tout est « important », plus rien ne l’est, et l’agent fait du simple appariement de motifs local plutôt qu’une exploration intentionnelle
  • Cela se dégrade très vite : un manuel géant uniforme devient un cimetière de règles périmées, et l’agent ne peut plus savoir ce qui est encore valable
  • Difficile à vérifier : un blob unique se prête mal aux contrôles mécaniques (couverture, fraîcheur, responsabilité, liens croisés), rendant la dérive inévitable
• La solution a été de traiter AGENTS.md comme une table des matières, non comme une encyclopédie
• La base de connaissances du dépôt est gérée comme un système d’enregistrement dans un répertoire structuré docs/
• Un AGENTS.md court (environ 100 lignes) est injecté dans le contexte et sert surtout de carte, orientant vers des sources d’information plus profondes et plus fiables
• La documentation de conception est classée et indexée, avec des convictions fondamentales définissant l’état de validation et les principes d’exploitation agent-first
• La documentation d’architecture fournit une carte de haut niveau des domaines et du layering des packages
• La documentation qualité attribue une note à chaque domaine produit et à chaque couche architecturale, et suit les écarts dans le temps
• Les plans sont traités comme des artefacts de premier ordre
  • les plans temporaires et simples servent aux petits changements
  • les tâches complexes sont intégrées à des plans d’exécution stockés dans le dépôt avec leur progression et un journal de décisions
  • les plans en cours, les plans terminés et la dette technique connue sont tous versionnés au même endroit
• Cela permet une divulgation progressive : l’agent peut démarrer à partir de petits points d’entrée stables sans être surchargé, puis avancer par étapes
• Application mécanique : des linters dédiés et des jobs CI vérifient que la base de connaissances est à jour, correctement croisée et bien structurée
• Un agent récurrent de « doc-gardening » relit les documents anciens ou invalides et ouvre des pull requests de correction

La lisibilité pour l’agent comme objectif

• Puisque le dépôt a été entièrement généré par des agents, il est d’abord optimisé pour la lisibilité par Codex
• L’objectif des ingénieurs humains est de permettre à l’agent de raisonner sur l’ensemble du domaine métier directement à partir du dépôt lui-même
• Du point de vue de l’agent, ce qui n’est pas accessible dans le contexte d’exécution n’existe pratiquement pas
  • les Google Docs, les fils de discussion et les connaissances dans la tête des gens sont inaccessibles au système
  • seuls les artefacts versionnés du dépôt (code, Markdown, schémas, plans d’exécution) sont accessibles
• Même un pattern d’architecture validé dans Slack est illisible pour l’agent s’il ne peut pas le retrouver
• Donner plus de contexte à Codex ne consiste pas à le surcharger d’instructions ad hoc, mais à organiser et exposer la bonne information pour qu’il puisse raisonner
• On obtient de meilleurs résultats en donnant à l’agent les informations comme on intégrerait un nouveau membre d’équipe aux principes produit, aux normes d’ingénierie et à la culture de l’équipe, y compris les préférences d’emoji
• Les dépendances et abstractions que l’agent peut entièrement internaliser et sur lesquelles il peut raisonner dans le dépôt sont privilégiées
• Les technologies « ennuyeuses » sont souvent plus faciles à modéliser pour l’agent grâce à leur composabilité, la stabilité de leur API et leur représentation dans les données d’entraînement
• Dans certains cas, il est moins coûteux pour l’agent de réimplémenter directement un sous-ensemble de fonctionnalité plutôt que de dépendre d’un comportement amont opaque d’une bibliothèque publique
  • exemple : implémenter son propre helper map-with-concurrency au lieu d’un package générique de style p-limit, avec intégration étroite à l’instrumentation OpenTelemetry, 100 % de couverture de tests, et un comportement d’exécution exactement conforme aux attentes
• Plus on rend le système inspectable, vérifiable et modifiable directement par l’agent, plus on augmente l’effet de levier non seulement pour Codex mais aussi pour d’autres agents comme Aardvark

Faire respecter l’architecture et les préférences

• La documentation seule ne suffit pas à maintenir une cohérence totale dans une codebase générée par agents
• Il faut faire respecter les invariants sans microgérer l’implémentation, afin de garder des fondations solides tout en permettant aux agents de livrer vite
  • exemple : l’équipe voulait que Codex parse les formes de données aux frontières, sans imposer précisément la manière de le faire ni la bibliothèque spécifique (le modèle a tendance à préférer Zod)
• Les agents sont plus efficaces dans un environnement doté de frontières strictes et d’une structure prévisible
• L’application a été construite autour d’un modèle architectural strict
  • chaque domaine métier est séparé en un ensemble fixe de couches, avec directions de dépendances strictement validées et un ensemble limité d’arêtes autorisées
  • le code circule dans l’ordre Types → Config → Repo → Service → Runtime → UI
  • les préoccupations transverses (authentification, connecteurs, télémétrie, feature flags) entrent via une interface explicite unique appelée Providers
  • tout le reste est interdit et appliqué mécaniquement
• Ces contraintes sont imposées via des linters sur mesure et des tests structurels générés par Codex
• Ce niveau d’architecture, souvent repoussé jusqu’à des équipes de centaines d’ingénieurs, est pour les agents de code une condition préalable dès le départ
• Des règles de lint sur mesure imposent statiquement le logging structuré, les conventions de nommage des schémas et des types, les limites de taille de fichiers et les exigences de stabilité propres aux plateformes
  • comme le lint est personnalisé, ses messages d’erreur peuvent être rédigés pour injecter des instructions de correction dans le contexte de l’agent
• Dans un workflow centré humain, ces règles peuvent sembler trop fines ou trop contraignantes, mais avec des agents leur effet est démultiplié
• Les contraintes distinguent clairement ce qui compte vraiment et ce qui ne compte pas
  • à l’image d’une grande organisation d’ingénierie de plateforme : définir les frontières au centre, laisser l’autonomie en local
• Le code produit ne correspond pas toujours aux préférences stylistiques humaines, mais si le résultat est correct, maintenable et lisible pendant l’exécution des agents, le critère est rempli
• Les préférences humaines sont continuellement réinjectées dans le système
  • les commentaires de revue, PR de refactoring et bugs côté utilisateur sont enregistrés via des mises à jour de documentation ou directement codés dans les outils
  • quand la documentation ne suffit pas, il faut élever la règle au rang de code

Une philosophie du merge qui change

• Avec l’augmentation du débit de Codex, les normes d’ingénierie classiques deviennent parfois contre-productives
• Le dépôt fonctionne avec des gates de merge minimales et peu bloquantes
• Les pull requests ont une durée de vie courte, et l’instabilité des tests est traitée dans des exécutions ultérieures plutôt que de bloquer indéfiniment l’avancement
• Dans un système où le débit des agents dépasse largement l’attention humaine, le coût de la correction est faible et le coût de l’attente est élevé
• Cette approche ne conviendrait pas forcément à des environnements à faible débit, où un autre compromis peut être nécessaire

Ce que couvre réellement « généré par agent »

• Dire que la codebase est générée par des agents Codex signifie tout ce qu’elle contient
  • le code produit et les tests
  • la configuration CI et le tooling de release
  • les outils internes pour développeurs
  • la documentation et l’historique de conception
  • les harnesses d’évaluation
  • les commentaires de revue et leurs réponses
  • les scripts qui gèrent le dépôt lui-même
  • les fichiers de définition des dashboards de production
• Les humains restent toujours dans la boucle, mais à une couche d’abstraction différente de celle d’avant
  • priorisation du travail, transformation des retours utilisateurs en critères d’acceptation, validation des résultats
• Quand les agents peinent, cela est pris comme un signal pour identifier ce qui manque dans les outils, garde-fous ou documents, puis les correctifs sont toujours écrits par Codex lui-même avant d’être réinjectés dans le dépôt
• Les agents vont jusqu’à récupérer les retours de revue, répondre en ligne, pousser les mises à jour, puis squash et merge leurs propres pull requests

Montée en autonomie

• À mesure que davantage de boucles de développement — tests, validation, revue, traitement du feedback, récupération — sont encodées directement dans le système, un seuil critique est atteint
• Ce qu’un agent peut faire avec un seul prompt :
  • vérifier l’état actuel de la codebase
  • reproduire un bug signalé
  • enregistrer une vidéo montrant la situation d’échec
  • implémenter le correctif
  • exécuter l’application pour valider la correction
  • enregistrer une seconde vidéo montrant la solution
  • ouvrir une pull request
  • répondre aux retours d’agents et d’humains
  • détecter et corriger les échecs de build
  • faire remonter à un humain uniquement lorsqu’un jugement est nécessaire
  • fusionner le changement
• Ces comportements dépendent fortement de la structure et du tooling propres à ce dépôt, et il ne faut pas supposer qu’ils se généralisent sans investissements comparables

Entropie et garbage collection

• L’autonomie complète des agents crée de nouveaux problèmes : Codex reproduit les patterns déjà présents dans le dépôt, y compris ceux qui sont hétérogènes ou sous-optimaux, d’où une dérive inévitable au fil du temps
• Au début, les humains géraient cela manuellement, en consacrant chaque vendredi (20 % de la semaine) au nettoyage de la « pente IA »
  • comme prévu, cela n’était pas scalable
• L’alternative a consisté à encoder directement dans le dépôt des « règles d’or » et à mettre en place des processus de nettoyage réguliers
  • (1) préférer des packages utilitaires partagés aux helpers maison afin de centraliser la gestion des invariants
  • (2) ne pas explorer les données en mode « YOLO-style », mais valider les frontières ou s’appuyer sur des SDK typés pour éviter que l’agent construise par erreur à partir de formes supposées
• Des jobs en arrière-plan Codex vérifient régulièrement les écarts, mettent à jour les notes qualité et génèrent des PR de refactoring ciblées
  • la plupart peuvent être relues en moins d’une minute puis fusionnées automatiquement
• Cela fonctionne comme une garbage collection : la dette technique ressemble à un prêt à taux élevé, mieux vaut la rembourser petit à petit avant que les intérêts ne s’accumulent
• Une fois les préférences humaines capturées, elles s’appliquent continuellement à chaque ligne de code ; les mauvais patterns sont détectés et corrigés chaque jour avant de se propager pendant des jours ou des semaines

Apprentissages en cours et défis à venir

• Cette stratégie a bien fonctionné chez OpenAI jusqu’aux étapes de lancement interne et d’adoption
• Construire de vrais produits pour de vrais utilisateurs ancre ces investissements dans le réel et aide à garantir la maintenabilité à long terme
• Ce qui reste inconnu : comment la cohérence architecturale évoluera sur plusieurs années dans un système entièrement généré par agents
• L’équipe continue d’apprendre où le jugement humain a le plus d’impact et comment l’encoder pour en tirer un effet composé
• À mesure que les capacités des modèles progressent, la trajectoire d’évolution de ce système reste elle aussi incertaine
• La construction logicielle exige toujours de la discipline, mais celle-ci s’exprime de plus en plus dans le scaffolding plutôt que dans le code
• Le tooling, les abstractions et les boucles de feedback qui maintiennent la cohérence d’une codebase deviennent de plus en plus importants
• Le défi le plus difficile aujourd’hui : concevoir l’environnement, les boucles de feedback et les systèmes de contrôle qui aident les agents à construire et maintenir à grande échelle des logiciels complexes et fiables