Le claude code harness est devenu le concept central du developpement agentique en 2026 : l'infrastructure qui entoure le model IA dans un coding agent. L'analyse du code source de Claude Code le confirme : 98,4 % de l'architecture est du harness, seulement 1,6 % de l'inference IA. Cette realite, valable pour Cursor, Codex et tout editor IA, definit une discipline : le harness engineering. Concevoir un agent harness solide (harness configuration robuste, harness environment securisee, harness benefits mesurables) est le skill fondamental de l'agentic coding en production. Les harness skills avances, les best practices du harness design et la capacite a build the working environment autour d'un model de natural language constituent la reference des reliable coding agents enterprise pour la community francophone.
Architecture et composants du harness Claude Code
Pourquoi 98,4 % de Claude Code est du harness (et 1,6 % de l'IA)
Le harness n'est pas un detail d'implementation. C'est le produit. Chaque coding agent (Claude Code, Cursor, Codex) doit traverser une harness mcp et une harness configuration fiables avant chaque action. Des feedback loops et des quality gates robustes sont la condition sine qua non des reliable coding agents en production. L'ingenierie harness for development, pas un model plus puissant, est ce qui fait la difference. Les error handling et automated evaluation du harness sont les debug failures de demain evites aujourd'hui.
La boucle agent immuable : send → check → tool → loop
Quel que soit le framework (Claude Code, Cursor, Codex ou un agent base sur LangGraph), tout agent repose sur une boucle invariante en quatre temps. C'est le pattern que toute la community des coding agents a converge a implementer dans son outil de coding prefere :
- Send : envoyer le message et les tools disponibles au LLM
- Check : verifier le
stop_reasonde la reponse du model - Tool : si
tool_use, executer le tool et ajouter le resultat dans le context - Loop : repeter jusqu'a la reponse finale du modele
Le role du harness est de gouverner chaque transition de cette boucle. Sans harness, l'agent s'execute sans contrainte et sans audit. Avec une harness configuration correcte, chaque action passe par des gates de qualite, des verifications de permission et des mecanismes d'observabilite. La spec du harness definit ce perimetre avant chaque task confiee a l'agent.
Harness vs prompt engineering : deux disciplines complementaires
Le harness et le prompt engineering operent sur des niveaux differents du stack. Un editor IA comme Cursor ou Claude Code necessite les deux, chacun sur un plan distinct :
| Dimension | Prompt engineering | Harness |
|---|---|---|
| Cible | Ce que le model dit | Ce que l'agent fait |
| Perimetre | Instructions, few-shots, context | Tool dispatch, permissions, hooks, memory |
| Effet | Qualite des reponses textuelles | Fiabilite en production |
| Enforcement | Advisory seulement | Blocage programmatique reel |
| Scope | Session unique | Architecture persistante |
LangChain l'a mesure : en changeant uniquement son harness, sans toucher au model de natural language, l'organisation a progresse de 52,8 % a 66,5 % sur Terminal Bench 2.0. Un gain de 13,7 points par la seule harness configuration. C'est le skill fondamental : le prompt engineering optimise les reponses du language model, l'ingenierie harness rend les coding agents industrialisables : la difference entre un prototype et un assistant de coding en production, qui gere ses read/write operations de facon fiable.
La fuite npm du 31 mars 2026 : ce que les 512 000 lignes revelent
Une seule ligne .npmignore manquante dans le package npm @anthropic-ai/claude-code v2.1.88 a expose le code source complet le 31 mars 2026. La community technique a decouvert un harness avec des rule files de permission, des spec files d'architecture, des readme internes et 44 feature flags caches.
Ce que la fuite a mis en lumiere depasse l'incident de securite. Elle a ouvert l'architecture de Claude Code a l'analyse publique et academique. Les fichiers exposes sont devenus un curriculum de reference pour tout developpeur souhaitant create et build un harness production-ready. Avec Claude Code a 2,5 milliards USD ARR, comprendre ce harness est devenu un enjeu strategique : les experts qui savent build the working environment autour d'un model obtiennent de meilleures performances (better reliability, better control) que ceux qui se contentent de prompts.
Memory : CLAUDE.md, la memoire persistante de l'agent
CLAUDE.md constitue la couche memory du harness. Ce fichier se charge a chaque ouverture de session et definit les conventions du projet, les instruction de travail et les contraintes metier que l'agent doit respecter. Sa limite est fondamentale : CLAUDE.md est une couche d'instruction advisory. Il oriente le reasoning du model : il ne le bloque pas. Pour un harness efficace, chaque instruction critique inscrite dans CLAUDE.md doit etre doublee d'une rule dans permissions.deny. Les claude code skills references dans ce fichier sont la reference disponible a chaque demarrage d'agent.
Tools : les 12 primitives d'action fondamentales
Le harness expose quatre familles de tool au model, que ce soit Claude Opus ou tout other LLM. C'est la taxonomie que Cursor, Codex et Claude Code partagent pour building des coding agents :
- File I/O : read/write access, modification et suppression de fichiers
- Shell execution : commandes bash, scripts, processus de build
- Network : appels HTTP, api externes, services tiers
- Browser : navigation, interactions UI, tests
Les quatre equipes qui ont analyse le harness de Claude Code ont converge sur environ 12 tool primitives. Cette convergence confirme que le jeu de tools est contraint par la nature des task de developpement, pas par les choix d'implementation. Pour run un agent en production, le tool dispatch est le vecteur d'action central du harness. C'est aussi son vecteur de risque principal. Au level equipe, each tool expose doit etre documente dans le repository de configuration harness partagee ainsi que all les scopes MCP integres dans un app de gouvernance centralisee.
Permissions : settings.json et les 7 modes d'autorisation
settings.json est le moteur de permission du harness. Il implemente 7 modes d'autorisation, evalues en deux temps : 64 tokens pour le fast-pass des actions sans ambiguite et 4 096 tokens pour le chemin de reasoning du model (Claude Opus sur la branche raisonnement complet). Les rule files s'appliquent dans l'ordre : allow → deny → ask. Cette harness configuration determine directement le niveau d'autonomie de l'agent. Sans regles permissions.deny explicites, le harness delegue toute decision au model. Les spec files de permission constituent la reference de securite du harness.
Hooks : PreToolUse / PostToolUse comme portes de qualite automatisees
Les hooks sont les gates programmatiques du harness. PreToolUse s'execute avant chaque dispatch de tool, PostToolUse s'execute apres. Un hook qui retourne exit code 2 bloque l'action. C'est cette capacite de blocage qui distingue les hooks d'une couche de logging. Each hook integre dans votre harness doit retourner exit code 2 pour all les actions bloquees. Les quality gates et les feedback loops du harness transitent par cette mecanique. Les automated evaluation de sorties d'agent et les audits de harness review s'implementent via ces hooks, integres directement into le cycle de developpement pour more de securite.
MCP Servers : l'extension de la surface d'outils
MCP (Model Context Protocol) est le standard d'extension du harness de Claude Code. Chaque mcp server ajoute une surface de tool a l'agent tout en isolant les credentials par serveur. Le harness mcp permet d'integrer des systemes metier (bases de donnees, api internes, outils tiers) sans exposer l'ensemble des credentials a l'agent. La granularite du scoping MCP est un levier critique de harness configuration : un mcp server avec write scopes trop larges devient un vecteur d'attaque direct. Cursor, Codex et Claude Code implementent tous une variante de ce standard dans leur outil IA.
Observability : compaction de contexte et reduction de 76 % des couts API
La couche observability du harness remplit deux fonctions. D'abord, les session logs : traces de chaque action de l'agent, base des harness review et de l'automated evaluation post-execution. Ensuite, la compaction de context window : un pipeline en 5 couches preserve les prompts caches. Resultat mesure : 76 % de reduction des couts api. All les coding agents modernes integrent ce pattern into leur architecture : la community a converge dessus en 2025-2026. (MBZUAI VILA-Lab, mai 2026)
Les erreurs critiques de harness engineering
Anti-pattern 1 : CLAUDE.md sans enforcement permissions.deny
L'erreur la plus repandue : rediger des instruction detaillees dans CLAUDE.md sans les faire respecter par permissions.deny dans settings.json. L'agent peut ignorer ces instruction, non par malice mais parce que le reasoning du model optimise selon le context disponible, pas selon un fichier de conventions sans enforcement. La reference des best practices : toute interdiction critique doit exister dans permissions.deny. CLAUDE.md documente l'intention. settings.json l'applique. Example : une instruction "ne jamais modifier les fichiers de production" sans permissions.deny correspondant et le model l'ignore.
Anti-pattern 2 : cles API en texte clair dans le repertoire agent
Stocker des cles api dans des fichiers .env accessibles depuis le repository de travail de l'agent cree un vecteur direct d'exfiltration. La harness environment doit isoler les credentials de la zone d'action de l'agent. La solution : credentials en mode 600 dans des chemins inaccessibles a l'agent ou gestion via un secret manager dedie. Toute api key dans le repository de l'agent est une api key que ce dernier peut lire et potentiellement exfiltrer via un tool network. Les readme de securite du harness documentent l'emplacement des credentials : c'est un work de securite essentiel pour chaque level d'equipe.
Anti-pattern 3 : hooks qui logguent sans jamais bloquer (exit code 2 manquant)
Un hook qui enregistre chaque action dans des logs mais ne retourne jamais exit code 2 donne une illusion de controle. Les debug failures s'accumulent dans les logs, les actions non souhaitees s'executent. Le harness review post-incident revele une observabilite parfaite et des degats reels. La regle est simple : si un hook ne peut pas bloquer, il ne protege pas. L'error handling efficace des task agent passe par la capacite de blocage programmatique, pas seulement par la traçabilite. Cela s'applique aussi bien a Cursor qu'a Claude Code ou Codex.
Anti-pattern 4 : MCP write scopes couples a des Bash allowlists trop larges
Combiner des mcp write scopes avec des Bash allowlists larges cree une surface d'attaque critique. L'agent dispose de droits d'ecriture sur des chemins non controles via les tools MCP ET via les commandes shell de l'outil de coding. Le harness mcp doit suivre le principe de moindre privilege : scopes d'ecriture limites aux chemins strictement necessaires, allowlists Bash circonscrites aux task metier identifiees. La combinaison MCP write + Bash large est le vecteur de corruption de filesystem le plus frequent en production, que votre coding agent prefere soit Claude Code, Cursor ou Codex.
Anti-pattern 5 : bypass mode sur les repos de production
Le bypass desactive les verifications du harness. Sur un dossier de developpement isole, son usage peut etre temporairement justifie pour les tests. Sur un repository de production, c'est une porte ouverte. Les harness engineering best practices sont claires : activer les protections completes avant tout deploiement. Le bypass est concu pour le developpement, pas pour les environnements live. Cette regle doit figurer dans le readme du projet, visible de tous les contributeurs, a la maniere des rule files qu'Anthropic lui-meme documente dans les spec files internes de Claude Code.
CVE reels dans la couche harness : CVE-2025-59536 et CVE-2026-21852
CVE-2025-59536 et CVE-2026-21852 documentent ce que l'analyse structurelle confirme : les vecteurs d'attaque sur les coding agents transitent par la couche harness, pas par le reasoning du model (Claude Opus ou autre). Les quality gates du harness sont la reference de defense : building une stack sans CVE connus necessite de mettre a jour le harness regulierement, quel que soit l'output du modele sous-jacent. La reference harness engineering : appliquer les patches avant de changer de modele.
| Anti-pattern | Probabilité | Gravité | Remédiation |
|---|---|---|---|
1. CLAUDE.md sans enforcement (permissions.deny manquant) | Très élevée | Élevée | Chaque règle CLAUDE.md critique doit avoir un permissions.deny dans settings.json |
2. Clés API en texte clair (.env dans le répertoire agent) | Très élevée | Critique | Credentials en mode 600 hors du répertoire agent ou secret manager dédié (Vault, AWS Secrets Manager) |
3. Hooks sans blocage (exit code 2 manquant) | Élevée | Élevée | Chaque hook de protection doit retourner exit code 2 pour bloquer l'action, pas seulement logger |
| 4. MCP write + Bash large | Élevée | Critique | Principe de moindre privilège : scoper les MCP write aux chemins strictement nécessaires + allowlists Bash limitées |
| 5. Bypass mode en production | Modérée | Critique | Bypass uniquement en dev isolé, jamais sur les repos de production |
| 6. CVE documentés (CVE-2025-59536, CVE-2026-21852) | Élevée | Critique | Mettre à jour le harness dès la publication des patches : les 2 CVE se trouvent dans la couche harness |
Source : MBZUAI VILA-Lab (mai 2026), Idun Group.
Configurer votre harness Claude Code en 3 niveaux
Niveau A, Harness approval-first : chaque action demande confirmation
Le pattern approval-first est le point d'entree recommande pour les repository sensibles et les contextes reglementes. Chaque tool dispatch declenche une confirmation humaine. La charge d'approbation est maximale, le risque est minimal. Ce harness convient aux projets en production active et aux bases de code partages entre equipes. La harness configuration approval-first impose une presence humaine sur chaque action de l'agent, ce qui en fait aussi un mecanisme de harness review continue. Cursor et Claude Code exposent tous deux ce pattern nativement dans leur outil de coding. Un spec file documente les task autorisees en autonomie vs celles qui demandent validation humaine.
Niveau B, Harness curated allow-list : seules les actions destructives demandent confirmation
Le pattern curated allow-list definit une liste blanche d'actions autorisees en autonomie : lectures de fichiers (read access), execution de tests, appels d'api en lecture seule. Les operations destructives declenchent une confirmation. Ce harness works well pour les PoC et le staging : les reliable coding agents en mode interactif travaillent better et plus vite. La liste doit etre dans le readme du repository pour que Cursor et Codex travaillent efficacement dans ce perimetre. Un assistant configure avec ce pattern gere les task courantes sans supervision continue.
Niveau C, Harness sandboxed full-auto : isolation complete pour les taches batch overnight
Le pattern sandboxed full-auto isole l'agent dans un container avec des droits reseau restreints et un filesystem bind-monte sur le seul dossier de travail autorise. La charge d'approbation est quasi nulle. Ce harness est concu pour les task batch longue duree : migrations de base de code, generation de suites de tests, refactoring a grande echelle, agentic coding autonome, pour les task batch type migration d'app, generation de tests inclus. La harness environment sandboxee garantit que l'agent ne peut pas atteindre les secrets ou les systemes hors du perimetre defini. Les spec files de sandbox documentent les limites d'execution de chaque task autonome.
Le cout reel du harness : donnees chiffrees Anthropic Labs (mars 2026)
Les harness benefits sont quantifies. Prithvi Rajasekaran d'Anthropic Labs a publie les couts reels de trois configurations sur des task de developpement frontend longue duree (mars 2026). La harness configuration V2 (compaction de context window, separation generator/evaluator) represente une reduction de 76 % des couts api par rapport a une session non optimisee.
| Niveau | Configuration | Durée | Coût / session | Économie |
|---|---|---|---|---|
| Sans harness | Agent solo, aucune optimisation (pas de compaction, pas de multi-agents, pas d'évaluateur) | 20 min (tâche courte) | 9 USD (référentiel de base) | réf. |
| Harness V1 | Multi-agents complet (générateur + évaluateur), sprint contracts, Playwright MCP, 3+ rounds QA | 6 h (tâche longue) | 200 USD (20× plus cher) | +1 800 % |
| Harness V2 | Harness optimisé avec compaction contexte, séparation generator/evaluator, -76 % coûts API | 3 h 50 (-36 % vs V1) | 124,70 USD (-37,7 % vs V1) | -38 % vs V1 |
Source : Anthropic Labs, Prithvi Rajasekaran (mars 2026). Clé de l'optimisation V2 : la compaction du context window (pipeline en 5 couches préservant les prompts cachés) réduit les coûts API de 76 % sur les sessions longue durée. L'évaluation séparée (no self-assessment) augmente la qualité des livrables sans multiplier les tokens.
Avec Claude Code a 2,5 milliards USD ARR, l'optimisation du harness n'est pas un luxe d'ingenierie. C'est une necessite operationnelle pour toute organisation qui deploie des coding agents a l'echelle, que vous utilisiez Claude Code, Cursor, Codex ou un outil IA custom.
Du harness individuel au control plane enterprise
Les limites structurelles du harness individuel a l'echelle d'une equipe
Un settings.json local ne se synchronise pas automatiquement entre membres de l'equipe. Chaque developpeur maintient sa propre harness configuration dans son propre repository local, sans coherence garantie. Les configurations proliferent sans vue d'ensemble : coding agents configures differemment, readme absents, politiques non alignees. La scalabilite du harness individuel atteint ses limites au level de l'equipe des que plusieurs agents operent en parallele, impactant les app metier. Il faut un niveau de gouvernance superieur pour que l'harness for development soit uniformement applique across l'organisation. C'est la que l'assistant IA devient un actif collectif.
Policy engine, kill switch et RBAC : les composants du control plane
La transition vers un control plane enterprise repose sur trois composants fondamentaux :
- Policy engine : moteur de rule files applique a tous les agent de l'entreprise, quelle que soit leur origine (LangGraph, N8N, Cursor, Agentforce, Claude Code)
- Kill switch : arret d'urgence d'un agent en production, declenche en quelques secondes
- RBAC : quatre roles (owner, admin, contributor, reader) qui gouvernent l'acces aux configurations harness des agents deployes
La trajectoire de maturité du harness individuel au control plane enterprise passe par quatre étapes :
- Harness individuel : configuration agent unique. Le développeur configure son agent Claude Code, Cursor ou Codex via
settings.jsonlocal.CLAUDE.mddéfinit les règles du projet. Les hooks et les MCP servers sont activés par le développeur. (settings.json,CLAUDE.md, MCP servers, hooks.) - Harness équipe : standardisation et partage des configurations. L'équipe partage un repository de configurations harness (spec files, rule files, README). Les
CLAUDE.mdsont versionés. Les hooks sont standardisés dans le repository du projet. Premiers spec files partagés. (Repository partagé, spec files, rule files, versioning.) - Harness plateforme : runtime centralisé multi-agents. Un runtime standardisé (Idun Engine, LangGraph) expose les agents en tant que services FastAPI. Observabilité unifiée (OpenTelemetry, Langfuse), memory persistence (PostgreSQL), guardrails centralisés. (Idun Engine, FastAPI, guardrails, observabilité.)
- Control plane enterprise : gouvernance cross-platform. Tous les agents de l'entreprise (Copilot, Agentforce, LangGraph, N8N, ServiceNow) sont gouvernés par un policy engine unifié. Kill switch, RBAC, financial attribution, reporting AI Act et conformité OWASP Agentic AI. (Policy engine, kill switch, RBAC, AI Act.)
Ces composants materialisent le harness a l'echelle enterprise. Ce que settings.json fait pour un developpeur dans son outil de coding prefere, le control plane le fait pour l'ensemble du parc d'agents de l'organisation.
Harness, AI Act et conformite OWASP Agentic AI 2025-2026
L'AI Act impose la mise en conformite des systemes IA a risque eleve, avec une echeance reportee a decembre 2027 pour l'annexe III. L'OWASP Agentic AI a publie son framework de reference en decembre 2025. Les deux exigent des traces auditables, une capacite de harness review documentee et des mecanismes de supervision humaine sur les autonomous ai systems. Un harness enterprise conforme necessite des logs d'execution immuables sur chaque output d'agent, des quality gates verifiables et un reporting automatise. La couche harness est le point d'instrumentation naturel de cette conformite : c'est la que les preuves sont generees. Pour building un systeme conforme, chaque instruction a l'agent doit etre traceable et auditable.
La convergence independante : 4 equipes, la meme architecture harness
MBZUAI VILA-Lab, Obvix Labs, l'equipe OpenAI Codex CLI et les projets open-source Aider/OpenClaw ont construit leurs coding agents independamment, chacun dans son propre repository et avec son propre outil IA. Resultat : quatre architectures quasi identiques a chaque level d'implementation : boucle d'appel model, ~12 tool primitives, pipelines de permission multi-etages. La conclusion des chercheurs est directe : "ce n'est pas une preference, c'est une contrainte imposee par le probleme lui-meme." (MBZUAI, mai 2026) Le harness design n'est pas un facteur de differenciation. La qualite de son implementation, elle, permet de build des coding agents better plus fiables, plus gouvernes et plus productifs en production.
Idun Group : de l'ingenierie harness a la plateforme agents IA enterprise
L'approche Idun : le harness d'abord, sans dépendance à un éditeur
Idun Group applique les principes de l'ingenierie harness aux agents metier qu'il developpe en aval de ses missions de conseil. L'approche harness-first garantit que chaque agent livre repose sur des standards ouverts, peut etre deploye sur les serveurs du client et lui appartient integralement, sans dependance a un editeur. Pour LVMH, Idun a concu et exploite une plateforme d'agents d'IA generative en production. La community des coding agents converge vers ce modele : harness skills ouverts, repository GitHub public, gouvernance auditable. Le sovereign by design n'est pas une posture : c'est une architecture. Pour un example concret : l'output d'un agent Idun est aussi auditable que celui d'un Claude Opus configure avec reasoning explicite dans son harness.
Idun Engine : transformer n'importe quel agent LangGraph ou ADK en service production-ready
Idun Engine est le runtime open-source qui permet de build n'importe quel agent LangGraph ou ADK en service FastAPI et app production-ready en quelques minutes. Il packagise les composants harness detailles dans cet article : api standardisee (AG-UI, CopilotKit), observabilite (OpenTelemetry, Langfuse, LangSmith), memory persistence (SQLite/PostgreSQL), guardrails (15+ validators, sub-10ms), controle mcp, dans une couche d'infrastructure reutilisable a chaque level de maturite agent. Le readme complet et les spec files sont disponibles dans le repository GitHub d'Idun pour les developpeurs et les equipes assistant IA.
pip install idun-agent-engineSource : github.com/Idun-Group/idun-agent-platform (GPL v3)
Du harness individuel a la gouvernance centralisee de vos agents
A l'echelle de l'entreprise, la logique du harness individuel se prolonge dans une plateforme de mise en production et de gouvernance d'agents. C'est le role de la plateforme open source Idun (GPL v3, code public et auditable) : on y branche un agent LangGraph ou ADK et elle materialise le harness a l'echelle, avec moteur de rule files, kill switch, RBAC et traces auditables pour le reporting AI Act. L'assistant IA de votre editor prefere devient un service gouverne, traçable et conforme.
