Harness engineering — construire l'environnement qui rend un agent IA fiable

1📖 Glossaire — le vocabulaire de base

• Harness — tout ce qui n'est pas le modèle : prompt système, outils, environnement d'exécution, fichiers d'état, boucles de vérification, orchestration.
• Context engineering — choisir quels tokens le modèle voit à un instant donné (fichiers, résultats d'outils, mémoire). Sous-ensemble du harness.
• Progressive disclosure — ne charger une information dans le contexte que lorsqu'elle devient nécessaire, via un point d'entrée court qui pointe vers des documents détaillés.
• Compaction — résumer et décharger le contexte quand la fenêtre se remplit, pour continuer sans repartir de zéro.
• Agent initialisateur — l'agent (ou la session) qui prépare le dépôt avant tout travail de feature : instructions, liste de features, script de démarrage, premier commit.
• Feature list — fichier machine-lisible qui liste chaque fonctionnalité avec son état, sa commande de vérification et sa preuve de réussite.
• WIP = 1 — work in progress limité à une seule tâche active par session ; on n'en démarre une autre qu'après vérification de la précédente.
• Generator / Evaluator — séparation entre l'agent qui produit le travail et un agent indépendant qui le juge.
• Victoire prématurée — l'agent déclare la tâche terminée sur la base de « le code a l'air correct », sans preuve d'exécution bout en bout.
• Handoff — note compacte laissée en fin de session pour que la suivante sache ce qui est vérifié, ce qui est cassé et quelle est la prochaine action.
• Ablation — retirer un composant du harness à la fois, modèle fixé, et mesurer la baisse de résultat pour savoir ce qui contribue vraiment.
• Loop engineering — concevoir une boucle autonome (planifier, agir, vérifier, committer, passer la main) avec condition d'arrêt machine-vérifiable.
• Graph engineering — organiser plusieurs boucles, agents et évaluateurs en nœuds et arêtes explicites avec état partagé.

2L'échec : une tâche, deux résultats

Voici le point de départ. Une équipe demande à son agent, en une phrase : « ajoute la réservation de stock à l'API d'inventaire ». Le modèle est l'un des meilleurs du marché. Résultat de la première session :

• près de la moitié du contexte part en exploration du dépôt (quelle version de Spring ? comment on lance les tests ? où sont les contrôleurs ?) ;
• l'agent utilise une syntaxe d'ORM dépassée, parce que la convention « on n'écrit plus les requêtes comme ça » vivait dans la tête de l'équipe ;
• il crée l'endpoint, le modèle, un job d'expiration, refactore au passage la gestion d'erreurs : six chantiers ouverts, aucun fini ;
• il termine par « les tests passent », alors qu'aucune commande de test ne lui a jamais été donnée.

Le cours walkinglabs classe ce qui vient de se passer en cinq modes d'échec. Aucun n'est une question d'intelligence : ce sont des trous dans l'environnement que le modèle comble en devinant.

Pourquoi « un meilleur prompt » ne suffit pas

Le premier réflexe est d'allonger la demande. C'est l'ère du prompt engineering : bien formuler, donner des exemples, imposer un format. Mais un prompt ne mémorise rien et ne voit pas le projet. Deuxième réflexe : montrer plus de choses au modèle. C'est le context engineering : fichiers d'instructions, RAG, mémoire, compaction. Le modèle voit alors tout… et déclare toujours « fini » sans preuve, parce que voir n'est pas vérifier. Le harness engineering est la couche externe : il ne se demande pas quoi dire ni quoi montrer, mais comment concevoir le système pour que le résultat soit vérifié et que la session suivante reparte proprement.

Le point de bascule a été documenté publiquement en quelques semaines : Mitchell Hashimoto nomme la pratique le 5 février 2026, OpenAI publie le 11 février son retour d'expérience sur un produit d'un million de lignes écrit sans une ligne manuelle, LangChain formalise en mars l'équation Agent = Modèle + Harness.

3Le diagnostic : cinq sous-systèmes et un instrument de mesure

Avant de réparer, il faut savoir de quoi un harness est fait. Le cours walkinglabs le découpe en cinq briques, et chacune répond à une question simple :

• les instructions : qu'est-ce que l'agent doit savoir avant de commencer ?
• les outils : qu'est-ce qu'il a le droit de faire (lancer une commande, lire un fichier, ouvrir un navigateur) ?
• l'environnement : où travaille-t-il, et ce monde est-il reproductible d'une session à l'autre ?
• l'état : qu'est-ce qui survit quand la conversation se termine ?
• le feedback : comment apprend-il qu'il s'est trompé ?

D'autres sources décrivent le même découpage avec d'autres mots. LangChain parle de prompt système, outils, filesystem, sandbox et mémoire ; un survey académique parle de boucle d'exécution, registre d'outils, gestionnaire de contexte, store d'état, hooks et interface d'évaluation. Peu importe le vocabulaire : ce sont les mêmes cinq briques. C'est cette grille qu'on va suivre dans tout le reste de la note, et le schéma ci-dessous les place autour du modèle.

Mesurer ce qui compte : l'ablation

Comment savoir si un sous-système sert à quelque chose, ou si on empile des fichiers par superstition ? Le cours donne un instrument, emprunté à la recherche : l'ablation. Modèle fixé, tâche fixée, on retire un composant à la fois et on mesure la baisse. La plus forte baisse indique la contribution marginale la plus élevée pour cette tâche. Une baisse nulle ne veut pas dire « inutile » : le composant peut être redondant, mal conçu, ou simplement jamais sollicité par cette tâche. Le diagnostic doit croiser l'ablation avec les journaux d'échec. Le projet final du cours (projet 06) est exactement cela : assembler le harness complet, le benchmarker contre une version affaiblie, puis retirer les composants un par un.

Le cours cite une progression illustrative (pas une mesure publiée) sur une application TypeScript/React d'environ 20 000 lignes, modèle identique :

4Avant tout : la session d'initialisation

Reprenons la réservation de stock. Avant de redemander quoi que ce soit à l'agent, on consacre une session entière à préparer le dépôt. Anthropic appelle cela l'agent initialisateur : son rôle n'est pas d'écrire une feature mais de laisser une base stable. Le playbook du cours fixe cinq artefacts obligatoires à la sortie de cette session :

1. un fichier d'instructions racine (AGENTS.md ou CLAUDE.md) ;
2. une liste de features lisible par machine (feature_list.json) ;
3. un journal de progression durable (progress.md) ;
4. un script de démarrage standard (init.sh) ;
5. un premier commit propre qui capture l'échafaudage.

Et un critère de réussite, le test de session fraîche : un agent neuf, sans aucun contexte de conversation, avec le seul dépôt, doit pouvoir répondre à cinq questions. Que fait ce dépôt ? Comment le lancer ? Comment le vérifier ? Qu'est-ce qui reste inachevé ? Quelle est la meilleure prochaine étape ? Chaque « je ne sais pas » est un endroit où il devinera.

Le dépôt comme seul monde de l'agent

Un agent ne lit que quatre choses : le prompt système, la tâche, les fichiers du dépôt et la sortie de ses outils. Il ne consulte ni le chat d'équipe, ni le wiki, ni la tête d'un collègue. D'où le principe d'OpenAI : ce que l'agent ne peut pas atteindre en contexte n'existe pas. Tout ce qui compte doit être versionné : décisions d'architecture, plans d'exécution, specs produit, dette technique. C'est pour ça que notre agent utilisait une syntaxe d'ORM dépassée : la bonne convention n'existait pas, pour lui.

Le piège du fichier d'instructions géant

Le réflexe suivant est connu : l'agent se trompe, on ajoute une règle, le fichier passe de 300 à 450 puis 600 lignes. Quatre mécanismes le rendent contre-productif :

1. Budget de contexte : 600 lignes coûtent 10 à 20 k tokens à chaque appel, au détriment du code à analyser.
2. Effet « lost in the middle » : les modèles sous-utilisent ce qui est au milieu d'un long document ; la contrainte critique en ligne 300 est ignorée.
3. Écrasement des priorités : « ne jamais utiliser eval() » et « préférer le style fonctionnel » ont le même format, l'agent ne distingue plus l'interdit du conseil.
4. Pourriture : supprimer fait peur, ajouter est gratuit, le rapport signal/bruit s'effondre.

La règle de calibration du cours tient en deux listes. Reste dans le fichier racine : objectif et périmètre du dépôt, chemin de démarrage, chemin de vérification, contraintes non négociables, artefacts d'état attendus, règles de fin de session. Sort du fichier racine : cas particuliers historiques, détails d'implémentation d'un seul sujet, notes d'architecture locales (qui vont à côté du code), exemples qui ne concernent qu'un sous-système.

OpenAI a gardé AGENTS.md à environ 100 lignes, comme table des matières vers un répertoire docs/ structuré. Voici ce que l'initialisateur laisse pour notre service d'inventaire :

# AGENTS.md — service d'inventaire

## Vue d'ensemble
API REST Java 25 / Spring Boot 4.1, PostgreSQL 18. Gère les stocks par entrepôt.

## Démarrage
- Setup : ./init.sh                     # ✓ installe, vérifie, lance
- Tests : ./mvnw verify                 # ✓ obligatoire avant toute PR
- Lint architecture : ./mvnw -Parch     # ✓ ArchUnit, bloque en CI

## Contraintes dures (non négociables)
- Les contrôleurs n'appellent jamais un repository directement (couche service obligatoire).
- Toute écriture en base passe par une transaction explicite.
- Aucun appel réseau sortant dans les tests unitaires.

## Definition of done
Une feature est terminée quand sa commande `verification` dans feature_list.json
passe ET que la preuve est consignée dans progress.md.

## Documentation (à lire selon la tâche)
- docs/architecture.md     — couches et sens des dépendances. Lire avant tout nouveau module.
- docs/api-conventions.md  — pagination, erreurs, versioning. Lire avant tout endpoint.
- docs/testing.md          — Testcontainers, fixtures. Lire avant d'écrire un test.
- docs/exec-plans/         — plans en cours ; un fichier par chantier.

Les documents thématiques font 50 à 150 lignes chacun et ne sont chargés que si la tâche le justifie : c'est la progressive disclosure, exactement le mécanisme des skills décrit dans outiller-developpement-ia-skills-agents-instructions.

Un environnement qui se décrit lui-même

Le deuxième trou de notre première session était le temps perdu à comprendre comment lancer le projet. Le script d'initialisation le bouche, et il a une règle : si la vérification de base échoue, l'agent répare la base avant toute autre chose.

#!/usr/bin/env bash
# init.sh — reproducible startup for every agent session
set -euo pipefail

INSTALL_CMD="./mvnw -q dependency:resolve"
VERIFY_CMD="./mvnw -q verify"
START_CMD="./mvnw spring-boot:run"

echo "▶ working dir: $(pwd)"
docker compose up -d postgres            # ✓ environment is self-describing
$INSTALL_CMD
$VERIFY_CMD                               # ✓ baseline must be green before any change
echo "▶ start with: $START_CMD"

5Pendant : une session de travail, une seule feature

Le dépôt est prêt. L'agent revient pour la réservation de stock, cette fois avec un contexte vide mais un dépôt qui parle. Le cours fixe une routine de démarrage immuable, dans cet ordre, parce que chaque étape protège la suivante :

1. pwd : confirmer la racine du dépôt (éviter de travailler au mauvais endroit).
2. Lire progress.md : restaurer l'état durable avant tout changement.
3. Lire feature_list.json : savoir ce qui est fait, en cours, bloqué.
4. git log --oneline -5 : voir ce qui a bougé en dernier.
5. Lancer ./init.sh : démarrer de façon standard, pas de mémoire.
6. Lancer un smoke test de base : détecter un point de départ cassé avant qu'un nouveau travail ne le masque.
7. Si la base est cassée, la réparer d'abord.
8. Choisir la feature non terminée de plus haute priorité.
9. Travailler uniquement sur cette feature jusqu'à ce qu'elle soit vérifiée ou explicitement bloquée.

sequenceDiagram
    participant H as Humain
    participant I as Agent initialisateur
    participant R as Dépôt (état)
    participant C as Agent de code (session N)
    participant V as Vérification (tests, navigateur)

    H->>I: prompt haut niveau
    I->>R: init.sh + feature_list.json (toutes à not_started)
    I->>R: progress.md + premier commit
    Note over R: L'état vit dans le dépôt, pas dans la conversation

    loop Chaque nouvelle session (contexte vide)
        C->>R: lit progress.md + git log + feature_list.json
        C->>V: lance init.sh, vérifie l'état de base
        C->>C: choisit UNE feature not_started (WIP = 1)
        C->>C: implémente la feature
        C->>V: exécute la commande de vérification de la feature
        V-->>C: preuve (sortie de test, capture)
        C->>R: passes = true + evidence, commit, progress.md mis à jour
        Note over C,R: État propre : build OK, tests OK, pas d'artefact de debug
    end

Pourquoi une seule feature

Le troisième trou de la première session, c'était six chantiers ouverts et aucun fini. Avec une capacité de contexte C répartie sur k tâches, chaque tâche reçoit C/k ; sous un seuil, rien n'aboutit. L'exemple du cours sur une API à huit features : sans contrainte, cinq features ouvertes, 800 lignes sur 12 fichiers, 20 % de tests verts ; avec WIP = 1, 200 lignes par feature, 100 % de tests verts par session.

feature_list.json : le primitif, pas le document

La différence entre un document et un primitif : un document est lu par des humains et peut être ignoré ; un primitif est exécuté par le harness. Le planificateur y choisit la prochaine feature, le vérificateur y autorise les transitions d'état, le rapport de fin de session en est généré. Chaque entrée porte un triplet : comportement attendu, commande de vérification, état.

{
  "features": [
    {
      "id": "F03",
      "priority": 3,
      "area": "stock",
      "title": "Réserver une quantité sur un entrepôt",
      "user_visible_behavior": "POST /warehouses/{id}/reservations avec {sku, quantity} retourne 201 et décrémente le stock disponible",
      "verification": "./mvnw test -Dtest=ReservationControllerIT && curl -sf -X POST localhost:8080/warehouses/w1/reservations -d '{\"sku\":\"A-100\",\"quantity\":2}' -H 'Content-Type: application/json'",
      "status": "passing",
      "evidence": "commit 4f2a9c1 — ReservationControllerIT 6/6 vert, curl 201",
      "notes": "Le stock négatif renvoie 409, cf. docs/api-conventions.md"
    },
    {
      "id": "F04",
      "priority": 4,
      "area": "stock",
      "title": "Libérer une réservation expirée",
      "user_visible_behavior": "Un job planifié remet en stock les réservations de plus de 15 min",
      "verification": "./mvnw test -Dtest=ReservationExpiryJobTest",
      "status": "in_progress",
      "evidence": null,
      "notes": null
    }
  ]
}

Règles de la machine à états : quatre états (not_started, in_progress, blocked, passing), une seule feature in_progress à la fois, et seul le succès de la commande verification autorise le passage à passing. Dans l'expérience d'Anthropic, l'agent n'avait le droit de modifier que le champ de réussite, jamais de supprimer une feature : c'est ce qui empêche la victoire prématurée par effacement du périmètre.

6Prouver avant de déclarer : la vérification

Notre agent a implémenté F03 et annonce que c'est terminé. Le quatrième trou de la première session, c'était cette phrase sans preuve. Ici, le harness la refuse structurellement.

Pourquoi l'agent déclare victoire trop tôt

Les réseaux de neurones modernes sont systématiquement sur-confiants : la confiance rapportée dépasse la précision réelle. L'agent juge « localement » (le code a l'air juste, les tests unitaires passent) alors que l'échec est « global » (migration absente, config manquante, deux composants mockés chacun de leur côté qui ne s'emboîtent pas). Exemple canonique du cours : une réinitialisation de mot de passe où schéma, endpoint et template sont écrits, les tests unitaires verts, et rien ne fonctionne bout en bout.

