# 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.

<figure class="schema"><svg viewBox="0 0 520 246" role="img" aria-label="Qui tient une règle : un outil, un texte ou une personne" xmlns="http://www.w3.org/2000/svg"><defs><marker id="f" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="8" markerHeight="8" orient="auto-start-reverse"><path d="M1 1.5L8.5 5L1 8.5z" class="mk"/></marker><filter id="o" x="-5%" y="-5%" width="110%" height="120%"><feDropShadow dx="0" dy="1.5" stdDeviation="2" flood-opacity=".14"/></filter></defs><g class="cc c-bleu"><rect x="10" y="10" width="162" height="190" rx="14" class="card" filter="url(#o)"/><path d="M10 24 a14 14 0 0 1 14 -14 H158 a14 14 0 0 1 14 14 V50 H10z" class="bar"/><text x="91" y="36" class="tw" text-anchor="middle">Un outil</text></g><text x="91" y="76" class="ts" text-anchor="middle">types, style, doublons</text><text x="91" y="106" class="ts" text-anchor="middle">droits de la base</text><text x="91" y="136" class="ts" text-anchor="middle">budget de lectures</text><text x="91" y="166" class="ts" text-anchor="middle">jamais d&#x27;essai en production</text><g class="cc c-vert"><rect x="181" y="10" width="162" height="190" rx="14" class="card" filter="url(#o)"/><path d="M181 24 a14 14 0 0 1 14 -14 H329 a14 14 0 0 1 14 14 V50 H181z" class="bar"/><text x="262" y="36" class="tw" text-anchor="middle">Un seul texte</text></g><text x="262" y="76" class="ts" text-anchor="middle">une règle, un endroit</text><text x="262" y="106" class="ts" text-anchor="middle">une décision remplace</text><text x="262" y="136" class="ts" text-anchor="middle">la ligne qu&#x27;elle contredit</text><g class="cc c-violet"><rect x="352" y="10" width="162" height="190" rx="14" class="card" filter="url(#o)"/><path d="M352 24 a14 14 0 0 1 14 -14 H500 a14 14 0 0 1 14 14 V50 H352z" class="bar"/><text x="433" y="36" class="tw" text-anchor="middle">Une personne</text></g><text x="433" y="76" class="ts" text-anchor="middle">la mise en ligne</text><text x="433" y="106" class="ts" text-anchor="middle">un import réel</text><text x="433" y="136" class="ts" text-anchor="middle">un nouveau paquet</text><text x="433" y="166" class="ts" text-anchor="middle">une écriture en production</text><text x="260" y="228" class="ts" text-anchor="middle">Si un outil peut tenir la règle, c&#x27;est l&#x27;outil. Sinon, elle est écrite à un seul endroit.</text></svg></figure>

## 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

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 `confirm` ni 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](/ingenierie/tests/) pour la liste complète.

## 3. La boucle

