Ce que vous allez apprendre

Ce guide couvre le Harness engineering, des principes fondamentaux à la mise en œuvre pratique. Vous comprendrez ce que c'est, pourquoi OpenAI a misé son plus grand projet interne sur ce concept, les modèles architecturaux spécifiques qui le font fonctionner, et comment appliquer ces principes à vos propres workflows d'agents AI — que vous utilisiez Codex, Claude Code, OpenCode ou tout autre système d'agent.

Harness Engineering : Le guide complet pour le développement d'agents AI en 2026

Si 2025 a été l'année où les agents AI ont prouvé qu'ils pouvaient écrire du code, 2026 est l'année où nous avons appris que l'agent n'est pas la partie difficile — c'est le harness qui l'est.

L'équipe Codex d'OpenAI a publié un article de blog majeur en février 2026 décrivant comment ils ont construit une application de production contenant environ un million de lignes de code où zéro ligne n'a été écrite par des mains humaines. Le secret n'était pas un meilleur modèle ou un prompt plus intelligent. C'était le système qu'ils ont construit autour de l'agent — le harness. Source

Ce guide décompose chaque principe, modèle et technique pratique de cette expérience et du mouvement plus large du Harness engineering qui en a émergé.

Partie 1 : Qu'est-ce que le Harness Engineering ?

La définition

Le Harness engineering est la discipline consistant à concevoir l'environnement complet — échafaudage (scaffolding), boucles de rétroaction, documentation, contraintes architecturales et artefacts lisibles par machine — qui permet aux agents de codage AI d'effectuer un travail fiable et de haute qualité à grande échelle avec une intervention humaine minimale.

Le terme « harness » (harnais) provient de l'équipement équestre : rênes, selle, mors — l'ensemble complet de l'équipement permettant de canaliser un animal puissant mais imprévisible dans la bonne direction. Un cheval non contrôlé est dangereux. Un cheval harnaché a bâti des civilisations. Il en va de même pour les agents AI. Source

Pourquoi cela émerge maintenant

Le passage du prompt engineering au Harness engineering reflète une maturation du paysage du développement AI :

Source

L'idée clé qui a conduit à cette transition : les agents sont devenus suffisamment capables pour que le goulot d'étranglement passe de la qualité du modèle à la qualité de l'environnement. Un modèle de pointe opérant dans un repository mal structuré produit de pires résultats qu'un modèle médiocre opérant dans un environnement bien harnaché.

Partie 2 : L'expérience OpenAI Codex

L'échelle

Dans une expérience interne de cinq mois, les ingénieurs d'OpenAI ont construit et livré un produit beta contenant environ un million de lignes de code. Le repository englobe la logique d'application, l'infrastructure, l'outillage, la documentation et les utilitaires internes pour les développeurs. Il n'y avait aucun code préexistant écrit par l'homme pour ancrer le système. Source

L'équipe

Le projet a débuté avec seulement trois ingénieurs pilotant Codex. Sur la période de cinq mois, environ 1 500 pull requests ont été ouvertes et fusionnées. À mesure que l'équipe passait à sept ingénieurs, le débit a augmenté — un résultat contre-intuitif qui suggère que le harness lui-même était le principal multiplicateur de productivité, et non les compétences individuelles.

OpenAI estime avoir construit le système en environ un dixième du temps qu'il aurait fallu pour écrire le code à la main. Source

Le scaffold initial

Le projet a commencé avec Codex CLI générant le scaffold initial à l'aide de GPT-5, guidé par un petit ensemble de modèles existants :

• Structure du repository et conventions de répertoires
• Configuration CI/CD
• Règles de formatage de code et de linting
• Configuration du gestionnaire de paquets
• Boilerplate du framework d'application

À partir de cette graine, tout le reste s'est développé grâce au développement piloté par les agents.

Le problème du vendredi