Trois couches de validation, sans raccourci entre elles :

1. Syntaxe et analyse statique : rapide, peu d'information.
2. Comportement à l'exécution : tests, chemins critiques.
3. Confirmation système : bout en bout, comme un utilisateur.

Anthropic a constaté que donner à l'agent des outils d'automatisation de navigateur et lui demander de tester « comme un humain le ferait » a changé le résultat : il a trouvé des bugs invisibles à la lecture du code. OpenAI a intégré le protocole DevTools de Chrome dans le runtime de l'agent : lancer une instance isolée, capturer le DOM, comparer visuellement, interroger les logs et métriques, et boucler parfois six heures sans intervention.

Séparer celui qui produit de celui qui juge

Un modèle qui note son propre travail le loue avec assurance, même quand la qualité est visiblement médiocre pour un humain. Anthropic a documenté ce biais et l'a corrigé en séparant Planner, Generator et Evaluator, l'évaluateur testant l'application qui tourne via Playwright et notant selon des critères mesurables. Avant de coder, générateur et évaluateur négocient un contrat de sprint : des critères d'acceptation testables. L'évaluateur a attrapé un outil de remplissage qui ne posait que les extrémités, des routes renvoyant 422, un enregistrement audio resté un stub.

Le projet 05 du cours rend ce choix mesurable : on implémente la même feature trois fois, en ajoutant un rôle à chaque fois (agent seul qui se note, puis générateur + évaluateur, puis planificateur + générateur + évaluateur), et on compare les grilles. La grille d'évaluateur fournie note six dimensions de 0 à 2 (correction, vérification, discipline de périmètre, fiabilité, maintenabilité, prêt pour le handoff) et rend un verdict : Accept, Revise ou Block. Elle se calibre : on compare ses scores au jugement humain, on resserre les critères là où ils divergent, et on recommence trois à cinq cycles jusqu'à alignement.

