Le secrétaire de Fernand

Guides et capteurs : cartographier ton attention pour la libérer

Guides et capteurs : cartographier ton attention pour la libérer

La grille de Birgitta Böckeler, guides et capteurs, calculés ou inférés, comme boussole pour décider où va l'attention d'un développeur qui travaille avec des agents, avec les exemples de phax.

9 min de lecture
Écouter l'article · 10:39
Lu par Phonon (Gradium), voix Augustin · CC BY-NC 4.0

Partie de la série : Attention is all we have · Voir toutes les parties

Précédemment dans cette série : Attention is all we have

Je ne lis pas le code que mes agents écrivent. Depuis des mois, le lire demande une attention que mon énergie ne me permet plus. Je donnais un plan à l'agent, il l'exécutait phase après phase, et je me retrouvais devant le résultat. Les tests passaient, et pourtant ça ne marchait pas. Je voyais l'erreur sans pouvoir aller la corriger : l'agent était mes seules mains. Je lui disais « corrige ça », il corrigeait, et une autre erreur surgissait ailleurs. Dans la liste des fichiers modifiés, je ne savais même pas pourquoi tel fichier avait été touché. Chaque erreur est donc devenue une question : qu'est-ce qui ferait que l'agent la corrige, et que ce genre d'erreur ne revienne plus ?

Ce qui m'a aidé à y répondre, c'est une grille. Elle est de Birgitta Böckeler, dans Harness engineering for coding agent users (martinfowler.com, avril 2026), et je m'en sers depuis comme d'une boussole. Elle parle du harness utilisateur : ce qu'on met autour de l'agent pour l'orienter et le vérifier, à distinguer du harness du fournisseur, la boucle et les outils dans lesquels tourne le modèle. Chaque pièce que j'ai ajoutée à phax y tient dans une case. phax est l'orchestrateur open source que je construis en public (sur GitHub) : il fait exécuter un plan par un agent, phase par phase, chacune dans son worktree, et ne commite une phase que si ses vérifications passent. La comparaison de phax avec les pratiques agentiques les recense une à une.

Un harness d'agent n'a que deux leviers : orienter avant, vérifier après

Quand l'agent dérive, le réflexe est d'écrire un meilleur prompt. C'est un levier parmi deux. Böckeler les appelle les guides et les capteurs (guides et sensors). Un guide anticipates the agent's behaviour and aims to steer it before it acts : il agit avant que l'agent écrive. Un capteur observes after the agent acts and helps it self-correct : il agit sur ce qui a été écrit.

Un plan est un guide. Un skill aussi, comme le CLAUDE.md ou le prompt de phase. Un gate qui lance pnpm typecheck est un capteur, comme une revue de code ou un test d'acceptation. Ce que j'appelle un gate, c'est une quality gate : les vérifications qu'un changement doit passer avant d'être commité.

Chaque levier est calculé ou inféré, et seul le calculé te rend ton attention

La deuxième dimension de la grille sépare ce qu'un programme décide de ce qu'un modèle juge. Un levier calculé (computational) est deterministic and fast, run by the CPU : il répond vrai ou faux, et il répond la même chose à chaque fois. Un levier inféré (inferential) passe par un modèle : un skill qu'il lit, une revue qu'il fait.

La grille de Böckeler

Deux dimensions. Un guide agit avant l'agent, un capteur après. Chacun est inféré, jugé par un modèle, ou calculé, décidé par un programme. Les guides inférés sont ce que l'agent lit, AGENTS.md, un skill, un plan, plus nets écrits dans les mots de la littérature ; les guides calculés sont des outils déterministes, un codemod, un serveur de langage. Les capteurs inférés sont une revue par un modèle ou une personne ; les capteurs calculés sont le type checker, le linter, les tests et les fitness functions. Chaque pratique fait passer un jugement vers le calcul, et le capteur calculé est l'optimum.

Inféréun modèle juge, ton attention suit
Calculéun programme décide, sans ton attention
Guidesavant que l'agent agisse
AGENTS.md · un skill · un plan, dans les mots de la littérature
vers le calcul
un codemod · un serveur de langage (LSP)
Capteursaprès que l'agent a agi
une revue par un modèle ou une personne
vers le calcul
l'optimumtype checker · linter · tests · fitness functions

Je l'ai apprise dans l'ordre le plus coûteux. Au début, je n'avais mis que de l'inférence. Des skills, des plans détaillés, des consignes d'architecture, en espérant que l'agent les suive. Prends une règle simple : le domaine n'importe pas l'infrastructure. Écrite dans un skill, l'agent la lit. Il la suit la plupart du temps. À la quarantième itération d'une phase difficile, avec un contexte saturé, il importe un client HTTP depuis le domaine parce que c'était le chemin le plus court vers un test vert. Rien ne le signale. La règle est toujours dans le skill, et je ne le découvre que quand quelque chose casse.

