Harness engineering
Comment on encadre des agents pour qu'ils écrivent du code qui tient.
Ironlane est écrit avec des agents. Un agent est un contributeur très rapide qui oublie tout entre deux sessions. Le dépôt se souvient pour lui.
Le harness est l’ensemble de ce qui encadre l’agent : où sont les règles, ce que les outils refusent, comment un changement se prouve, et ce qui n’arrive jamais sans une personne.
1. Où vivent les règles
Section intitulée « 1. Où vivent les règles »Une règle, un endroit. Une règle écrite deux fois finit par dire deux choses.
| Quoi | Où | À lire quand |
|---|---|---|
| Le projet, sa pile, comment le lancer | Le fichier de présentation | D’abord |
| Les contrôles au commit, les tests, les migrations | Le guide de contribution | Avant un commit |
| La base, les fonctions, les droits, la vitesse | Le document d’architecture | Avant de toucher au SQL |
| Les objets du métier | Les documents du modèle et du métier | Avant de toucher à un objet |
| Les écrans, composants, tableaux | Le document des écrans | Avant de toucher à un écran |
| Le texte courant d’une fonction SQL | Un fichier par fonction | À la place de chercher dans les migrations |
| Ce qu’un agent doit savoir en plus | Le fichier de consignes du projet | Chargé d’office |
On lit seulement la partie qui touche ce qu’on change. Seul le fichier de consignes est chargé d’office, et il reste court : il pointe, il ne recopie pas. Une décision remplace la ligne qu’elle contredit, au présent, sans date ni nom. Qui l’a prise et pourquoi vont dans le message de commit.
2. Ce que les outils refusent
Section intitulée « 2. Ce que les outils refusent »Ces règles n’ont pas besoin d’être retenues : les enfreindre fait échouer un contrôle.
- Un composant partagé (tableau, sélecteur, fenêtre, choix de fichier) ne se réécrit pas.
- Pas de style en ligne, pas de fichier de plus de sept cents lignes, pas de
confirmni d’alert. - Un geste cliquable est un bouton ou un lien, et se fait au clavier.
- Un commentaire ne porte ni date, ni nom de personne, ni pictogramme.
- Pas de bloc de dix lignes écrit deux fois. Pas de code mort.
- Une table sans règle d’accès, une fonction à droits élevés ouverte, un lien entre deux sociétés : refusés.
- Un écran qui lit plus que son budget est refusé.
- Une migration qui recopie une fonction existante est refusée.
Voir les tests et les contrôles pour la liste complète.
3. La boucle
Section intitulée « 3. La boucle »- Regarder. L’état du dépôt avant d’écrire : une autre session peut y travailler. Lire les lignes en base avant d’affirmer quoi que ce soit sur les données.
- Chercher l’existant. Un écran, un composant, une fonction qui fait déjà la même chose se reprend. Le compte rendu nomme ce qui a été réutilisé.
- Écrire la règle une fois, côté serveur. Un contrôle fait dans l’interface se refait côté serveur. Ce qu’un lecteur ne doit pas voir ne part pas du serveur.
- Changer la base par une migration, avant le code. Elle dit comment elle se défait.
- Prouver. Les contrôles ciblés de ce qui a changé, pas la suite complète.
- Faire relire. Les relecteurs passent sur la branche. Ce qu’ils relèveraient se corrige avant de demander à une personne.
- Commiter. Fichier par fichier, jamais en bloc. Le contenu mis en attente est relu : ni secret, ni fichier d’une autre session. Un commit fait une chose.
- Rendre compte. Ce qui est fait, ce qui a été vérifié et comment, ce qui ne l’a pas été, ce qui reste, la décision attendue.
4. Les relecteurs
Section intitulée « 4. Les relecteurs »Quatre lectures indépendantes de chaque changement avant sa mise en ligne :
- le code, lu comme un mainteneur qui découvre le dépôt ;
- la base : voyages, index, verrous de migration ;
- les écrans : la grammaire d’interface et les textes ;
- un second regard, avec un autre moteur d’intelligence artificielle, pour ne pas partager les mêmes angles morts.
Un relecteur lit le code, pas la conclusion de l’auteur. Il ne sait pas qui l’a écrit et n’écrit rien lui-même. Ses remarques reviennent à celui qui a écrit le code. Elles ne bloquent pas toutes : une faille de droits, une panne possible ou un risque pour les données arrête la mise en ligne, le reste se corrige ensuite.
5. Ce qui n’arrive jamais sans une personne
Section intitulée « 5. Ce qui n’arrive jamais sans une personne »Certaines actions demandent l’accord d’une personne à chaque fois, quel que soit le mode de travail de l’agent. Ce sont les actions rares : une demande trop fréquente cesse d’être lue.
- La mise en ligne.
- Un import réel de données.
- Une migration de la base de production.
- L’ajout d’un nouveau paquet.
- Une écriture à la main sur la production. Quand on la demande : dans une transaction, en montrant l’avant et l’après, sur la seule ligne visée.
- Un script qui verrouille la base partagée pendant que des gens s’en servent.
Et ce que l’agent ne fait jamais :
- envoyer un courriel à un client depuis un test ;
- purger des données : on archive, on ne supprime pas ;
- rapprocher deux fiches sur une simple vraisemblance : il ne lie que ce qu’il peut prouver. Une décision humaine est gardée dans une table, sur une clé stable, avec son motif, et survit au prochain import.
6. Les rôles
Section intitulée « 6. Les rôles »Avec plusieurs sessions en parallèle, le travail se partage par rôle.
| Rôle | Fait | Ne fait pas |
|---|---|---|
| Chef de projet | Répartit le travail, vérifie, lance les mises en ligne | Ne relaie pas de notes entre sessions |
| Chantier | Un gros sujet sur sa branche, testé sur un environnement d’essai | Ne touche pas la production |
| Domaine | Corrige sur la branche principale un sujet déjà en ligne | N’ouvre pas de branche pour un correctif |
| Relecteur | Lit un changement qu’il n’a pas écrit | Ne le corrige pas lui-même |
Chaque session travaille avec la personne qui la dirige. Elle ne rend compte à aucune autre session. Une étude, une session.
7. Les garde-fous du commit et de la mise en ligne
Section intitulée « 7. Les garde-fous du commit et de la mise en ligne »- Au commit, un crochet lance la mise en forme, l’analyse et la détection des doublons sur les fichiers touchés, et vérifie la forme du message :
type(domaine): ce que ça fait. - Les types se vérifient avant la mise en ligne et dans l’intégration continue, pas à chaque commit : plusieurs sessions partagent le même arbre de travail, et un fichier à moitié écrit par l’une ferait échouer l’autre.
- La mise en ligne est un script, pas un geste libre. Il passe la vérification, joue les migrations avant le code, pousse, puis vérifie que les adresses répondent. Il demande l’accord de la personne.
- Un correctif de sécurité (monter une bibliothèque dans sa version majeure actuelle pour une faille connue) est la seule exception : il part sans attendre l’accord, et n’a pas le droit de contenir autre chose.
8. Des compétences réutilisables
Section intitulée « 8. Des compétences réutilisables »Les gestes qui reviennent sont écrits une fois, sous forme de compétences que l’agent charge quand il en a besoin : écrire une migration sans coupure, tester un écran de bout en bout, relire une base, vérifier une session de travail. Une compétence est un texte court, versionné avec le code. Elle ne remplace pas les règles : elle dit comment les appliquer pour un geste précis.
9. Un agent peut en confier une partie à un autre
Section intitulée « 9. Un agent peut en confier une partie à un autre »Les tâches qui coûtent cher en lecture (audits, cartographies, rédaction de documents, tri de journaux) peuvent être confiées à un second moteur, dans une copie du dépôt à part, sans accès à la production, aux secrets ni à la branche principale. Le travail revient toujours relu et rejoué par l’agent qui l’a confié avant d’être repris. Les raisons sont concrètes : un second moteur a déjà remplacé des messages d’erreur précis par de simples codes, lu hors de son dossier et inventé une faute. Ce qui est purement mécanique (lancer des tests, mettre à jour un environnement) se fait mieux par un script que par un modèle.
10. La mémoire
Section intitulée « 10. La mémoire »Les décisions, les retours des utilisateurs, la grammaire d’interface et l’inventaire des erreurs que l’application gère vivent dans un dépôt privé distinct, que les agents consultent quand un sujet le demande. Elle n’est pas publiée : elle contient des retours de clients.
11. Une remarque sur les cadres de développement
Section intitulée « 11. Une remarque sur les cadres de développement »Le dépôt avertit l’agent d’une chose : les versions récentes de Next.js ont changé d’interfaces et de conventions depuis ce que le modèle a appris. Avant d’écrire, il lit la documentation livrée avec le paquet. Ce n’est pas une habitude : c’est une règle écrite en tête du dépôt.
12. La langue
Section intitulée « 12. La langue »L’interface est en français, écrite pour les gens qui s’en servent. Le code passera à l’anglais en une seule fois, par un script piloté par un glossaire, quand aucun chantier ne sera ouvert. D’ici là, tout ce qui ne touche pas au modèle de données s’écrit en anglais (format d’import, serveur MCP, guide), et le code qui lit des tables existantes garde leurs noms. Un code à moitié en anglais est pire que l’une ou l’autre langue.