harness-books : deux livres sur la structure de contraintes des agents de code

Un corpus de lecture, pas une bibliothèque Python

Le dépôt est classé en Python, mais rien dans le README ne décrit du code à importer, une CLI ou une API. Ce qui est publié, ce sont deux livres : Harness Engineering: A Design Guide to Claude Code et The Harness Design Philosophies of Claude Code and Codex. Le README les présente comme des textes qui ne parcourent pas le code source ligne par ligne, et qui portent sur la manière dont un harness organise les contraintes et l'exécution. Le problème visé est donc documentaire : il n'existe pas de vocabulaire partagé pour parler de ce qui entoure un modèle de code une fois qu'il tourne dans un terminal, un dépôt, un système de permissions et des habitudes d'équipe. Le public est celui qui doit trancher sur l'architecture d'un agent, pas celui qui veut une dépendance de plus dans son requirements.txt.

La thèse : le problème n'est plus la qualité de la réponse

Le README énonce une position nette dans ses Core Claims. Une fois qu'un modèle de code entre dans un environnement d'ingénierie réel, le problème principal n'est plus la qualité de la réponse mais les conséquences comportementales. Et la formulation qui donne le ton : le vrai danger n'est pas qu'un modèle dise occasionnellement quelque chose de faux, mais que le système n'ait aucune structure pour traiter les conséquences. C'est un déplacement d'attention. La plupart des discussions sur les agents restent au niveau du prompt et du modèle. Ici, prompts, outils, permissions, état, reprise, vérification et institutions sont traités comme des organes d'une même structure de contrôle, pas comme des accessoires autour du système. On peut trouver la métaphore appuyée. Elle a le mérite de rendre explicite une conséquence pratique : si ces éléments sont des organes, on ne peut pas en ajouter un sans toucher aux autres.

Ce que chaque livre prend en charge

Le livre 1 prend Claude Code comme cible d'observation et se concentre sur la structure d'exécution. Ses chapitres suivent une progression : pourquoi le harness engineering n'est pas du prompt engineering à plus grande échelle, pourquoi le prompt appartient au plan de contrôle plutôt qu'à une boîte de dialogue, pourquoi les erreurs du modèle doivent être traitées comme la norme d'exécution et non comme un événement exceptionnel, pourquoi le travail multi-agents et la vérification ne doivent pas être fondus dans un mécanisme vague, et comment une équipe transforme une expérience individuelle en règles réutilisables. Le livre 2 place Claude Code et Codex côte à côte et demande où chacun place l'ordre. Le README décrit deux chemins : l'un part de la discipline d'exécution, l'autre d'une couche de contrôle plus structurée. La divergence centrale annoncée porte sur le plan de contrôle, et le livre aborde aussi l'alignement des rôles entre boucles de requête, threads, rollouts et état, ainsi que ce que permissions, bacs à sable et langages de politique font en matière de gouvernance.

Le squelette du livre 1, chapitre par chapitre

La table des matières complète du livre 1 est fournie, ce qui permet de juger la couverture avant d'ouvrir le premier fichier. Après une introduction et une préface intitulée Harness, Terminals, and Engineering Constraints, les chapitres s'enchaînent ainsi : chapitre 2, Prompt Is Not Personality, Prompt Is the Control Plane ; chapitre 3, Query Loop: The Heartbeat of an Agent System ; chapitre 4, Tools, Permissions, and Interrupts ; chapitre 5, Context Governance: Memory, CLAUDE.md, and Compact as a Budgeting Regime ; chapitre 6, Errors and Recovery ; chapitre 7, Multi-Agent Work and Verification ; chapitre 8, Team Adoption ; chapitre 9, Ten Principles of Harness Engineering. Trois annexes ferment le volume : des checklists présentées comme la transformation de principes en contraintes exécutables, des notes de diagrammes pour dessiner le squelette d'exécution, et une source map indiquant quels fichiers étayent chaque chapitre. Cette dernière annexe est l'élément le plus concret du dépôt : elle indique au lecteur où le texte s'ancre dans du code réel.

Comment y accéder, concrètement