Le vocabulaire aide. Écrite dans les mots de la littérature, « architecture hexagonale : le domaine n'importe aucun adaptateur », la règle renvoie à des textes sur lesquels le modèle a été entraîné, et il la comprend mieux qu'une règle maison. Mieux comprise, elle n'est pas vérifiée pour autant.

La même règle peut vivre dans une autre case. Elle devient une commande, pnpm audit:architecture, qui vérifie les frontières entre les couches et échoue si le domaine touche l'infrastructure. On la met dans le profil de gate. Le tout premier phax.json du projet, le 12 mai 2026, la contenait déjà. Elle y côtoyait pnpm typecheck, pnpm lint et pnpm knip. Désormais, à chaque phase, phax lance la commande. Si elle échoue, la phase ne commite pas : l'échec retourne à la même session de l'agent, qui corrige dans la limite de son budget de tentatives.

Dans le gate, c'est le CPU qui la porte. Ensuite, j'ai verrouillé tout ce que le langage et les outils savaient vérifier : le type checker en mode strict, le linter, le formateur, la détection du code mort. Chaque règle passée d'un skill à un gate, c'est une famille d'erreurs qui ne revient plus.

Côté guides, la case calculée existe aussi : des outils déterministes qui orientent l'agent avant qu'il écrive, comme un codemod ou un serveur de langage. Le brief de phax, arrivé en octobre avec phax brief, s'en approche. Avant qu'une phase écrive, un fournisseur de brief calcule à partir du code les garanties qui couvrent les fichiers qu'elle va toucher, avec leur état, et le gate vérifiera ensuite les mêmes. Mais l'agent le lit comme un skill : son contenu est calculé, sa lecture reste celle d'un modèle.

Un capteur calculé ne vaut que ce qu'il vérifie : il faut le séparer de celui qui fait

Un gate vert dit que les commandes passent. Il ne dit pas que les commandes vérifient la bonne chose. Et un agent qui a le droit de modifier ses propres tests a un chemin très court vers le vert : modifier le test qui échoue.

Le premier garde-fou de phax, c'est la réconciliation du planifié et du fait. Depuis juin, phax compare les fichiers que chaque phase a vraiment changés avec ceux que son plan annonçait (le prévu et le fait). Prévu mais pas fait, fait mais pas prévu, supprimé, renommé : chaque écart est listé, et l'agent doit le justifier dans son rapport de fin de phase. Devant la liste des fichiers modifiés, je sais maintenant pourquoi chacun a été touché. Un test modifié se voit donc. Il n'est pas empêché pour autant.

Un capteur inféré coûte, et ne vaut que pour ce qu'aucun capteur calculé ne couvre

Restent les jugements qu'aucune commande ne sait porter. Le travail respecte-t-il l'intention du plan ? Le nommage est-il juste ? La solution est-elle la bonne ? Pour ceux-là, il faut un capteur inféré : un modèle qui relit.

phax en a deux. La revue de conformité, arrivée en juin avec phax review-compliance, lit le travail contre le plan et ne modifie rien. La revue de code headless, arrivée en octobre, tourne dans une session en lecture seule. Si la session a changé quoi que ce soit dans le worktree, phax remet les fichiers en place et refuse sa réponse. Les deux sont optionnelles par projet, et chacune prend son propre modèle et son propre effort.

Un capteur inféré coûte des tokens, du temps, et il peut se tromper. Si une revue par modèle passe son temps à signaler une erreur de format, c'est qu'un formateur manque dans le gate.

Le cran suivant, ce sont des capteurs écrits avant le code, que l'agent ne peut pas toucher

Ajouter des capteurs ne suffit pas. Un capteur calculé exécute un critère, et ce critère, quelqu'un l'a choisi. Je trouve donc utile de poser deux questions de plus à chaque capteur : quand il a été écrit, et qui peut le changer.

Les règles du type checker et du linter sont posées avant le code. Les tests unitaires s'écrivent pendant, et souvent les fitness functions aussi, au sens de Building Evolutionary Architectures (Ford, Parsons et Kua) : il faut que les choses soient en place pour pouvoir les écrire. Au moment où ils naissent, ils peuvent épouser le code au lieu de le juger. Un test d'acceptation, lui, est écrit avant par définition : c'est un contrat, et le code n'a pas pu l'influencer.

Depuis fin octobre, phax les écrit dans une phase à part : ce sont les tests d'acceptation, ce que la littérature appelle l'ATDD (acceptance test-driven development). Une phase écrit les tests qu'une phase suivante devra satisfaire. Ils sont jugés deux fois, par un fournisseur que tu configures : d'abord ils doivent échouer, puisque le code n'existe pas encore, puis ils doivent passer.

