Ingénierie harnais : exploiter Codex dans un monde axé sur agents

Au cours des cinq derniers mois, notre équipe a mené une expérience : concevoir et livrer une version bêta interne d’un produit logiciel avec 0 lignes de code écrites manuellement.

Le produit a des utilisateurs quotidiens internes et des testeurs alpha externes. Il est expédié, déployé, cassé et réparé. Ce qui est différent, c’est que chaque ligne de code — logique d’application, tests, configuration de CI, documentation, observabilité et outils internes — a été écrite par Codex. Nous estimons avoir mis environ 10 fois moins de temps à développer cette solution qu'il n'en aurait fallu pour écrire le code à la main.

Les humains orientent. Les agents exécutent.

Nous avons délibérément choisi cette contrainte afin de ne construire que ce qui était nécessaire pour accroître la rapidité de l'ingénierie de plusieurs ordres de grandeur. Nous avons eu des semaines pour expédier ce qui s'est avéré être un million de lignes de code. Pour y parvenir, nous devions comprendre ce qui change lorsque le travail principal d’une équipe d’ingénierie logicielle n’est plus d’écrire du code, mais de concevoir des environnements, de spécifier l’intention et de créer des boucles de commentaires permettant aux agents Codex d’effectuer un travail fiable.

Cet article traite de ce que nous avons appris en développant un tout nouveau produit avec une équipe d’agents : ce qui a échoué, ce qui s’est amplifié, et comment maximiser notre seule ressource véritablement rare : le temps et l’attention humains.

Le premier commit dans un dépôt vide a été effectué à la fin août 2025.

L’échafaudage initial—structure du dépôt, configuration CI, règles de formatage, configuration du gestionnaire de paquets et cadre d’application—a été généré par Codex CLI à l’aide de GPT‑5, guidé par un petit ensemble de modèles existants. Même le fichier AGENTS.md initial, qui guide les agents sur la manière de travailler dans le dépôt, a été rédigé par Codex lui-même.

Il n'existait aucun code écrit par des humains pour servir de base au système. Dès le début, le dépôt a été influencé par l’agent.

Cinq mois plus tard, le dépôt contient environ un million de lignes de code réparties entre la logique applicative, l’infrastructure, les outils, la documentation et les utilitaires internes pour les développeurs. Au cours de cette période, environ 1 500 pull requests ont été ouvertes et fusionnées par une petite équipe de seulement trois ingénieurs dirigeant Codex. Cela se traduit par un débit moyen de 3,5 PRs par ingénieur par jour et, étonnamment, le débit a augmenté à mesure que l’équipe s’est agrandie pour compter maintenant sept ingénieurs. Il est important de noter qu'il ne s'agissait pas d'une production pour le simple fait de produire : le produit a été utilisé en interne par des centaines d'utilisateurs, y compris des utilisateurs avancés qui l'utilisent quotidiennement.

Tout au long du processus de développement, les humains n’ont jamais directement écrit de code. C’est devenu une philosophie centrale pour l’équipe : aucun code écrit manuellement.

L’absence de codage humain pratique a introduit un autre type de travail d’ingénierie, axé sur les systèmes, les structures de soutien et l’optimisation.

Les progrès initiaux ont été plus lents que nous l'avions prévu, non pas parce que Codex était incapable, mais parce que l’environnement était insuffisamment spécifié. L’agent ne disposait pas des outils, des abstractions et de la structure interne nécessaires pour progresser vers des objectifs de haut niveau. La principale tâche de notre équipe d’ingénierie est devenue de permettre aux agents d’accomplir un travail utile.

En pratique, cela signifiait travailler en profondeur : décomposer les objectifs plus vastes en éléments de base plus petits (conception, code, révision, test, etc.), inciter l’agent à construire ces éléments, puis les utiliser pour débloquer des tâches plus complexes. Quand quelque chose échouait, la solution n’était presque jamais « essayez plus fort ». Comme la seule façon de progresser était de faire en sorte que Codex fasse le travail, les ingénieurs humains se chargeaient toujours de la tâche et demandaient : « quelle capacité manque-t-il, et comment la rendre à la fois lisible et applicable pour l’agent? »