flowchart LR
    S[("État externe<br/>progress.md · feature_list.json · issues")] --> P["Planifier<br/>lire l'état, choisir UNE tâche"]
    P --> A["Agir<br/>générateur, worktree isolé"]
    A --> V{"Vérifier<br/>évaluateur indépendant<br/>tests + navigateur"}
    V -- échec, message actionnable --> A
    V -- preuve --> C["Committer<br/>seul le validé rejoint main"]
    C --> H["Passer la main<br/>mettre à jour l'état externe"]
    H --> S
    STOP{{"Condition d'arrêt<br/>machine-vérifiable"}} -.-> P

Linters qui parlent à l'agent

Le deuxième trou de la première session, la convention implicite, se bouche ici aussi, mais mécaniquement. L'idée la plus réutilisable du retour d'OpenAI : les règles d'architecture sont appliquées par des linters personnalisés, des tests structurels et des jobs CI qui bloquent la PR. Et le message d'erreur n'est plus écrit pour un humain : il injecte la correction dans le contexte de l'agent, avec un lien vers la doc concernée.

// ArchUnit test — the failure message is written FOR the agent, not for a human reviewer
@ArchTest
static final ArchRule controllers_must_not_touch_repositories =
    noClasses().that().resideInAPackage("..controller..")
        .should().dependOnClassesThat().resideInAPackage("..repository..")
        .because("""
            Controllers must call a @Service, never a repository.        // ⚠️ hard constraint
            Fix: move the data access into an existing service in src/main/java/.../service,
            or create one. Rationale and examples: docs/architecture.md#layers.
            Do NOT add an exception to this rule.""");