Reste qui peut le changer. Un capteur que l'agent peut réécrire ne juge plus le code : la commande reste déterministe, mais c'est l'agent qui décide de ce qui compte comme succès. C'est la loi de Goodhart appliquée au code : dès que l'agent peut toucher la mesure, la mesure devient ce qu'il optimise. Un test validé ne tient donc pour les phases suivantes que si elles ne peuvent pas le modifier. Il faut un verrou, et il doit couvrir aussi ce qui permet de contourner le test : la configuration du runner, les seuils, un skip. Il doit tenir hors de portée de l'agent, dans les permissions du harness ou un contrôle de la CI, jamais dans une consigne du prompt. Dans phax, ce sont les protected paths, arrivés fin octobre : une liste de fichiers qu'aucune phase d'un run ne peut modifier. Quand le fournisseur de l'agent sait refuser l'écriture, l'agent ne peut même pas la tenter ; sinon, la phase échoue et le changement n'est jamais commité. Le phax.json est lui-même protégé, pour qu'une phase ne puisse pas élargir sa propre frontière.

Le plan a aussi ses capteurs, avant qu'une ligne de code existe. phax plans lint, en septembre, refuse un plan mal formé avant qu'un run démarre : une phase qui modifie un fichier qu'aucune phase précédente ne crée, une autre qui crée un fichier qui existe déjà. Les bornes d'affectation, en octobre, permettent au propriétaire du dépôt de tenir certains fichiers à un modèle et à une plage d'effort. Une phase qui s'écarte de sa borne sans en donner la raison est refusée, par plans lint comme au démarrage du run, avant d'avoir coûté quoi que ce soit.

La grille de Böckeler, et le moment où un capteur est écrit

La même grille, son capteur calculé coupé selon le moment où il est écrit. Écrit avant le code, c'est un contrat que le code doit passer et qu'il n'a pas pu influencer : les règles du type checker et du linter, les tests d'acceptation ; c'est le plus fort. Écrit avec le code, il peut épouser le code au lieu de le juger : les tests unitaires, et souvent les fitness functions.

Inféréun modèle juge, ton attention suit
Calculéun programme décide, sans ton attention
Guidesavant que l'agent agisse
AGENTS.md · un skill · un plan, dans les mots de la littérature
vers le calcul
un codemod · un serveur de langage (LSP)
Capteursaprès que l'agent a agi
une revue par un modèle ou une personne
vers le calcul
l'optimumAvant le code · un contratrègles du type checker et du linter · tests d'acceptation
Avec le codetests unitaires · fitness functions, souvent

Le capteur le plus fort est celui qu'on contractualise avant d'écrire le code, et que l'agent ne peut pas toucher.

Quand les modèles progressent, les capteurs calculés restent et les guides deviennent un réglage

Une objection revient : les modèles s'améliorent, tout ce harness deviendra inutile. Anthropic le dit de son côté : every component in a harness encodes an assumption about what the model can't do on its own (Harness design for long-running application development). Leur propre harness a abandonné des morceaux à mesure que les modèles progressaient.

La grille dit lesquels. Un gate n'encode aucune hypothèse sur le modèle. Il encode ce que le changement doit passer. Un modèle meilleur le passe plus souvent, donc il coûte moins de tentatives. Et un modèle meilleur dans son travail est aussi meilleur pour tromper un capteur faible, ce qui est une raison de plus de garder le juge séparé de celui qui fait.

Les guides, eux, deviennent un réglage. Combien le plan détaille, quel modèle exécute chaque phase : ce sont des choix qui changent avec les modèles et leurs prix. Un plan très détaillé, écrit une fois par un modèle fort, peut laisser un modèle moins cher exécuter les phases. Un plan plus léger s'appuie davantage sur les gates et la boucle de correction.

Ton attention va à ce que le système ne prouve pas encore

La grille classe les pratiques. Décider ce que le système que tu produis doit tenir, et lesquels de ces jugements méritent d'être calculés, ça reste ton métier.

Une fois ces jugements posés, les capteurs calculés, le verrou du harness et la comparaison au plan les tiennent à ta place. Le diff, je ne le vois plus. Mon attention va au domaine, et à la découverte des pratiques qui feront passer dans une case calculée ce qui n'est pas encore prouvé.

La question à te poser, à chaque changement : qu'est-ce que je regarde encore, que le système pourrait prouver à ma place ?

Une remarque après lecture ?

Si vous souhaitez envoyer un mot au sujet de cet article, vous pouvez écrire ici. Je partage ici parce que le sujet m’intéresse et que je veux apprendre des autres. Merci pour vos retours, surtout lorsqu’ils sont formulés avec soin.

Écris-moiremy@lesecretairedefernand.co