Au début de l'expérience, l'équipe a découvert un problème critique : elle passait chaque vendredi — 20 % de son temps d'ingénierie — à nettoyer ce qu'elle appelait la « AI slop » (bouillie d'IA). Cela incluait des modèles incohérents, de la logique dupliquée, des variables mal nommées et une dérive architecturale.

Cela n'était pas extensible. La solution a été d'encoder leurs normes dans le harness lui-même afin que les agents produisent une sortie plus propre dès le départ, et de construire des systèmes de nettoyage automatisés pour la dérive résiduelle.

Partie 3 : Les cinq principes fondamentaux

Principe 1 : Connaissance centrée sur le repository (Repository-First Knowledge)

Du point de vue de l'agent, tout ce à quoi il ne peut pas accéder en contexte pendant son exécution n'existe effectivement pas. Les connaissances qui résident dans des Google Docs, des fils de discussion, des messages Slack ou dans la tête des gens sont invisibles pour le système.

Cela signifie que toutes les connaissances doivent vivre sous forme d'artefacts versionnés et locaux au repository :

• Code — l'artefact principal
• Documentation Markdown — décisions d'architecture, conventions, guides d'intégration
• Schemas — contrats API, schémas de base de données, définitions de types
• Plans exécutables — décompositions de tâches étape par étape que l'agent peut suivre
• Configuration — règles de linter, pipelines CI, normes de formatage

L'équipe a appris qu'elle devait injecter de plus en plus de contexte dans le repo au fil du temps. Chaque fois qu'un agent commettait une erreur par manque de contexte, la solution n'était pas un meilleur prompt — c'était d'ajouter ce contexte au repository. Source

Mise en œuvre pratique :

# ARCHITECTURE.md (lives in repo root)

## Dependency Rules
- UI components may import from Service layer but never from Repo layer
- Service layer may not import from Runtime layer
- All cross-domain communication goes through typed event bus

## Naming Conventions
- React components: PascalCase, suffixed with purpose (UserListPage, UserCard)
- Services: camelCase, suffixed with Service (userService, authService)
- Types: PascalCase, prefixed with domain (UserProfile, OrderItem)

## Testing Requirements
- All Service functions require unit tests
- All API endpoints require integration tests
- Coverage threshold: 80% per package

Principe 2 : Principes d'or (Golden Principles)

Les principes d'or sont des règles mécaniques et affirmées, encodées directement dans le repository, qui maintiennent la base de code lisible et cohérente pour les futures exécutions d'agents. Ce ne sont pas des directives aspirationnelles — ce sont des contraintes appliquées.

Exemples issus de l'expérience OpenAI :

1. Préférer les paquets utilitaires partagés aux helpers faits main — centralise les invariants de sorte que lorsqu'un comportement doit changer, il change en un seul endroit.
2. Ne pas sonder les données en mode YOLO — valider les limites ou s'appuyer sur des SDK typés afin que les agents ne puissent pas accidentellement construire sur des formes de données devinées.
3. Un concept, un fichier — chaque fichier doit représenter un concept unique, ce qui facilite la recherche et la modification du bon emplacement pour les agents.
4. Explicite plutôt qu'implicite — éviter les comportements magiques qu'un agent aurait besoin de connaissances tribales pour comprendre.

Source

Ces principes ne sont pas seulement de la documentation. Ils sont appliqués par :

• Règles de linter — des linters personnalisés (eux-mêmes générés par Codex) qui signalent les violations.
• Tests structurels — des tests qui valident la conformité architecturale.
• CI gates — les pull requests qui violent les principes d'or sont automatiquement rejetées.

Principe 3 : Architecture en couches avec application mécanique

Chaque domaine métier du projet OpenAI est divisé en un ensemble fixe de couches avec des directions de dépendance strictement validées :

Types → Config → Repo → Service → Runtime → UI

Les dépendances circulent dans une seule direction. Un composant UI peut dépendre de Runtime et Service, mais un Service ne peut jamais importer depuis UI. Un Repo peut dépendre de Config et Types, mais jamais de Service. Source

Ces contraintes sont appliquées mécaniquement :

// structural-test.ts — enforces dependency boundaries
import { analyzeImports } from './tools/import-analyzer';

describe('Dependency Layer Enforcement', () => {
  it('Service layer must not import from Runtime', () => {
    const violations = analyzeImports({
      sourceLayer: 'service',
      forbiddenLayers: ['runtime', 'ui'],
    });
    expect(violations).toEqual([]);
  });

  it('Repo layer must not import from Service', () => {
    const violations = analyzeImports({
      sourceLayer: 'repo',
      forbiddenLayers: ['service', 'runtime', 'ui'],
    });
    expect(violations).toEqual([]);
  });
});

Les tests structurels valident la conformité et empêchent les violations du multicouche modulaire. Ce n'est pas une suggestion — c'est imposé par la CI. Chaque pull request, qu'elle soit créée par un humain ou un agent, doit passer ces tests.

Principe 4 : Garbage Collection automatisée

Même avec des principes d'or et une application structurelle, le code généré par les agents dérive avec le temps. L'équipe d'OpenAI a résolu ce problème en mettant en œuvre une garbage collection automatisée — des tâches de fond récurrentes qui :

1. Scannent les écarts par rapport aux principes d'or dans l'ensemble de la base de code.
2. Mettent à jour les notes de qualité pour chaque module en fonction des scores de conformité.
3. Ouvrent des pull requests de refactoring ciblées qui corrigent des catégories spécifiques de dérive.

Cela a remplacé le « nettoyage manuel du vendredi » par un système qui fonctionne en continu. Le garbage collector lui-même est alimenté par des agents Codex, créant une boucle d'auto-maintenance. Source

# .github/workflows/garbage-collection.yml
name: Codebase Garbage Collection
on:
  schedule:
    - cron: '0 2 * * *'  # Run nightly at 2 AM

jobs:
  gc-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run golden principle scanner
        run: npx codex-gc scan --principles ./GOLDEN_PRINCIPLES.md
      - name: Generate refactoring PRs
        run: npx codex-gc fix --auto-pr --max-prs 5

Principe 5 : Plans exécutables

Avant que les agents n'écrivent du code, ils écrivent des plans. Ces plans ne sont pas des notes informelles — ce sont des documents structurés et exécutables qui spécifient :

• Objectif : Ce que la tâche accomplit.
• Fichiers à modifier : Liste explicite des fichiers auxquels l'agent touchera.
• Dépendances : Autres tâches ou modules dont ce travail dépend.
• Critères d'acceptation : Comment vérifier que le travail est terminé.
• Contraintes : Règles architecturales qui ne doivent pas être violées.

# Plan: Add user notification preferences

## Objective
Allow users to configure which notification channels (email, SMS, push) they
receive alerts on, with per-category granularity.

## Files to Modify
- src/types/user.ts — Add NotificationPreferences type
- src/repo/userRepo.ts — Add getPreferences/setPreferences methods
- src/service/notificationService.ts — Filter notifications by preferences
- src/ui/pages/SettingsPage.tsx — Add preferences UI section

## Constraints
- Must follow Types → Repo → Service → UI dependency flow
- NotificationPreferences type must be shared, not duplicated
- All new methods require unit tests

## Acceptance Criteria
- [ ] User can toggle email/SMS/push per notification category
- [ ] Preferences persist across sessions
- [ ] Toggling a channel off stops notifications on that channel within 30s

Les plans vivent dans le repository sous forme de fichiers markdown, sont contrôlés par version et peuvent être révisés avant exécution — offrant aux humains un point de contrôle entre l'intention et la mise en œuvre.

Partie 4 : La boucle de l'agent Codex

Comprendre comment la boucle de l'agent Codex opère au sein d'un harness est essentiel pour un Harness engineering efficace.

L'architecture de la boucle

OpenAI a publié une décomposition détaillée de la boucle de l'agent Codex dans son article complémentaire « Unrolling the Codex agent loop ». Source La boucle suit ce cycle :

Lire le contexte → Planifier → Exécuter → Valider → Committer (ou Réessayer)

Chaque itération :

1. Lire le contexte : L'agent lit les fichiers pertinents, la documentation, les schémas et le plan de tâche à partir du repository.
2. Planifier : Sur la base du contexte, l'agent détermine les modifications à apporter.
3. Exécuter : L'agent écrit ou modifie le code.
4. Valider : Le harness exécute des tests, des linters et des vérifications structurelles sur les modifications.
5. Committer ou Réessayer : Si la validation passe, l'agent commit. Si elle échoue, l'agent lit la sortie d'erreur et réessaye.

Le rôle du harness est de rendre les étapes 1 et 4 aussi riches en informations que possible. Plus l'agent lit de contexte, meilleur est son plan. Plus le retour de validation est spécifique, plus vite il converge vers une solution fonctionnelle.

Le App Server Harness

Dans leur article « Unlocking the Codex harness: how we built the App Server », OpenAI décrit l'infrastructure concrète qui alimente la boucle de l'agent. Source Le App Server fournit :

• Environnements d'exécution isolés (sandboxed) pour chaque tâche d'agent.
• Accès aux outils pré-configurés (système de fichiers, terminal, navigateur).
• Injection automatique de contexte à partir des artefacts du repository.
• Retour de validation en streaming afin que les agents puissent voir les échecs de tests en temps réel.

Partie 5 : Appliquer le Harness Engineering à votre équipe

Pour commencer : Le Harness Minimum Viable

Vous n'avez pas besoin de reproduire toute l'infrastructure d'OpenAI pour bénéficier du Harness engineering. Commencez par ces éléments fondamentaux :

Étape 1 : Créer un ARCHITECTURE.md

Documentez les règles architecturales de votre projet dans un format lisible par machine à la racine de votre repository. Incluez :

• Les limites des modules et les dépendances autorisées.
• Les conventions de nommage.
• Les règles d'organisation des fichiers.
• Les exigences de tests.

Ce simple fichier améliore considérablement la qualité de sortie de l'agent car les agents le lisent avant d'apporter des modifications.

Étape 2 : Ajouter des tests structurels

Écrivez des tests qui valident vos règles architecturales. Ces tests ne vérifient pas la logique métier — ils vérifient que le code est organisé correctement :

// No service file should import from a UI module
test('service layer isolation', () => {
  const serviceFiles = glob('src/services/**/*.ts');
  for (const file of serviceFiles) {
    const imports = extractImports(file);
    const uiImports = imports.filter(i => i.startsWith('../ui/'));
    expect(uiImports).toHaveLength(0);
  }
});

Étape 3 : Configurer la validation CI

Assurez-vous que votre pipeline CI exécute des tests structurels, des linters et des vérifications de types sur chaque pull request — y compris celles créées par des agents. L'agent doit voir le même résultat de validation qu'un développeur humain.

Étape 4 : Écrire des plans de tâches avant l'exécution de l'agent

Avant de demander à un agent d'implémenter une fonctionnalité, écrivez un document de plan structuré qui spécifie les fichiers à modifier, les contraintes à suivre et les critères d'acceptation. Stockez ces plans dans votre repository.

Étape 5 : Mettre en place un nettoyage automatisé

Implémentez une tâche CI hebdomadaire ou nocturne qui scanne votre base de code pour détecter les écarts par rapport à vos normes documentées et crée des pull requests de refactoring ciblées.

Choisir votre système d'agent

Les principes du Harness engineering s'appliquent quel que soit l'agent que vous utilisez :

Le harness réside dans votre repository, pas dans votre agent. Cela signifie que vous pouvez changer d'agent sans perdre votre investissement dans le harness.

Passer d'un agent à plusieurs

L'expérience OpenAI a démontré que le Harness engineering permet l'exécution parallèle d'agents. Parce que le harness impose des limites architecturales, plusieurs agents peuvent travailler simultanément sur différentes parties de la base de code sans créer de conflits.

Conditions clés pour l'exécution parallèle d'agents :

1. Propriété claire des modules — chaque agent travaille dans une limite définie.
2. Interfaces typées entre les modules — les agents peuvent coder par rapport à des interfaces sans connaître les détails d'implémentation.
3. Prévention des conflits de fusion — les tâches sont délimitées pour minimiser le chevauchement de fichiers.
4. Validation centralisée — tous les agents soumettent au même pipeline CI.

Partie 6 : Pièges courants et anti-modèles

Anti-modèle 1 : Traiter l'agent comme le harness

L'agent n'est pas le harness. Le harness est l'environnement dans lequel l'agent opère. Demander à un modèle plus intelligent de compenser un repository mal structuré est la mauvaise approche. Réparez l'environnement, pas le prompt.

Anti-modèle 2 : Documentation au mauvais endroit

si vos décisions architecturales vivent dans Confluence, Notion ou Google Docs, les agents ne peuvent pas les voir. La solution est simple mais demande de la discipline : déplacez toute la documentation pertinente pour le développement dans le repository.

Anti-modèle 3 : Nettoyage manuel au lieu de l'application automatisée

Si vous passez un temps important à nettoyer le code généré par les agents, vous avez besoin d'une meilleure application des règles, pas de plus de sessions de nettoyage. Chaque tâche de nettoyage récurrente devrait devenir soit une règle de linter, soit un test structurel, soit un travail de refactoring automatisé.

Anti-modèle 4 : Trop de contraintes

Un harness trop rigide empêche les agents de trouver des solutions créatives. L'objectif est de contraindre l'architecture, pas l'implémentation. Dites aux agents quels modules ils peuvent modifier et quelles dépendances sont autorisées, mais laissez-les décider comment implémenter la logique dans ces limites.

Anti-modèle 5 : Ignorer les retours des agents

Lorsqu'un agent échoue de manière répétée sur certaines tâches, l'échec indique généralement une lacune dans le harness, et non une limitation de l'agent. Suivez les modèles d'échec et utilisez-les pour améliorer votre documentation, vos tests structurels ou vos contraintes architecturales.

Partie 7 : L'avenir du Harness Engineering

La perspective de Martin Fowler

Martin Fowler a publié une analyse du Harness engineering sur son blog, notant qu'il représente un changement fondamental dans la manière dont les équipes logicielles opèrent. La discipline emprunte à des décennies de meilleures pratiques en génie logiciel — intégration continue, architecture decision records (ADR), injection de dépendances — mais les réutilise pour un monde piloté par les agents. Source

Le framework HumanLayer

L'équipe de HumanLayer a publié son analyse qualifiant le Harness engineering de « skill issue » (problème de compétence) — arguant que la capacité à concevoir des harnesses efficaces deviendra le principal différenciateur entre les équipes d'ingénierie performantes et celles en difficulté. Source

Ce que cela signifie pour les développeurs

Le Harness engineering ne remplace pas la compétence du développeur — il la réoriente. Au lieu d'écrire du code, les ingénieurs seniors conçoivent les systèmes qui permettent aux agents de bien écrire du code. Les compétences qui comptent passent de l'implémentation à l'architecture, du codage à la conception de systèmes, de l'écriture de tests à la conception de frameworks de tests.

Pour les équipes qui construisent des applications, des plateformes comme ZBuild intègrent déjà les principes du Harness engineering dans leurs workflows de création d'applications. Plutôt que d'exiger des développeurs qu'ils conçoivent leurs propres harnesses de zéro, ZBuild fournit des modèles architecturaux pré-configurés, une gestion des dépendances et des systèmes de validation qui guident les agents AI vers une sortie de haute qualité — laissant les développeurs se concentrer sur les décisions produit plutôt que sur l'infrastructure.

Les trois horizons

À l'avenir, le Harness engineering devrait évoluer à travers trois phases :

1. À court terme (2026) : Les équipes adoptent la documentation centrée sur le repository, les tests structurels et les principes d'or. Le développement assisté par agent devient une pratique standard pour les projets bien harnachés.

2. À moyen terme (2027) : La génération de harness elle-même devient pilotée par les agents. Les agents analysent les bases de code existantes et proposent des configurations de harness — règles de linter, tests structurels, limites de dépendances — basées sur les modèles qu'ils observent.

3. À long terme (2028+) : Les harnesses deviennent adaptatifs. Au lieu de règles statiques, ils évoluent en fonction des résultats du code généré par les agents, resserrant automatiquement les contraintes dans les zones où les agents produisent fréquemment des erreurs et assouplissant les contraintes là où ils réussissent systématiquement.

Partie 8 : Checklist pratique

Utilisez cette checklist pour évaluer la maturité de votre équipe en matière de Harness engineering :

Fondation (Commencez ici)

• ARCHITECTURE.md existe à la racine du repository.
• Le formatage du code est automatisé (Prettier, Black, gofmt).
• Le linting s'exécute sur chaque pull request.
• La vérification des types est imposée (TypeScript strict, mypy, etc.).

Intermédiaire

• Les tests structurels valident les limites des dépendances.
• Les principes d'or sont documentés et applicables par machine.
• Des plans de tâches sont écrits avant l'exécution de l'agent.
• Les pull requests générées par les agents passent par la même CI que les pull requests humaines.

Avancé

• Une garbage collection automatisée s'exécute selon un calendrier.
• Plusieurs agents peuvent travailler en parallèle sans conflits.
• Les modèles d'échec des agents sont suivis et utilisés pour améliorer le harness.
• Le harness lui-même est contrôlé par version et révisé comme du code.

Expert

• Les agents génèrent des parties du harness (règles de linter, tests structurels).
• Des notes de qualité sont automatiquement attribuées à chaque module.
• Les améliorations du harness sont basées sur les données des taux de réussite des agents.
• L'équipe livre plus de code par ingénieur et par semaine qu'avant l'adoption des agents.

Conclusion

Le Harness engineering n'est pas un effet de mode. C'est l'évolution naturelle du génie logiciel à une époque où les agents AI sont suffisamment capables pour écrire du code de production mais ont besoin d'environnements structurés pour bien le faire. L'expérience d'un million de lignes d'OpenAI a prouvé le concept à grande échelle, et les principes qu'ils ont articulés — connaissance centrée sur le repository, principes d'or, architecture en couches, garbage collection automatisée et plans exécutables — sont applicables aux équipes de toutes tailles.

Les équipes qui maîtriseront le Harness engineering en 2026 livreront plus vite, maintiendront une meilleure qualité de code et évolueront plus efficacement que celles qui traitent les agents AI comme de l'autocomplétion glorifiée. L'agent est le cheval. Le harness est ce qui le rend utile.

Sources

• Harness Engineering: Leveraging Codex in an Agent-First World — OpenAI
• Unlocking the Codex Harness: How We Built the App Server — OpenAI
• Unrolling the Codex Agent Loop — OpenAI
• OpenAI Introduces Harness Engineering — InfoQ
• Harness Engineering — Martin Fowler
• Skill Issue: Harness Engineering for Coding Agents — HumanLayer
• From Prompt Engineering to Harness Engineering — SoftmaxData
• How to Build an Agent Harness — Study Notes
• Harness Engineering — GTCode
• OpenAI Harness Engineering: Ship 1M Lines of Code — The Neuron
• How OpenAI Built 1M Lines of Code Using Only Agents — TonyLee
• Harness Engineering — The New Discipline — CodeNote