Thoughtworks classe ces contrôles en deux familles : feedforward (guides qui anticipent : doc, types, scripts de bootstrap) et feedback (capteurs qui observent : linters, tests, revue par IA), et en deux natures : computationnels (déterministes, millisecondes) et inférentiels (sémantiques, lents, non déterministes). Règle de placement : les contrôles bon marché en pré-commit, les contrôles coûteux dans le pipeline.

7À la fin : passer la main proprement

F03 est vérifiée, commitée. Reste le cinquième trou : que la session suivante ne redécouvre pas tout. Le cours impose une routine de fin de session symétrique de celle du démarrage : consigner le progrès, mettre à jour le statut des features, écrire une note de handoff si nécessaire, committer le travail sûr, laisser un chemin de redémarrage propre.

Qu'est-ce qu'un état propre ?

Cinq conditions, simultanées : build vert, tous les tests verts (y compris les anciens), progrès consigné, aucun artefact de debug, chemin de démarrage fonctionnel. En manquer une, la session n'est pas « finie ». La checklist d'état propre du cours ajoute une vérification de cohérence : la liste de features doit refléter la réalité, aucune entrée passing qui ne le soit pas.

Le fichier de progression est la source de vérité de l'état courant : racine du dépôt, commande de démarrage, commande de vérification, feature prioritaire non terminée, bloqueurs, puis un journal par session (objectif prévu, réalisé, vérifications lancées, commits, risque introduit, prochaine action). Pour les sessions longues ou les projets à plusieurs chantiers, une note de handoff compacte s'y ajoute : ce qui est vérifié, ce qui a changé, ce qui est encore cassé ou non vérifié, la meilleure prochaine action et ce qu'il ne faut pas toucher, les commandes clés de démarrage, vérification et debug.