Il n'y a pas de commande d'installation à exécuter. L'accès se fait par le site, avec une version anglaise à l'adresse harness-books.agentway.dev/en/. Chaque livre a sa page et son PDF exporté : book1-claude-code/exported/book1-claude-code-en.pdf et book2-comparing/exported/book2-comparing-en.pdf. Les sources Markdown sont dans le dépôt, sous book1-claude-code/locales/en/ pour le livre 1, avec des fichiers nommés chapter-01-why-harness-engineering.md jusqu'à chapter-09-ten-principles.md, plus preface.md, appendix-a-checklists.md, appendix-b-diagram-notes.md et appendix-c-source-map.md. Le chemin locales/en/ implique une structure de traduction par locale, et un README.zh-CN.md figure à la racine. Le README ne détaille pas les autres langues disponibles ni l'outil qui génère le site à partir de ces fichiers. Si vous voulez lire hors ligne, le PDF est la voie documentée ; si vous voulez suivre les renvois vers le code, ce sont les fichiers Markdown qu'il faut ouvrir.

Trois parcours de lecture annoncés

Le README propose trois entrées. Pour le cadre complet, livre 1 puis livre 2. Si vous connaissez déjà les outils d'agent de code et voulez directement la séparation architecturale, commencez par le livre 2. Si vous ne voulez que les conclusions, lisez le chapitre 9 du livre 1 et le chapitre 7 du livre 2. Ce dernier parcours mérite qu'on s'y arrête, parce qu'il révèle un choix éditorial : les principes et la comparaison finale sont isolés dans des chapitres dédiés, ce qui suppose que le reste est du développement. C'est pratique pour un lecteur pressé, mais cela signifie aussi que les chapitres 3 à 8 du livre 1 portent la charge de la démonstration. Un lecteur qui saute directement au chapitre 9 obtient des affirmations sans le raisonnement qui les produit, et le README ne prétend pas le contraire.

Ce que le dépôt ne fournit pas

La limite la plus visible est l'absence de licence dans le matériel fourni. Le champ est marqué inconnu, et rien dans le README ne l'indique. Pour un dépôt qui publie deux livres, ce n'est pas un détail : sans identifiant de licence, on ne sait pas ce qui est autorisé en matière de réutilisation, de traduction, d'extraction vers un support de formation interne ou de redistribution du PDF. Je ne peux pas trancher à votre place et ce n'est pas un avis juridique, mais le point doit être vérifié dans le dépôt avant tout usage autre que la lecture personnelle. Deuxième limite : le README annonce une comparaison Claude Code contre Codex, mais ne donne aucun détail sur la méthode. Les deux systèmes évoluent vite, et un texte comparatif qui n'expose pas sa date d'observation ni sa version de référence vieillit sans prévenir. Le dépôt a reçu une poussée en avril 2026 et ne liste aucune release, donc aucun versionnement du contenu. Enfin, si vous cherchez un harness à réutiliser, ce dépôt est le mauvais outil : il explique comment en concevoir un, il n'en fournit pas.

Face à quoi d'autre lire ceci

Le concurrent naturel n'est pas un autre dépôt mais la documentation officielle des outils concernés. La différence d'approche est réelle : la documentation de Claude Code ou de Codex décrit ce que fait chaque fonctionnalité et comment la configurer, alors que ces livres partent des conséquences et remontent vers les mécanismes. Un exemple tient dans le chapitre 5 du livre 1, qui traite CLAUDE.md et le compact comme un régime budgétaire. La documentation vous dira ce qu'est CLAUDE.md et où le placer ; le livre en fait un problème d'allocation de contexte avec des arbitrages. Inversement, la documentation officielle est à jour par construction, alors qu'un livre comparatif fige une observation. Un troisième terme de comparaison, plus proche : les articles de blog d'ingénierie qui racontent l'adoption d'un agent dans une équipe. Ils apportent des récits situés, ce que ces livres ne font pas, mais ils restent anecdotiques là où le livre 1 tente explicitement de transformer l'expérience individuelle en institution réutilisable. Le bon usage est de lire les deux côte à côte, pas de choisir.

Conclusion éditoriale

Adoptez ces livres si vous concevez ou arbitrez un harness d'agent de code et voulez un cadre de vocabulaire avant d'écrire du code : commencez par le chapitre 9 du livre 1 et le chapitre 7 du livre 2, qui donnent les conclusions sans le développement. Passez votre chemin si vous cherchez du code exécutable, un SDK ou des mesures de performance : le dépôt ne contient ni l'un ni l'autre. Avant de vous engager, vérifiez deux points précis dans le dépôt : la licence, absente du matériel fourni, et l'état des traductions sous book1-claude-code/locales/, puisque la structure du README suggère plusieurs langues mais que seule la version anglaise est documentée ici.

Sources officielles

1. Issues
2. Project website
3. README
4. wquguru/harness-books on GitHub