Harness engineering: governar el codi que escriuen els agents
Quan el codi el genera una màquina, el que importa no és el codi sinó les restriccions que l'envolten. El marc Context–Restricció–Convergència, explicat.
·8 min de lectura
El febrer de 2026 OpenAI va publicar que tres enginyers havien construït un producte d’un milió de línies sense escriure’n cap a mà. La xifra és cridanera, però no és la part interessant. La part interessant és el que van descobrir pel camí: els agents repliquen els patrons que ja hi ha al repositori, incloent-hi els dolents. I si ningú ho impedeix, el projecte deriva.
La resposta que van muntar té nom: harness engineering. Un harness —el mot anglès és el d’un arnès o un guarniment: el que subjecta i condueix— és el conjunt de regles verificables per màquina que decideixen quines estructures de codi són admissibles al teu projecte, siguin qui siguin les mans que l’escriuen.
Fa poc, en Jiun Kim ha publicat el primer intent seriós de posar-hi vocabulari: Harness Engineering: A Governance Framework for AI-Driven Software Engineering. Aquest article és la meva lectura, amb la part pràctica al davant.
El problema no és la qualitat, és la variància
La generació de codi amb models de llenguatge ha canviat una cosa concreta: la producció ha passat a ser probabilística. La mateixa instrucció, el mateix model, el mateix dia, pot donar sortides estructuralment diferents. On abans hi havia un desenvolupador amb els seus vicis —previsibles, corregibles a la revisió—, ara hi ha quatre agents amb vicis diferents cada vegada.
Als de Toss, una de les fintech més grans de Corea, ho van resumir sense embuts: «amb el mateix model i el mateix editor, la variància de la sortida és extrema».
El resultat té nom des dels anys noranta: erosió arquitectònica. La diferència és la velocitat. Abans l’erosió trigava anys i la revisió de codi la contenia. Ara un agent en genera prou en una tarda com per superar la capacitat d’atenció de qui hauria de revisar-ho.
Per què les instruccions no n’hi ha prou
La reacció natural és escriure-ho tot a un AGENTS.md o un CLAUDE.md. És el primer que fa tothom, i és el primer que falla. Torno a OpenAI: «vam provar l’enfocament de l’AGENTS.md únic i gros. Va fallar de maneres previsibles… massa guia esdevé cap guia».
El motiu és estructural. Les instruccions augmenten la probabilitat de compliment; no la garanteixen. I hi ha tres estratègies habituals que comparteixen el defecte:
| Estratègia | Què fa | Per què no tanca el problema |
|---|---|---|
| Enginyeria d’instruccions | AGENTS.md, CLAUDE.md, .cursorrules |
Probabilística: el model pot fer-ne cas o no |
| Revisió humana línia a línia | Una persona llegeix la sortida | El cabal de l’agent supera l’atenció disponible |
| Ajust fi del model | Entrenar amb el corpus del projecte | Cost alt, i es depreca a cada versió nova |
Cap de les tres dona una resposta binària. Un linter, sí.
Les tres dimensions
El marc del document organitza la pràctica en tres eixos. No són fases: és un bucle.
┌──────────────────────────────────────────┐
│ │
▼ │
┌─────────┐ ┌────────────┐ ┌──────────┴───────┐
│ CONTEXT │─────▶│ RESTRICCIÓ │─────▶│ CONVERGÈNCIA │
│ informa │ │ governa │ │ avalua │
└─────────┘ └────────────┘ └──────────────────┘
què sap què pot produir ha convergit?
l'agent l'agent O(P²) = O(P)| Dimensió | La pregunta | Si falta |
|---|---|---|
| Context | Què sap l’agent? | Errors factuals i errors de criteri |
| Restricció | Què li deixem produir? | Variància estructural sense límit |
| Convergència | Ja ha convergit la sortida? | Cap criteri per saber quan pares |
Context: el que informa
És el coneixement que arriba a l’agent, i té dues capes que fallen diferent. El coneixement declaratiu són fets: quins mòduls existeixen, quin esquema té la base de dades, quina és l’API. Sense això, l’agent genera codi plausible però fals: importa un mòdul inexistent o crida un endpoint que vas treure fa mesos. El coneixement procedimental són criteris de decisió: com es nomenen les coses, en quina direcció poden anar les dependències, quin patró es fa servir quan. Sense això, l’agent escriu codi correcte al lloc equivocat.
Ho desenvolupo a Context per a agents.
Restricció: el que governa
Són les regles que limiten la sortida, i es reparteixen en dues capes segons quan actuen. La guia actua abans: fitxers d’instruccions, prompts de sistema, exemples. La imposició actua després: linters, comprovador de tipus, formatadors, portes de CI, correccions automàtiques.
La diferència operativa és senzilla: la guia és prescriptiva però no verificable; la imposició és prescriptiva i verificable. Una regla de linter passa o no passa, i li és igual si el codi el va escriure una persona o un agent. Això té un corol·lari fort: quan la imposició és prou completa, la identitat de qui escriu el codi deixa de ser rellevant per al resultat estructural.
Ho desenvolupo a El linter com a governança arquitectònica.
Convergència: el que avalua
Cap harness neix complet. Es construeix per capes, i cada capa fa visibles problemes que la capa anterior amagava. La pregunta interessant és quan pots parar, i el document proposa un criteri concret: la idempotència estructural. El harness ha convergit quan tornar a aplicar-lo no canvia res.
Ho desenvolupo a Idempotència estructural.
Tothom hi ha arribat pel seu compte
El que fa creïble el marc no és l’elegància: és que sis fonts independents descriuen el mateix animal amb noms diferents.
| Qui | Context | Restricció | Convergència |
|---|---|---|---|
| OpenAI | docs/ curat |
Linters propis amb «principis d’or» | Agents de neteja recurrents |
| Toss | Convencions d’equip | Mercat de connectors instal·lables | Desplegament per equips |
| Shoemaker | Especificacions | 35+ skills i verificació en capes | Iteració buscant forats |
| Hashimoto | AGENTS.md |
Eines programades, no consells | Sis passos d’adopció |
| Zakas (ESLint) | Documentació d’arquitectura | El linter com a porta de governança | Evolució de l’eina |
| Thoughtworks | Enginyeria de context | Temps d’execució restringit | «Recollida d’escombraries» |
El cas d’en Mitchell Hashimoto és el que més m’agrada. És el creador de Terraform, l’eina la garantia central de la qual és que apliquis la configuració les vegades que vulguis i l’estat convergeixi sempre al mateix. Vint anys després, sense buscar-ho, ha arribat al mateix principi un nivell d’abstracció més avall: les regles del harness, s’introdueixin quan s’introdueixin, han de convergir el codi a una forma canònica. Quan la mateixa persona redescobreix el mateix principi en dos dominis diferents, val la pena parar atenció.
Com començar sense muntar un departament
Sense pressa i per ordre d’impacte:
- Escriu el context que ja tens al cap. Els tres o quatre criteris que repeteixes a cada conversa amb l’agent. Curt. Si passa de dues pantalles, ja has tornat a l’AGENTS.md gros.
- Converteix la primera regla en linter. La que més vegades has hagut de corregir a mà. Una sola. Com a avís primer, com a error quan ja no salti.
- Posa-la a CI. Una regla que no bloqueja és una recomanació.
- Executa el pipeline dues vegades seguides i mira si la segona passada canvia alguna cosa. Si en canvia, tens regles que es trepitgen.
- Cada cop que corregeixis l’agent a mà, pregunta’t quin forat del harness ho ha permès. Aquesta és tota la disciplina. La resta és conseqüència.
El pas 5 és el que separa el harness d’una col·lecció de regles. En Ben Shoemaker ho diu millor que jo: quan llegeix codi generat, «generalment miro d’esbrinar quin és el forat del harness perquè no hagi de tornar a tractar aquest problema mai més».
Què hi guanyes i què hi perds
A favor. La qualitat estructural passa a ser una propietat del projecte, no de qui hi treballa aquell dia. Les respostes són binàries i auditables: la porta de CI passa o no. I l’esforç de revisió es concentra on realment cal criteri humà.
En contra, i és real. Tota restricció canvia flexibilitat per consistència, i com més complet és el harness, més excepcions demana: cada excepció és manteniment. Escriure regles de linter pròpies no és gratis ni immediat. I el límit important: la convergència estructural no garanteix res del comportament. Dues implementacions idèntiques d’estructura poden tenir errors diferents. El harness no et diu si el codi fa el que ha de fer.
Per això la conclusió del document em sembla la frase justa: el harness no substitueix el criteri humà, l’allibera perquè es dediqui a la semàntica, al disseny i a la intenció —els llocs on la variància no només es tolera, sinó que es vol.
El que t’has d’endur
- Amb codi generat, les restriccions al voltant del codi valen més que el codi.
- Els fitxers d’instruccions són probabilístics; les portes de CI, deterministes. Necessites totes dues, i saber quina és quina.
- Un harness es construeix per capes, i el criteri per saber que ja hi ets és que tornar-lo a aplicar no canviï res.
- Comença per una regla, no per un marc.
Si tot això et sona al que ja fa una especificació ben escrita, és perquè és la mateixa idea per l’altra banda: l’especificació diu què s’ha de construir, el harness impedeix que es construeixi de qualsevol manera. Cap de les dues es fia de la memòria de ningú.