L'observabilité à l'intérieur du harness

Sans visibilité sur ce qui s'exécute, les retries sont aveugles (l'agent tape au hasard), l'évaluation devient subjective et le progrès est invisible. Le cours chiffre l'écart : implémenter un mode sombre prend 45 minutes en trois ou quatre itérations à l'aveugle, 15 minutes en une itération avec logs et traces accessibles. Deux niveaux à prévoir :

• Runtime : phases de vie de l'application, exécution des chemins fonctionnels avec points de passage, contexte complet des erreurs (pas seulement le message).
• Processus : contrats de sprint, grilles de notation, traces de tâche enregistrant le contexte de chaque étape, à la manière du tracing distribué.

L'agent ne peut pas s'instrumenter lui-même : il ne sait pas ce qu'il ne sait pas. Le harness doit imposer des formats constants et une collecte automatique. OpenAI a donné à ses agents un accès direct aux logs et métriques via LogQL et PromQL, et le cours recommande les conventions sémantiques OpenTelemetry pour l'IA générative. Pour la consommation de tokens côté outillage, voir codeburn-stats-de-tokens-et-couts-pour-claude-code-agents-ia.

Entropie et ramasse-miettes

Lehman l'avait observé pour tout logiciel : un système en changement continu se complexifie sauf effort actif. Avec des agents qui produisent plus vite que les humains ne relisent, l'entropie explose. Le cours illustre une dégradation sur douze semaines : build vert de 100 à 68 %, tests de 100 à 61 %, démarrage de 5 à plus de 60 minutes. Deux parades au-delà de l'état propre par session :