<figure class="schema"><svg viewBox="0 0 520 318" role="img" aria-label="La boucle de travail d&#x27;un agent en huit étapes" xmlns="http://www.w3.org/2000/svg"><defs><marker id="f" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="8" markerHeight="8" orient="auto-start-reverse"><path d="M1 1.5L8.5 5L1 8.5z" class="mk"/></marker><filter id="o" x="-5%" y="-5%" width="110%" height="120%"><feDropShadow dx="0" dy="1.5" stdDeviation="2" flood-opacity=".14"/></filter></defs><g class="cc c-gris"><rect x="10" y="10" width="240" height="56" rx="12" class="card" filter="url(#o)"/><path d="M22 10 H15 a5 5 0 0 0 -5 5 V61 a5 5 0 0 0 5 5 H22z" class="bar" transform="translate(0 0)"/><circle cx="37" cy="38.0" r="12" class="bad"/><text x="37" y="43.0" class="num" text-anchor="middle">1</text><text x="60" y="43.0" class="tt" text-anchor="start">Regarder</text></g><path d="M252 38 H266" class="ln" fill="none" marker-end="url(#f)"/><g class="cc c-gris"><rect x="270" y="10" width="240" height="56" rx="12" class="card" filter="url(#o)"/><path d="M282 10 H275 a5 5 0 0 0 -5 5 V61 a5 5 0 0 0 5 5 H282z" class="bar" transform="translate(0 0)"/><circle cx="297" cy="38.0" r="12" class="bad"/><text x="297" y="43.0" class="num" text-anchor="middle">2</text><text x="320" y="43.0" class="tt" text-anchor="start">Chercher l&#x27;existant</text></g><path d="M390 68 V76 H130 V84" class="ln" fill="none" marker-end="url(#f)"/><g class="cc c-bleu"><rect x="10" y="84" width="240" height="56" rx="12" class="card" filter="url(#o)"/><path d="M22 84 H15 a5 5 0 0 0 -5 5 V135 a5 5 0 0 0 5 5 H22z" class="bar" transform="translate(0 0)"/><circle cx="37" cy="112.0" r="12" class="bad"/><text x="37" y="117.0" class="num" text-anchor="middle">3</text><text x="60" y="117.0" class="tt" text-anchor="start">Écrire la règle une fois</text></g><path d="M252 112 H266" class="ln" fill="none" marker-end="url(#f)"/><g class="cc c-bleu"><rect x="270" y="84" width="240" height="56" rx="12" class="card" filter="url(#o)"/><path d="M282 84 H275 a5 5 0 0 0 -5 5 V135 a5 5 0 0 0 5 5 H282z" class="bar" transform="translate(0 0)"/><circle cx="297" cy="112.0" r="12" class="bad"/><text x="297" y="117.0" class="num" text-anchor="middle">4</text><text x="320" y="117.0" class="tt" text-anchor="start">Migrer avant le code</text></g><path d="M390 142 V150 H130 V158" class="ln" fill="none" marker-end="url(#f)"/><g class="cc c-ambre"><rect x="10" y="158" width="240" height="56" rx="12" class="card" filter="url(#o)"/><path d="M22 158 H15 a5 5 0 0 0 -5 5 V209 a5 5 0 0 0 5 5 H22z" class="bar" transform="translate(0 0)"/><circle cx="37" cy="186.0" r="12" class="bad"/><text x="37" y="191.0" class="num" text-anchor="middle">5</text><text x="60" y="191.0" class="tt" text-anchor="start">Prouver</text></g><path d="M252 186 H266" class="ln" fill="none" marker-end="url(#f)"/><g class="cc c-ambre"><rect x="270" y="158" width="240" height="56" rx="12" class="card" filter="url(#o)"/><path d="M282 158 H275 a5 5 0 0 0 -5 5 V209 a5 5 0 0 0 5 5 H282z" class="bar" transform="translate(0 0)"/><circle cx="297" cy="186.0" r="12" class="bad"/><text x="297" y="191.0" class="num" text-anchor="middle">6</text><text x="320" y="191.0" class="tt" text-anchor="start">Faire relire</text></g><path d="M390 216 V224 H130 V232" class="ln" fill="none" marker-end="url(#f)"/><g class="cc c-violet"><rect x="10" y="232" width="240" height="56" rx="12" class="card" filter="url(#o)"/><path d="M22 232 H15 a5 5 0 0 0 -5 5 V283 a5 5 0 0 0 5 5 H22z" class="bar" transform="translate(0 0)"/><circle cx="37" cy="260.0" r="12" class="bad"/><text x="37" y="265.0" class="num" text-anchor="middle">7</text><text x="60" y="265.0" class="tt" text-anchor="start">Commiter</text></g><path d="M252 260 H266" class="ln" fill="none" marker-end="url(#f)"/><g class="cc c-vert"><rect x="270" y="232" width="240" height="56" rx="12" class="card" filter="url(#o)"/><path d="M282 232 H275 a5 5 0 0 0 -5 5 V283 a5 5 0 0 0 5 5 H282z" class="bar" transform="translate(0 0)"/><circle cx="297" cy="260.0" r="12" class="bad"/><text x="297" y="265.0" class="num" text-anchor="middle">8</text><text x="320" y="265.0" class="tt" text-anchor="start">Rendre compte</text></g></svg></figure>