Les humains interagissent avec le système presque entièrement par le biais des invites : un ingénieur décrit une tâche, exécute l’agent et lui permet d’ouvrir une pull request. Pour mener une PR à terme, nous demandons à Codex de passer en revue ses propres modifications localement, de solliciter des revues supplémentaires et précises d’agents, à la fois localement et dans le nuage, de répondre à tout commentaire fourni par un humain ou un agent, puis d’itérer en boucle jusqu’à ce que tous les agents réviseurs soient satisfaits (en pratique, c’est une boucle Ralph Wiggum⁠(s'ouvre dans une nouvelle fenêtre)). Codex utilise directement nos outils de développement standard (gh, scripts locaux et compétences intégrées au dépôt) pour recueillir le contexte sans que des humains aient à copier-coller dans la CLI.

Les humains peuvent examiner les pull requests, mais ils ne sont pas obligés de le faire. Au fil du temps, nous avons dirigé presque tous les efforts de révision vers un traitement entre agents.

À mesure que le débit de code augmentait, notre goulot d’étranglement est devenu la capacité humaine d'AQ. Étant donné que la contrainte fixe a été le temps et l’attention des humains, nous avons travaillé à ajouter davantage de capacités à l’agent en rendant des éléments tels que l’interface utilisateur de l’application, les journaux et les métriques de l’application directement lisibles par Codex.

Par exemple, nous avons rendu l'application amorçable par arbre de travail git, afin que Codex puisse lancer et piloter une instance par modification. Nous avons également intégré le protocole Chrome DevTools à l’environnement d’exécution de l’agent et créé des compétences pour travailler avec des instantanés du DOM, des captures d’écran et la navigation. Cela a permis à Codex de reproduire des bogues, de valider des correctifs et de raisonner directement sur le comportement de l'interface utilisateur.

Nous avons fait de même pour les outils d’observabilité. Les journaux, les métriques et les traces sont exposés à Codex via une pile d’observabilité locale qui est éphémère pour tout arbre de travail donné. Codex fonctionne sur une version entièrement isolée de cette application, y compris ses journaux et ses mesures, qui sont supprimés une fois cette tâche terminée. Les agents peuvent interroger les journaux avec LogQL et les métriques avec PromQL. Avec ce contexte disponible, des invites telles que « assurez-vous que le démarrage du service se termine en moins de 800 ms » ou « aucun délai dans ces quatre parcours utilisateurs critiques ne dépasse deux secondes » deviennent réalisables.

Nous voyons régulièrement des exécutions uniques de Codex travailler sur une seule tâche pendant plus de six heures (souvent pendant que les humains dorment).

La gestion du contexte est l’un des plus grands défis pour rendre les agents efficaces dans l’exécution de tâches vastes et complexes. L’une des premières leçons que nous avons apprises était simple : donner à Codex une carte, pas un manuel d’instructions de 1 000 pages.

On a essayé le « un gros AGENTS.md⁠(s'ouvre dans une nouvelle fenêtre)» comme approche. Cela a échoué de façon prévisible :

• Le contexte est une ressource précieuse. Un fichier d’instructions gigantesque évince la tâche, le code et la documentation pertinente, de sorte que l’agent passe à côté de contraintes clés ou commence à optimiser pour les mauvaises.
• Trop de directives devient contre-productif. Quand tout est « important », rien ne l'est. Les agents finissent par faire de la reconnaissance de motifs localement au lieu de naviguer intentionnellement.
• Il pourrit instantanément. Un manuel monolithique devient un cimetière de règles obsolètes. Les agents ne peuvent pas déterminer ce qui est encore vrai, les humains cessent de le maintenir, et le fichier devient discrètement une nuisance attrayante.
• C’est difficile de vérifier. Un seul blob ne se prête pas aux vérifications mécaniques (couverture, fraîcheur, propriété, liens croisés), donc la dérive est inévitable.

Donc, au lieu de traiter AGENTS.md comme une encyclopédie, nous le considérons comme la table des matières.

La base de connaissances du dépôt réside dans un répertoire structuré docs/, considéré comme le système de référence. Un court AGENTS.md (environ 100 lignes) est injecté dans le contexte et sert principalement de guide, avec des références vers des sources d'information plus détaillées ailleurs.

La documentation de conception est cataloguée et indexée, y compris l’état de vérification et un ensemble de croyances fondamentales qui définissent les principes d’exploitation axés sur l’agent. La documentation d’architecture⁠(s'ouvre dans une nouvelle fenêtre) fournit une vue d'ensemble des domaines et de la hiérarchisation des paquets. Un document de qualité évalue chaque domaine de produit et chaque couche architecturale, en suivant les écarts au fil du temps.

Les plans sont traités comme des livrables de première classe. Les plans éphémères légers sont utilisés pour de petits changements, tandis que le travail complexe est consigné dans des plans d’exécution⁠(s'ouvre dans une nouvelle fenêtre) avec des journaux de progression et de décisions qui sont archivés dans le dépôt. Les plans actifs, les plans complétés et la dette technique connue sont tous versionnés et co-localisés, permettant aux agents de fonctionner sans dépendre d’un contexte externe.

Cela permet la divulgation progressive : les agents commencent avec un petit point d’entrée stable et apprennent où regarder ensuite, plutôt que d’être submergés dès le départ.

Nous appliquons cela de manière mécanique. Des linters dédiés et des tâches CI valident que la base de connaissances est à jour, bien interconnectée et correctement structurée. Un agent récurrent de « doc-gardening » analyse la documentation périmée ou obsolète qui ne reflète pas le comportement réel du code et ouvre des pull requests de correction.

À mesure que le codebase évoluait, le cadre de Codex pour les décisions de conception devait également évoluer.

Étant donné que le dépôt est entièrement généré par des agents, il est d'abord optimisé pour la lisibilité de Codex. De la même manière que les équipes visent à améliorer la navigabilité de leur code pour les nouvelles recrues en ingénierie, l’objectif de nos ingénieurs humains était de permettre à un agent de raisonner sur l’ensemble du domaine d’affaires directement à partir du dépôt lui-même.

Du point de vue de l’agent, tout ce à quoi il ne peut pas accéder dans le contexte pendant son exécution n’existe pas. Les connaissances présentes dans Google Docs, les fils de discussion ou dans la tête des gens ne sont pas accessibles au système. Les artefacts versionnés locaux au dépôt (p. ex., code, markdown, schémas, plans exécutables) sont tout ce qu'il peut voir.

Nous avons appris qu'au fil du temps, nous devions intégrer de plus en plus de contexte dans le dépôt. Cette discussion Slack qui a permis d’aligner l’équipe sur un modèle d’architecture? Si l’agent ne peut pas le découvrir, c’est illisible, tout comme ce serait inconnu pour une nouvelle recrue qui se joindrait trois mois plus tard.

Donner plus de contexte à Codex signifie organiser et exposer les bonnes informations afin que l’agent puisse raisonner à leur sujet, plutôt que de le submerger d’instructions ponctuelles. De la même manière que vous intégreriez un nouveau coéquipier aux principes du produit, aux normes d’ingénierie et à la culture de l’équipe (préférences d’emoji incluses), fournir ces informations à l’agent permet d’obtenir un résultat mieux aligné.

Ce cadrage a clarifié de nombreux compromis. Nous avons privilégié des dépendances et des abstractions qui pouvaient être entièrement internalisées et comprises dans le dépôt. Les technologies souvent qualifiées d'« ennuyeuses » ont tendance à être plus faciles à modéliser pour les agents en raison de leur composabilité, de la stabilité des API et de leur représentation dans l'ensemble d'entraînement. Dans certains cas, il était moins coûteux pour l’agent de réimplémenter des sous-ensembles de fonctionnalités que de contourner un comportement opaque en amont provenant de bibliothèques publiques. Par exemple, plutôt que d’intégrer un paquet générique de type p-limit, nous avons implémenté notre propre assistant de mappage avec concurrence : il est étroitement intégré à notre instrumentation OpenTelemetry, bénéficie d’une couverture de tests à 100 % et se comporte exactement comme notre environnement d'exécution s’y attend.

Intégrez davantage le système dans une forme que l’agent peut inspecter, valider et modifier directement augmente l’effet de levier — non seulement pour Codex, mais aussi pour d’autres agents (p. ex. Aardvark) qui travaillent également sur le codebase.

La documentation seule ne suffit pas à assurer la cohérence d'un codebase entièrement générée par des agents. En appliquant des invariants plutôt qu’en microgérant les implémentations, nous permettons aux agents de livrer rapidement sans compromettre les fondations. Par exemple, nous demandons à Codex de analyser les structures de données à la frontière⁠(s'ouvre dans une nouvelle fenêtre), mais nous ne sommes pas prescriptifs sur la manière dont cela doit se faire (le modèle semble préférer Zod, mais nous n'avons pas spécifié cette bibliothèque en particulier).

Les agents sont plus efficaces dans des environnements avec des limites strictes et une structure prévisible⁠(s'ouvre dans une nouvelle fenêtre), c’est pourquoi nous avons conçu l’application autour d’un modèle architectural rigide. Chaque domaine d’activité est divisé en un ensemble fixe de couches, avec des directions de dépendance strictement validées et un ensemble limité de connexions autorisées. Ces contraintes sont appliquées mécaniquement par des linters personnalisés (générés par Codex, bien sûr!) et des tests structurels.

Le diagramme ci-dessous montre la règle : au sein de chaque domaine d’activité (p. ex. Paramètres de l’application), le code ne peut dépendre que « vers l’avant » à travers un ensemble fixe de couches (Types → Config → Dépôt → Service → Runtime → UI). Les préoccupations transversales (auth, connecteurs, télémétrie, indicateurs de fonctionnalités) passent par une seule interface explicite : Providers. Tout autre élément est interdit et appliqué de manière mécanique.

C’est le genre d’architecture que vous remettez habituellement à plus tard jusqu’à ce que vous ayez des centaines d’ingénieurs. Avec les agents de codage, c’est un prérequis précoce : les contraintes permettent la rapidité sans dégradation ni dérive architecturale.

En pratique, nous appliquons ces règles à l’aide de linters personnalisés et de tests structurels, ainsi qu’un petit ensemble d’invariants de goût. Par exemple, nous appliquons de manière statique la journalisation structurée, les conventions de nommage pour les schémas et les types, les limites de taille de fichier et les exigences de fiabilité spécifiques à la plateforme à l'aide de lints personnalisés. Étant donné que les lints sont personnalisés, nous rédigeons les messages d'erreur pour inclure des instructions de correction dans le contexte de l'agent.

Dans un flux de travail axé sur l’humain, ces règles peuvent sembler pédantes ou contraignantes. Avec des agents, ils deviennent des multiplicateurs : une fois encodés, ils s’appliquent partout simultanément.

Parallèlement, nous précisons clairement où les contraintes importent et où elles n'importent pas. Cela ressemble à diriger une grande organisation de plateforme d’ingénierie : imposer des limites de manière centralisée, tout en permettant l’autonomie au niveau local. Les limites, l'exactitude et la reproductibilité vous tiennent particulièrement à cœur. Dans ces limites, vous accordez aux équipes — ou aux agents — une grande liberté quant à la façon dont les solutions sont exprimées.

Le code résultant ne correspond pas toujours aux préférences stylistiques humaines, et cela ne pose pas de problème. Tant que le résultat est correct, maintenable et lisible pour les futures exécutions de l’agent, il satisfait aux critères.

Le goût humain est intégré en continu dans le système. Les commentaires de révision, les pull requests de refactorisation et les bogues visibles par les utilisateurs sont consignés sous forme de mises à jour de la documentation ou encodés directement dans les outils. Lorsque la documentation est insuffisante, nous promouvons la règle dans le code

À mesure que le débit de Codex augmentait, de nombreuses normes d’ingénierie conventionnelles devenaient contre-productives.

Le dépôt fonctionne avec des portes de fusion bloquantes minimales. Les pull requests sont de courte durée. Les instabilités de test sont souvent traitées par des exécutions de suivi plutôt que de bloquer indéfiniment les progrès. Dans un système où le débit des agents dépasse largement l’attention humaine, les corrections sont peu coûteuses et l’attente est onéreuse.

Ce serait irresponsable dans un environnement à faible débit. Ici, c’est souvent le bon compromis.

Lorsque nous disons que le codebase est généré par les agents Codex, nous entendons tout ce qui se trouve dans le codebase.

Les agents produisent :

• Code de produit et tests
• Configuration CI et outils de déploiement
• Outils internes pour développeurs
• Historique de la documentation et de la conception
• Harnais d’évaluation
• Commentaires et réponses de révision
• Scripts qui gèrent le dépôt lui-même
• Fichiers de définition du tableau de bord de production

Les humains restent toujours dans la boucle, mais travaillent à un niveau d’abstraction différent de celui auquel nous étions habitués. Nous priorisons le travail, traduisons les commentaires des utilisateurs en critères d'acceptation et validons les résultats. Lorsque l’agent rencontre des difficultés, nous le considérons comme un signal : identifier ce qui manque — outils, garde-fous, documentation — et le réintégrer dans le dépôt, en demandant toujours à Codex lui-même de rédiger la correction.

Les agents utilisent directement nos outils de développement standard. Ils récupèrent les commentaires de révision, répondent en ligne, poussent des mises à jour et fusionnent souvent leurs propres pull requests après les avoir écrasées.

À mesure qu’une plus grande partie de la boucle de développement était encodée directement dans le système—tests, validation, revue, gestion des commentaires et récupération—le dépôt a récemment franchi un seuil significatif où Codex peut piloter de bout en bout une nouvelle fonctionnalité.

Avec une seule invite, l’agent peut maintenant :

• Valider l’état actuel du codebase
• Reproduire un bogue signalé
• Enregistrer une vidéo démontrant l’échec
• Appliquer une correction
• Valider la correction en exécutant l’application
• Enregistrer une deuxième vidéo démontrant la résolution
• Ouvrir une pull request
• Répondez aux commentaires des agents et des humains
• Détecter et remédier aux échecs de compilation
• Transférer à un humain uniquement lorsque le jugement est requis
• Fusionner le changement

Ce comportement dépend fortement de la structure spécifique et des outils de ce dépôt et ne doit pas être présumé se généraliser sans un investissement similaire — du moins, pas encore.

L’autonomie totale des agents introduit également des problèmes nouveaux. Codex reproduit des modèles qui existent déjà dans le dépôt, même s'ils sont inégaux ou sous-optimaux. Au fil du temps, cela conduit inévitablement à une dérive.

Au début, les humains ont abordé cela manuellement. Notre équipe passait auparavant chaque vendredi (20 % de la semaine) à nettoyer les « déchets d'IA ». Sans surprise, cela n’a pas pris de l’ampleur.

Nous avons plutôt commencé à encoder ce que nous appelons des « principes d’or » directement dans le dépôt et avons mis en place un processus de nettoyage récurrent. Ces principes sont des règles mécaniques et affirmées qui maintiennent le codebase lisible et cohérent pour les futures exécutions d’agents. Par exemple : (1) nous préférons les ensembles utilitaires partagés aux assistants faits maison pour garder les invariants centralisés, et (2) nous ne sondons pas les données de manière « YOLO » — nous validons les limites ou nous nous appuyons sur des SDK typés pour que l’agent ne puisse pas, par accident, s’appuyer sur des formes devinées. À intervalles réguliers, nous exécutons un ensemble de tâches Codex en arrière-plan qui détectent les écarts, mettent à jour les notes de qualité et ouvrent des pull requests de refactorisation ciblées. La plupart de ceux-ci peuvent être examinés en moins d'une minute et fusionnés automatiquement.

Ça fonctionne comme un service de ramassage des ordures. La dette technique est comme un prêt à taux d’intérêt élevé : il est presque toujours préférable de la rembourser continuellement par petites tranches, plutôt que de la laisser s’accumuler et de s’y attaquer par à-coups douloureux. Le goût humain est saisi une fois, puis appliqué de manière continue à chaque ligne de code. Cela nous permet également de repérer et de corriger les mauvais schémas quotidiennement, plutôt que de les laisser se propager dans la base de code pendant des jours ou des semaines.

Jusqu’à présent, cette stratégie a bien fonctionné jusqu’au lancement interne et à l’adoption chez OpenAI. Créer un véritable produit pour de vrais utilisateurs nous a aidés à ancrer nos investissements dans la réalité et à nous orienter vers une maintenabilité à long terme.

Ce que nous ignorons encore, c'est comment la cohérence architecturale évolue au fil des années dans un système entièrement généré par des agents. Nous continuons d'apprendre où le jugement humain offre le plus d'avantages et comment l'encoder pour qu'il s'amplifie. Nous ne savons pas non plus comment ce système évoluera à mesure que les modèles continueront de devenir plus performants au fil du temps.

Ce qui est devenu clair, c'est que le développement de logiciels exige toujours de la rigueur, mais cette rigueur se manifeste davantage dans la structure que dans le code. Les outils, les abstractions et les boucles de commentaire qui assurent la cohérence du codebase deviennent de plus en plus importants.

Nos défis les plus difficiles portent désormais sur la conception d’environnements, de boucles de commentaire et de systèmes de contrôle qui aident les agents à atteindre notre objectif : développer et maintenir des logiciels complexes et fiables à grande échelle.

À mesure que des agents comme Codex prennent en charge de plus grandes portions du cycle de vie des logiciels, ces questions deviendront encore plus importantes. Nous espérons que le partage de quelques leçons apprises dès le début vous aidera à déterminer où investir vos efforts afin que vous puissiez simplement créer des choses.