1. Ramasse-miettes périodique : OpenAI a encodé ses « principes d'or » en règles mécaniques et lance des tâches d'agent en arrière-plan, à cadence fixe, qui scannent les écarts et ouvrent des PR de refactoring. Le goût humain est capturé une fois, puis appliqué en continu.
2. Document de qualité : un snapshot de santé qui note chaque domaine produit et chaque couche d'architecture de A à D (statut de vérification, lisibilité pour l'agent, stabilité des tests, lacunes). Là où la grille d'évaluateur juge une session, ce document suit si le projet s'améliore dans le temps. Il sert aussi à simplifier le harness : retirer un composant, relancer les benchmarks, comparer les snapshots, remettre le composant si les notes baissent. C'est l'ablation appliquée en continu.

8Sans soi : du prompt manuel à la boucle, puis au graphe

Le harness tient sur une session. L'étape suivante est de ne plus être là. La progression observée dans toute l'industrie : prompts un par un, puis longs prompts multi-étapes, puis auto-réflexion de l'agent, puis jugement d'arrêt indépendant. Le pont est le modèle du « but » : on fournit un objectif, une méthode de vérification et une condition d'arrêt, et l'agent boucle jusqu'à satisfaction.

Trois boucles, par ordre de délégation

Le projet 07 du cours fait construire trois boucles sur le harness de la section précédente, chacune confiant un peu plus à la machine :

Six primitives rendent ces boucles viables : automatisations (cron, webhooks), worktrees isolés, skills, connecteurs, sous-agents maker/checker, et état externe hors conversation. L'exemple de référence est la boucle de recherche de Karpathy : un program.md en langage naturel décrit la méthodologie, et un cliquet à neuf étapes ne garde sur main que les commits qui améliorent la métrique. Résultat : environ 11 % de temps d'entraînement gagné par accumulation de micro-optimisations, sans humain dans la boucle.

Quatre coûts silencieux des boucles longues : dette de vérification (on saute la confirmation machine), pourriture de compréhension (plus personne ne comprend le code généré), abandon cognitif (on accepte sans relire), explosion de tokens (le contexte croît de façon quadratique avec les itérations). La phrase à retenir du cours : les boucles rendent la génération presque gratuite et font du jugement la ressource rare.

Quand la boucle devient un graphe

Dès qu'un agent a besoin de spécialisation, de parallélisme, d'état partagé, de vérification et de reprise, ce n'est plus une boucle, c'est un graphe : des nœuds (code déterministe, appel de modèle, outil ou agent complet), des arêtes (handoffs avec parallélisme, conditions, retry, rollback), un état partagé et des règles de routage. Le projet 08 montre que le graphe n'est pas un choix de design mais ce qu'une boucle devient quand on l'écrit noir sur blanc : en dessinant la boucle maker/checker, on trouve toujours au moins une arête implicite, une décision qui vivait cachée dans le contexte de l'agent. Trois ajouts caractéristiques :

• Fan-out / fan-in : découper en sous-tâches indépendantes, chacune dans son worktree, avec un critère de fusion explicite (les deux revues doivent passer, ou une seule). On mesure temps, tokens et qualité avec et sans parallélisme pour vérifier que la coordination ne mange pas le gain.
• Arête de rollback ciblée : un échec « partiel » renvoie au nœud responsable, pas toujours à l'implémentation. Si les tests passent mais que la revue révèle une exigence mal comprise, on retourne à la recherche. Cela suppose que l'état enregistre quelle étape a échoué.
• Nœud d'approbation humaine : avant la fusion, le graphe s'arrête jusqu'à ce qu'un humain écrive « approved » ou « rejected » dans l'état, avec une règle de timeout qui rejette ou escalade après N heures.

