Fer el projecte més automatitzable
Aquest capítol descriu la infraestructura que fa més segura la delegació: decisions explícites, contractes, tests i una verificació automàtica prou fiable per sostenir més autonomia.
Que la delegació autònoma sigui segura per defecte no és qüestió d’encertar el prompt — és qüestió de com està dissenyat el projecte. Tres palanques són especialment rendibles:
- Decisions de disseny explícites — patrons, convencions i fronteres documentades que l’agent pot seguir sense haver d’inferir-les.
- Contractes i tipus — interfícies, tipus i esquemes d’API que descriuen el resultat esperat al codi, no al cap del desenvolupador.
- Tests i CI/CD — una suite que verifica cada canvi sense intervenció manual.
Totes tres només serveixen de xarxa de seguretat real si s’executen automàticament a cada canvi.
Decisions de disseny explícites
Un projecte on les decisions estructurals estan documentades — patrons, convencions, fronteres entre mòduls — satisfà la primera condició del mode autònom sense haver de repetir-les a cada prompt. ADRs, fitxers d’instruccions de projecte i exemples canònics al codi serveixen el doble propòsit: orienten nous desenvolupadors i donen context a la IA per mantenir la coherència. Les decisions ja estan preses i són accessibles — ni el desenvolupador ni l’agent han d’inferir-les de nou.
El fitxer d’instruccions del projecte hauria d’evolucionar per acumulació de fracassos, no per especulació. Cada línia que hi afegeixes hauria de traçar-se fins a un error concret que ha passat: l’agent va comentar tests, va tocar fitxers fora d’abast, va aplicar un patró que el projecte havia descartat. Quan això passa, no n’hi ha prou de corregir el canvi — cal afegir la regla perquè no es repeteixi. Però el criteri és simètric: no cal documentar el que l’agent ja fa bé per defecte. Afegir regles per comportaments que ja són el default no protegeix res — només infla el fitxer i dilueix les regles que sí que importen. Un fitxer d’instruccions útil és curt i específic: cada línia resol un problema real d’aquest projecte, no un problema hipotètic o genèric.
Un ADR útil per a l’agent no és una descripció del que es va decidir — és una descripció del que es va descartar i per què. “Usem repositoris en lloc de serveis d’aplicació” diu poc; “usem repositoris en lloc de serveis d’aplicació perquè el domini té lògica de consulta complexa que no volem dispersar” dona a l’agent el criteri per aplicar el patró en casos nous sense desviar-se als defaults que coneix. La mateixa lògica s’aplica al fitxer d’instruccions del projecte: no és un llistat de convencions, sinó un llistat de decisions que l’agent hauria de respectar i que no s’infereixen llegint el codi — les desviacions del framework, els patrons descartats, les restriccions de domini que no apareixen als tipus.
Contractes i tipus
Definir contractes formals — interfícies, tipus, esquemes d’API, fronteres entre mòduls — fa que el resultat esperat estigui descrit amb precisió al codi, no al cap del desenvolupador. Un tipus és una especificació executable; un esquema d’API es pot validar automàticament. Quan l’agent ha de generar codi que encaixi amb aquests contractes, els buits d’especificació queden reduïts mecànicament — no és qüestió de redactar prompts millors, sinó d’haver escrit els contractes al codi.
En la pràctica, la diferència entre un contracte útil i un que l’agent ignorarà és la distància entre la intenció i el codi:
- Una interfície amb mètodes ben nomenats i tipus precisos és un contracte; un mòdul sense interfície pública definida no ho és — l’agent omplirà els buits com li sembli.
- Un esquema d’API declarat amb OpenAPI o GraphQL és verificable automàticament; una API descrita en un README no ho és.
El criteri pràctic: si la violació del contracte produeix un error de compilació o de validació sense que ningú hagi de llegir el codi, el contracte existeix realment.
Tests i CI/CD
La verificació ha de ser simple i fiable. Això depèn de dues peces que es reforcen mútuament: una suite de tests sòlida i una CI/CD que l’executi automàticament a cada canvi.
Però aquestes inversions — documentació, contractes, tests — només es converteixen en una xarxa de seguretat real si s’executen automàticament a cada canvi. Un test que cal recordar de llançar manualment no protegeix res; un contracte que no es verifica a cada commit acaba desincronitzat. El mecanisme que tanca el cicle és la integració contínua (vegeu CI/CD): cada push dispara linters, type checkers, tests i escàners de seguretat, i cap canvi avança si alguna porta falla. Sense CI/CD, l’arnès existeix al repositori però no s’aplica; amb CI/CD, passa a ser la condició per defecte de tot el que es fusiona.
Com més d’aquesta estructura existeixi, més tasques passen de requerir mode Plan o Chat a ser segures en mode Autònom. Invertir en disseny clar, contractes explícits i tests no és només bona enginyeria — és el que converteix la IA d’una eina que cal supervisar constantment en un executor fiable.
Harness engineering
Decisions explícites, contractes i tests creen l’estructura. L’harness engineering és l’extensió natural d’aquesta idea: envoltar l’agent amb les verificacions que fan que l’estructura s’apliqui — i que evolucioni — automàticament.
Quan l’agent s’equivoca, la reacció instintiva és atribuir-ho al model — “aquesta IA no és prou bona per a això”. Però la majoria de fallades repetibles no són limitacions del model: són buits a la configuració. La idea d’envoltar l’agent amb un arnès automatitzat de verificació que atrapi aquests errors s’ha consolidat com a disciplina amb nom propi: harness engineering.
Linters estrictes, type checking, tests de contracte, escàners de seguretat — tot plegat forma un arnès que atrapa els tipus d’error que la revisió humana detecta però que no necessita jutjar. L’arnès no substitueix la revisió — l’allibera. Quan les portes automatitzades ja garanteixen que el codi compila, segueix els tipus, passa els tests i no conté vulnerabilitats conegudes, el revisor humà pot centrar tota l’atenció en el que les portes no poden avaluar: si la solució és la correcta, si l’abstracció aguantarà, si la decisió de disseny encaixa al sistema. Amb eines IA, la necessitat és més urgent: el volum de codi que un agent genera supera el que qualsevol revisor pot llegir línia a línia, de manera que l’arnès passa de ser un complement a la revisió a ser la porta principal de qualitat.
Un arnès pràctic no comença amb un agent — comença amb eines deterministes: linters, type checkers, tests automàtics i hooks de pre-commit. Són la base més fiable perquè no depenen del model: donada la mateixa entrada, produeixen sempre el mateix resultat. Les eines semàntiques — analitzadors d’AST, detectors de codi mort, validators de cobertura — afegeixen una capa que entén l’estructura del codi sense introduir probabilisme. Els agents entren quan cap de les capes anteriors pot cobrir el que cal verificar: consistència arquitectural, qualitat de documentació, convencions massa matisades per expressar-les com a regla determinista. El principi és el mateix que per a qualsevol delegació (vegeu Codi, eina o agent): prefereix determinista sobre probabilístic, i usa l’agent per al que l’script no pot fer.
L’arnès es construeix per acumulació: cada error que es repeteix és informació sobre on la configuració és incompleta. Quan l’agent comenta tests durant un refactoring, toca fitxers fora de l’abast definit, o aplica un patró que el projecte havia descartat — la resposta correcta no és acceptar-ho sinó tancar el forat: una regla nova al fitxer d’instruccions, un hook que ho bloquegi, un validador que ho detecti.
Però esperar que l’agent falli és un mode reactiu — hi ha erosions que no generen símptomes fins que el dany ja és fet:
- una convenció al fitxer d’instruccions que els últims deu PRs han deixat d’aplicar,
- un exemple canònic que referencia funcions que ja no existeixen,
- una restricció de domini que un refactoring ha invalidat sense que ningú actualitzés les instruccions.
Programar un agent per escanejar aquests desajustos periòdicament — setmanalment, o com a part del tancament d’sprint — converteix el manteniment de l’arnès en una rutina en lloc d’una descoberta tardana.
L’arnès no és només una pràctica individual — la seva qualitat reflecteix la cultura d’enginyeria de l’equip. La recerca més rigorosa sobre el tema (el report DORA 2025) és consistent: la IA amplifica el que l’equip ja és. Equips amb CI/CD sòlid, cultura de revisió i bona cobertura de tests canalitzen la velocitat de la IA en guanys reals. Equips sense aquestes bases simplement produeixen bugs més ràpid. L’arnès és la inversió organitzativa que determina de quin costat caus.
Un cop l’arnès és funcional, hi ha un pas que alguns equips estan explorant: tancar el bucle en l’altra direcció. En lloc de deixar que sigui el desenvolupador qui identifiqui sempre els forats, l’agent pot analitzar els propis resultats — tests que fallen repetidament, patrons d’error recurrents entre sessions — i generar recomanacions concretes: una regla nova al fitxer d’instruccions, un hook addicional, una guia que falta. El desenvolupador valida les propostes; per als canvis de menor risc, pot automatitzar-ne l’aprovació gradualment. El sistema passa d’un arnès que millora per acumulació de fracassos a un que s’auto-millora activament. No és el punt de partida — requereix un arnès ja operatiu i prou instrumentació per detectar patrons — però és la direcció natural un cop la base és sòlida.
Una manera de calibrar on és el teu projecte: imagina que l’agent fa un canvi incorrecte — viola un patró, trenca un contracte, introdueix una vulnerabilitat coneguda. Quantes d’aquestes coses el sistema les detectaria automàticament, sense que ningú hagués de llegir el codi? Cada resposta “caldria que algú ho veiés” és un forat a l’arnès — i un límit al que pots delegar amb seguretat. No cal omplir tots els forats abans de delegar, però sí tenir-los identificats.