1. **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.
2. **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é.
3. **É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.
4. **Changer la base par une migration, avant le code.** Elle dit comment elle se défait.
5. **Prouver.** Les contrôles ciblés de ce qui a changé, pas la suite complète.
6. **Faire relire.** Les relecteurs passent sur la branche. Ce qu'ils relèveraient se corrige avant de demander à une personne.
7. **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.
8. **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

<figure class="schema"><svg viewBox="0 0 520 292" role="img" aria-label="Quatre lectures indépendantes, les remarques vont à l&#x27;auteur" xmlns="http://www.w3.org/2000/svg"><defs><marker id="f" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="8" markerHeight="8" orient="auto-start-reverse"><path d="M1 1.5L8.5 5L1 8.5z" class="mk"/></marker><filter id="o" x="-5%" y="-5%" width="110%" height="120%"><feDropShadow dx="0" dy="1.5" stdDeviation="2" flood-opacity=".14"/></filter></defs><g class="cc c-gris"><rect x="180" y="8" width="160" height="54" rx="12" class="card" filter="url(#o)"/><text x="260.0" y="32.0" class="tt" text-anchor="middle">Changement</text><text x="260.0" y="51.0" class="ts" text-anchor="middle">sur une branche</text></g><path d="M260 64 V80 H67 V98" class="ln" fill="none" marker-end="url(#f)"/><g class="cc c-bleu"><rect x="8" y="100" width="118" height="66" rx="12" class="card" filter="url(#o)"/><text x="67.0" y="130.0" class="tt" text-anchor="middle">Le code</text><text x="67.0" y="149.0" class="ts" text-anchor="middle">mainteneur</text></g><path d="M67 168 V190 H260 V208" class="ln" fill="none" marker-end="url(#f)"/><path d="M260 64 V80 H194 V98" class="ln" fill="none" marker-end="url(#f)"/><g class="cc c-ambre"><rect x="135" y="100" width="118" height="66" rx="12" class="card" filter="url(#o)"/><text x="194.0" y="130.0" class="tt" text-anchor="middle">La base</text><text x="194.0" y="149.0" class="ts" text-anchor="middle">voyages, verrous</text></g><path d="M194 168 V190 H260 V208" class="ln" fill="none" marker-end="url(#f)"/><path d="M260 64 V80 H321 V98" class="ln" fill="none" marker-end="url(#f)"/><g class="cc c-vert"><rect x="262" y="100" width="118" height="66" rx="12" class="card" filter="url(#o)"/><text x="321.0" y="130.0" class="tt" text-anchor="middle">Les écrans</text><text x="321.0" y="149.0" class="ts" text-anchor="middle">grammaire</text></g><path d="M321 168 V190 H260 V208" class="ln" fill="none" marker-end="url(#f)"/><path d="M260 64 V80 H448 V98" class="ln" fill="none" marker-end="url(#f)"/><g class="cc c-violet"><rect x="389" y="100" width="118" height="66" rx="12" class="card" filter="url(#o)"/><text x="448.0" y="130.0" class="tt" text-anchor="middle">Second regard</text><text x="448.0" y="149.0" class="ts" text-anchor="middle">autre moteur</text></g><path d="M448 168 V190 H260 V208" class="ln" fill="none" marker-end="url(#f)"/><g class="cc c-bleu plein"><rect x="110" y="210" width="300" height="62" rx="12" class="card" filter="url(#o)"/><path d="M122 210 H115 a5 5 0 0 0 -5 5 V267 a5 5 0 0 0 5 5 H122z" class="bar" transform="translate(0 0)"/><text x="134" y="238.0" class="tt" text-anchor="start">À celui qui a écrit</text><text x="134" y="257.0" class="ts" text-anchor="start">les remarques lui reviennent</text></g></svg></figure>

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

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

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

- **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

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

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

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

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

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.