Trois échecs des boucles monolithiques y trouvent une réponse : la loi de Goodhart (le bot support qui ferme les tickets au lieu de les résoudre), la cécité vers le haut (une boucle ne questionne jamais son objectif) et le conflit entre boucles indépendantes. Cinq critères, dont au moins trois doivent tenir avant de dessiner un graphe : la tâche se décompose en unités indépendantes ; des branches ou rollbacks méritent d'être explicites ; l'état intermédiaire vaut d'être sauvegardé pour reprise ; la definition of done est vérifiable automatiquement ; le bénéfice de coordination dépasse son coût.

9Ce que font les harness du marché

On a construit un harness à la main. Les outils du marché en embarquent un, et les lire avec la grille des cinq sous-systèmes montre qu'ils répondent aux mêmes problèmes par des choix différents. Le même modèle peut scorer très différemment selon le harness : LangChain est passé du top 30 au top 5 de Terminal Bench 2.0 en ne touchant que le harness, modèle inchangé.

Deux lectures transversales. D'abord, chacun a inventé sa propre réponse à la victoire prématurée : le hook Stop de Claude Code, la commande de vérification obligatoire de Codex, l'extension session-summary de Pi, l'événement agent/turn-stopping de DeepSeek. Ensuite, tous convergent vers un journal append-only et rejouable comme fondation de l'état : le handoff est garanti par la couche de stockage, pas par la mémoire du modèle.

Cursor va plus loin et traite son harness comme un produit : évals hors ligne, A/B tests en ligne (latence, tokens, nombre d'appels d'outils, taux de cache), un « keep rate » qui mesure la part de code généré qui survit, une taxonomie des erreurs d'outils où toute erreur inconnue est un bug du harness, et un harness ajusté par modèle (format d'édition, prompts). En un sprint, les erreurs d'appel d'outil inattendues ont baissé d'un ordre de grandeur sans changer de modèle.

Deux retours d'expérience donnent l'échelle de ce qu'un harness mûr permet :

10Démarrer vite : templates, skill et pack avancé

Tout ce qui précède existe sous forme prête à copier. Trois niveaux, du plus léger au plus structuré.

Les huit templates du cours

Le skill harness-creator

Le cours livre aussi un skill (voir outiller-developpement-ia-skills-agents-instructions pour la notion) qui automatise la création et l'audit d'un harness :

npx skills add walkinglabs/learn-harness-engineering --skill harness-creator

Son workflow : inspecter ce qui existe (fichiers d'instructions, d'état, commandes de vérification), ne demander que ce qui ne s'infère pas (agent cible, nom de fichier, droit d'écraser), démarrer minimal. Il note cinq sous-systèmes (instructions, état, vérification, périmètre, cycle de vie), traite le score le plus bas comme candidat goulot à confirmer par les logs et les échecs réels, et recommande les deux ou trois premiers changements. Quatre scripts Node : create-harness.mjs (échafaudage), validate-harness.mjs (audit), render-assessment-html.mjs (rapport partageable), run-benchmark.mjs (benchmark structurel). Sept fiches de patterns l'accompagnent : persistance mémoire, runtime de skills, context engineering, registre d'outils, coordination multi-agents, cycle de vie et bootstrap, et une liste de quinze pièges non évidents.

Le pack avancé d'OpenAI

Quand le dépôt a dépassé le harness minimal, le cours propose une structure opinionée dérivée du retour d'OpenAI : AGENTS.md et ARCHITECTURE.md à la racine, un docs/ avec design docs et croyances fondatrices, plans d'exécution actifs et terminés plus un suivi de dette, specs produit, artefacts générés (schéma de base), références au format llms.txt pour les outils externes, et des fichiers de politique explicites : design, frontend, plans, sens produit, score de qualité, fiabilité, sécurité. Une bibliothèque de procédures (SOP) transforme les schémas de l'article en étapes : mise en place de l'architecture par couches, encodage d'une nouvelle connaissance dans le dépôt, stack d'observabilité locale, boucle de validation UI via Chrome DevTools. La règle d'adoption : commencer par le pack minimal, copier le pack avancé quand on en a besoin, et mettre à jour qualité, fiabilité et plans dans le flux normal de travail, pas lors d'une journée de nettoyage.

11Tableau de synthèse : du symptôme à l'artefact

