Anthropic a fait construire la même application, un éditeur de jeux rétro, de deux façons. Premier essai, un agent seul : une vingtaine de minutes, environ 9 $, et une fonction principale cassée. Second essai, un harness complet : environ six heures, 200 $, et une application jouable. Pris isolément, ces chiffres ne disent rien. Côte à côte, ils posent la vraie question d'un CTO : que contient ce qu'on construit autour du modèle, et que vaut chaque pièce ?
Un harness agentique est l'ensemble des rôles, boucles de contrôle, artefacts de passage de relais et vérifications qui entourent un modèle pour le faire travailler de façon fiable sur une tâche longue. Chaque composant encode une hypothèse sur ce que le modèle ne sait pas encore faire seul. Ce dernier article de la série montre comment concevoir un harness planner, générateur et évaluateur avec les briques de Claude Code, puis la moitié du travail qu'on oublie : le simplifier à chaque nouveau modèle, parce qu'un composant utile hier peut n'être aujourd'hui qu'un coût.
Qu'est-ce qu'un harness agentique, et quand en avoir besoin ?
Un harness n'est pas un framework à installer : c'est un ensemble de décisions de conception, chacune posée pour compenser une faiblesse du modèle. Le billet Harness design for long-running apps (24 mars 2026) le dit en une phrase : chaque composant d'un harness encode une hypothèse sur ce que le modèle ne sait pas faire seul, et cette hypothèse peut devenir fausse au modèle suivant. Le point de départ reste celui de Building effective agents (décembre 2024) : chercher la solution la plus simple possible, et n'ajouter de la complexité que lorsqu'elle est nécessaire.
Sur une tâche courte, le modèle seul suffit, surtout avec la vérification décrite dans l'article sur la vérification d'abord. Sur une tâche longue, il dérive : il perd le fil de ce qui reste à faire, déclare fini ce qui ne l'est pas, s'accommode de ses propres approximations. Le harness répond à cette dérive. Cet article traite de sa conception, pas de l'outillage d'orchestration, couvert dans notre article sur l'orchestration multi-agents.
Comment fonctionne l’architecture planner, générateur, évaluateur ?
- Le planner transforme une demande courte en spécification de livrables découpée en fonctionnalités. Il reste au niveau du comportement observable, pas des classes ni du schéma : une erreur de conception à ce stade se propage en cascade.
- Le générateur implémente une fonctionnalité à la fois, utilise git, et ne décide jamais lui-même qu'elle est terminée.
- L'évaluateur exécute l'application comme un utilisateur (Anthropic utilisait le MCP Playwright ; pour une API Symfony,
curletbin/consolejouent ce rôle) et note chaque tranche contre des seuils durs.
La séparation entre générateur et évaluateur est la décision structurante, parce que les agents surévaluent leur propre travail. Demande à un modèle de relire ce qu'il vient d'écrire, il trouve que c'est bien. On ne corrige pas ce biais en demandant au modèle de s'en méfier : on place un second regard, indépendant, devant le premier. Avec Claude Code, les rôles deviennent des sous-agents dans .claude/agents/, et leur périmètre d'outils est une contrainte de conception : le planner ne touche pas au code, l'évaluateur ne peut pas modifier ce qu'il juge.
---
name: planner
description: Transforme une demande courte en spec de livrables, sans détail d'implémentation. À utiliser avant toute fonctionnalité de plus d'une demi-journée.
tools: Read, Grep, Glob
model: opus
maxTurns: 15
---
Tu es le planner. Entrée : une demande en une à quatre phrases.
Sortie : le contenu de docs/harness/spec.md, découpé en fonctionnalités ordonnées.
- Reste au niveau des livrables et du comportement observable : aucune
décision de classe, de service ou de schéma.
- Liste aussi les cas limites et les états d'erreur non cités.
- Chaque fonctionnalité : un identifiant, une phrase de comportement,
3 à 8 critères vérifiables sans lire le code.
- Lis CLAUDE.md et src/ pour ne pas contredire l'existant.Les champs de frontmatter sont ceux de la doc des sous-agents, où seuls name et description sont obligatoires. Le planner n'ayant pas Write, il renvoie le contenu de la spécification et c'est l'orchestrateur qui écrit le fichier : le plus simple et le plus sûr. Le générateur est en général la session Claude Code principale, avec une consigne claire : lire le journal de progression et l'historique git, proposer un contrat, implémenter, lancer bin/verify, committer, et ne jamais marquer une fonctionnalité comme terminée.
Qu'est-ce qu'un sprint contract et comment l'écrire ?
Un sprint contract est un accord écrit, avant de coder, entre générateur et évaluateur sur les critères vérifiables qui valident une tranche de travail. Dans le protocole d'Anthropic, le générateur propose ce qu'il va construire et comment le succès sera vérifié, l'évaluateur relit, et les deux itèrent jusqu'à l'accord. Le générateur ne peut plus redéfinir « fini » après coup, et l'évaluateur ne peut plus durcir ses critères en cours de route. Exemple pour un export CSV de factures sur un projet Symfony multi-tenant :
{
"feature": "F-07",
"title": "Export CSV des factures filtré par période",
"agreed_by_evaluator": false,
"scope": {
"in": ["GET /api/invoices/export.csv?from=&to=", "InvoiceExportVoter"],
"out": ["export PDF", "pagination du CSV"]
},
"criteria": [
{ "id": "C1", "behavior": "200 et text/csv pour un ROLE_ACCOUNTANT", "check": "curl authentifié", "blocking": true },
{ "id": "C2", "behavior": "403 pour un utilisateur d'un autre tenant, même avec un id valide", "check": "test fonctionnel et requête manuelle", "blocking": true },
{ "id": "C3", "behavior": "from > to renvoie 422 avec un message lisible, pas une 500", "check": "requête manuelle", "blocking": true },
{ "id": "C4", "behavior": "100 000 lignes en streaming, sous 128 Mo de mémoire", "check": "fixtures et mesure mémoire", "blocking": true },
{ "id": "C5", "behavior": "cellules commençant par = + - @ neutralisées", "check": "fixture piégée, inspection du CSV", "blocking": false }
],
"verify_command": "bin/verify",
"passes": false
}- Chaque critère est un comportement observable avec son moyen de vérification : « code propre » n'est pas un critère.
- Au moins un critère négatif (autre tenant, entrée invalide) : c'est là que les agents sont paresseux.
- Le format JSON est un choix : d'après Effective harnesses for long-running agents, le modèle réécrit moins volontiers un fichier structuré qu'un fichier Markdown.
- Le contrat est commité avant le code : il sert aussi de trace lors des simplifications futures.
Pourquoi l’évaluateur doit-il être sceptique, et comment le régler ?
Parce que Claude est un QA faible par défaut. Anthropic décrit un évaluateur qui trouvait de vrais problèmes, puis « talked itself into approving ». Un évaluateur n'est pas bon parce qu'il existe : il l'est parce qu'il est réglé. Son prompt impose l'exécution de chaque critère et des preuves, et son périmètre l'empêche de corriger ce qu'il juge :
---
name: evaluator
description: Évalue une fonctionnalité contre son contrat de sprint en exécutant l'application. Sceptique par défaut. Ne modifie jamais le code.
tools: Read, Grep, Glob, Bash
disallowedTools: Write, Edit
model: opus
maxTurns: 40
---
Tu es l'évaluateur. Tu n'as pas écrit ce code et tu n'es pas là pour le défendre.
1. Lis docs/harness/contract-<id>.json.
2. Exécute chaque critère (curl, bin/console, phpunit, fixtures). Lire le
diff ne suffit jamais : un critère non exécuté vaut FAIL.
3. Pour chaque critère, cite la commande lancée et la sortie observée.
4. Si tu constates un problème puis hésites, c'est un FAIL.
5. Fais au moins trois tentatives adverses hors contrat : autre tenant,
entrée vide, accès concurrent.
Réponse finale en JSON :
{"verdict": "PASS|FAIL", "criteria": [{"id": "", "status": "", "evidence": ""}], "unlisted_findings": []}Attention : disallowedTools retire les outils d'édition, mais l'évaluateur garde Bash et peut donc écrire via le shell. Pour un blocage réel, ajoute des règles permissions.deny. Le réglage se fait ensuite depuis les logs, comme le recommande Anthropic : relire les jugements de l'évaluateur, repérer ceux qui divergent du tien, et corriger son prompt. En pratique :
- Rejouer cinq à dix sprints en gardant le verdict et les preuves de chaque évaluation.
- Marquer à la main les faux PASS, les plus graves, et les faux FAIL.
- Pour chaque faux PASS, ajouter une règle générale (« un critère non exécuté vaut FAIL »), pas un correctif sur le cas.
- Recompter : les faux PASS doivent baisser sans que les faux FAIL explosent, sinon tu déplaces le biais au lieu de le corriger.
Votre équipe utilise Claude Code ?
Formation intra sur vos projets réels : de la demi-journée à 2 jours, 6 devs max.
C'est la même boucle que pour la revue de code IA et son REVIEW.md : un filtre imparfait, des logs qu'on lit, une règle qu'on corrige. Pour pondérer le jugement, une grille simple suffit : fonctionnel et sécurité éliminatoires (tous les critères bloquants passent, preuve à l'appui), puis cohérence avec les conventions du projet, robustesse hors contrat et maintenabilité notées sur cinq.
Le harness complet vaut-il son coût ?
Pas toujours. Les chiffres d'Anthropic, obtenus avec Opus 4.5 : agent seul, environ 20 minutes et 9 $, fonction principale cassée ; harness complet, environ 6 heures et 200 $, application jouable. Plus de vingt fois le coût, pour un résultat qualitativement différent. Avec le harness simplifié sous Opus 4.6, sur une autre application, environ 3 h 50 et 125 $. Ce sont des cas uniques, pas des moyennes transposables à ton projet ; l'ordre de grandeur de l'arbitrage, lui, l'est.
- Tâche de moins d'une demi-heure, périmètre clair, testable par
bin/verify: agent seul et Stop hook. - Plusieurs fonctionnalités couplées, spécification floue : planner et générateur.
- Fonctionnalité sensible (authentification, paiement, multi-tenant) : ajouter l'évaluateur et les contrats.
- Tâche que le modèle courant réussit déjà seul de façon fiable : ne rien ajouter.
La frontière entre ces cas bouge à chaque modèle : l'évaluateur ne vaut son coût que lorsque la tâche dépasse ce que le modèle fait seul de façon fiable. Elle se mesure avec la méthode de l'A/B sur le coût par tâche réussie, pas au coût par run.
Comment l’implémenter avec Claude Code ?
Trois niveaux, du plus simple au plus industrialisé. Au premier, la session principale joue le générateur et délègue au planner puis à l'évaluateur ; simple, mais tout transite par le contexte. Au deuxième, un script relance une session fraîche par fonctionnalité, l'état passant par des fichiers (liste de fonctionnalités en JSON, journal de progression, git) : c'est le pattern « une fonctionnalité par session » d'Anthropic, et c'est l'orchestrateur, pas le générateur, qui passe une fonctionnalité à passes: true sur verdict de l'évaluateur. Au troisième, un workflow dynamique porte la boucle : un script JavaScript exécuté en arrière-plan, dont Claude ne voit que le résultat final.
// .claude/workflows/plan-build-evaluate.js
export const meta = {
name: 'plan-build-evaluate',
description: 'Planner, générateur, évaluateur avec boucle de correction bornée',
}
const verdictSchema = {
type: 'object',
required: ['verdict', 'failures'],
properties: {
verdict: { type: 'string', enum: ['PASS', 'FAIL'] },
failures: { type: 'array', items: { type: 'string' } },
},
}
phase('Plan')
const plan = await agent(`Produis la spec de livrables pour : ${args.request}`, { label: 'planner' })
phase('Build + Evaluate')
let feedback = ''
for (let round = 1; round <= 3; round++) {
await agent(`Implémente selon cette spec :\n${plan}\n${feedback}`, { label: `generator-${round}` })
const v = await agent('Évalue le résultat contre le contrat, en exécutant chaque critère.', {
label: `evaluator-${round}`,
schema: verdictSchema,
})
if (v.verdict === 'PASS') return { rounds: round, verdict: v }
feedback = `Corrige ces échecs :\n- ${v.failures.join('\n- ')}`
}
return { rounds: 3, verdict: 'FAIL' }- Le script n'a accès ni au système de fichiers ni au shell : tout passe par les agents. Une option
schemasuragent()force une sortie JSON validée. Date.now()etMath.random()lèvent une erreur, pour qu'une reprise rejoue exactement les mêmes appels.- Seize agents concurrents par défaut, réglables avec
CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS(v2.1.269+), et mille agents au plus par run. - Un workflow n'accepte pas d'entrée utilisateur en cours de route : pour valider la spécification avant la construction, lance le plan et la construction comme deux workflows distincts.
Comment simplifier son harness à chaque nouveau modèle ?
C'est la partie la plus rentable et la moins pratiquée. Anthropic en donne deux exemples. Les remises à zéro de contexte étaient nécessaires avec Sonnet 4.5, qui manifestait une « context anxiety » : il bâclait sa fin de tâche quand il sentait sa fenêtre se remplir. Avec Opus 4.5, ce comportement a largement disparu et les remises à zéro ont pu être retirées. Puis, en passant à Opus 4.6, l'auteur a supprimé le découpage en sprints et ne fait plus tourner l'évaluateur qu'une fois en fin de run, en gardant planner et évaluateur. Le composant n'était pas une erreur : il était juste, pour ce modèle. Il est devenu un poids pour le suivant. Le protocole d'ablation :
- Inventorier chaque composant et écrire l'hypothèse qu'il encode (« le modèle ne sait pas finir proprement près de sa limite de contexte »), le modèle sur lequel elle a été validée et la date du dernier test, dans un
docs/harness/ASSUMPTIONS.mdversionné. - Figer un benchmark interne : les tâches représentatives, les critères de succès et les répétitions de l'A/B, puisqu'un seul run ne prouve rien.
- Retirer un seul composant à la fois, puis rejouer et comparer taux de réussite, coût par tâche réussie et durée.
- Décider : pas de régression crédible, le composant sort ; régression, il reste, avec une date de dernier test mise à jour. Un composant retiré peut revenir si le modèle suivant régresse.
Deux garde-fous. Commence par les composants les plus coûteux et les plus anciens (remises à zéro, découpage fin), jamais par l'évaluateur des fonctionnalités sensibles. Et méfie-toi d'un benchmark trop facile : si le modèle le réussit déjà à 100 % sans harness, il ne mesure plus rien, et un composant qui protège un risque de sécurité peut rester même quand le benchmark n'en voit pas la valeur. Le choix du modèle et le harness se rejouent ensemble : un nouveau modèle déplace à la fois la répartition des rôles entre Opus, Sonnet et Haiku et ce que le harness doit compenser.
Que retenir des quinze articles de la série ?
Les briques de la série se rangent dans un seul système. Le choix du modèle et de l'effort fixe ce que le harness doit compenser. Les leviers natifs, la mesure de la consommation et le comparatif des outils tiers disent ce que coûte le contexte, et l'A/B tranche ce qui vaut son prix. Le context engineering et le ménage de la configuration gardent un signal propre. L'auto mode, la sandbox, les hooks et les managed settings fixent ce que l'agent a le droit de faire. La vérification d'abord et la revue de code IA disent ce qui est fini. Les runners et la gateway donnent le périmètre d'exécution en entreprise. Le harness les assemble.
- Pour chaque composant de ton harness, sais-tu dire quelle faiblesse du modèle il compense ?
- As-tu commencé par l'agent seul, avec vérification, pour mesurer où il échoue ?
- Le générateur est-il privé du droit de décider de son propre « fini » ?
- Chaque fonctionnalité sensible a-t-elle un contrat avec au moins un critère négatif ?
- L'état passe-t-il par des fichiers et git plutôt que par le contexte, avec des boucles bornées ?
- À chaque nouveau modèle, relis-tu tes hypothèses et rejoues-tu une ablation à la fois ?
Un harness n'est pas un actif à faire grossir : c'est un échafaudage dont la taille reflète l'écart entre ton modèle et ta tâche, et cet écart se réduit à chaque génération. Il vit dans le dépôt, versionné, relu, avec un propriétaire, parce qu'un harness bricolé par chacun dans ses fichiers personnels donne des résultats incomparables et des garde-fous à trous. Le rôle d'un CTO n'est pas de poser ces briques une fois, mais de décider qui possède le harness, à quelle cadence on le rejoue contre chaque nouveau modèle, et qui a le droit d'en retirer une pièce. Construis peu, mesure tout, et retire dès que le modèle n'en a plus besoin.

Écrit par
Flavien Métivier
Expert PHP/Symfony indépendant depuis 2014, ancien CTO de Kartable et d'Extrabat. Plus de 80 projets menés, de l'audit à la migration.
Mon parcours