Le cours fournit une carte de méthode qui résume la discipline en une règle : ajouter le plus petit artefact qui répare l'échec observé, jamais un paragraphe de plus dans le fichier d'instructions global.

Notes liées

• outiller-developpement-ia-skills-agents-instructions — les leviers individuels (prompt, skill, fichier d'instructions, hook, subagent) dont le harness est l'assemblage systémique.
• mcp-model-context-protocol — le protocole standard du sous-système « outils ».
• graphify-graphe-de-connaissances-pour-ia-de-code — externaliser la structure du code pour alléger le contexte.
• codeburn-stats-de-tokens-et-couts-pour-claude-code-agents-ia — mesurer la consommation de tokens, première brique d'observabilité du harness.

Sources

Le cours walkinglabs (source principale)

• Learn Harness Engineering — cours en 14 leçons ; structure de cette note.
• Projets 01 à 08 — baseline vs harness minimal, continuité multi-sessions, vérification par rôles (projet 05), capstone avec ablation (projet 06), première boucle (projet 07), premier graphe (projet 08).
• Bibliothèque : templates — les huit templates (AGENTS.md, init.sh, feature_list.json, claude-progress.md, session-handoff.md, clean-state-checklist.md, evaluator-rubric.md, quality-document.md).
• Bibliothèque : référence — carte de méthode, playbook de l'initialisateur, routine de démarrage, calibration des prompts, et une trentaine de sources 2026.
• Bibliothèque : pack avancé OpenAI — layout de dépôt opinioné et bibliothèque de SOP.
• Skill harness-creator — création, audit et benchmark structurel d'un harness ; sources du skill.
• Décryptages : Claude Code, Codex, Pi, DeepSeek Harness — lecture de chaque outil avec la grille des cinq sous-systèmes.
• Awesome Harness Engineering — liste curée : fondations, contexte et mémoire, garde-fous, specs, evals, runtimes, benchmarks.

Articles fondateurs

• Harness engineering: leveraging Codex in an agent-first world (OpenAI) — ~1 M de lignes sans code manuel, AGENTS.md en table des matières, linters à messages pour agent, ramasse-miettes.
• Effective harnesses for long-running agents (Anthropic) — agent initialisateur, feature list, fichier de progression, tests par automatisation de navigateur.
• Harness design for long-running application development (Anthropic) — Planner / Generator / Evaluator, biais d'auto-évaluation, contrats de sprint, simplification du harness quand le modèle progresse.
• The Anatomy of an Agent Harness (LangChain) — Agent = Modèle + Harness, composants, gain top 30 → top 5 sur Terminal Bench 2.0 à modèle constant.
• Harness engineering for coding agent users (Thoughtworks, Birgitta Böckeler) — contrôles feedforward / feedback, computationnels / inférentiels, harnessabilité, rôle de l'humain.
• My AI Adoption Journey (Mitchell Hashimoto) — origine du terme et de la méthode « une erreur observée = une correction structurelle ».
• Beyond Prompts and Context: Harness Engineering for AI Agents (madplay) — les trois ères prompt / contexte / harness et l'analogie équestre.

Mesure, évaluation, exploitation

• Demystifying evals for AI agents (Anthropic) — distinction harness d'évaluation / harness d'agent, graders par code, par modèle, humains, evals de capacité vs de régression.
• Continually improving our agent harness (Cursor) — le harness comme produit : évals hors ligne, A/B en ligne, keep rate, taxonomie des erreurs d'outils, harness par modèle.
• Unrolling the Codex agent loop (OpenAI) — anatomie de la boucle d'exécution, croissance du contexte, terminaison.
• Multi-Agents: What's Actually Working (Cognition) — boucles générateur / vérificateur, relecteurs à contexte propre, limites de la communication inter-agents.
• Evaluating AGENTS.md (ETH Zurich) — les fichiers de contexte n'améliorent pas systématiquement le taux de réussite et coûtent plus de 20 % d'inférence.
• Autoresearch, cliquet à neuf étapes (Karpathy, nanochat) — boucle de recherche autonome gardant seulement les commits qui améliorent la métrique.

Standards et outils cités

• AGENTS.md — format ouvert de fichier d'instructions pour agents.
• Claude Code : mémoire, hooks, sous-agents — documentation des mécanismes cités dans le décryptage.
• DeepSeek Harness : architecture — noyau Cordis, capability seams, journal de session.
• Pi : extensions — hooks de cycle de vie et compaction programmable.
• OpenTelemetry — conventions sémantiques GenAI — standard d'instrumentation des traces d'agents.