La integració d'agents d'intel·ligència artificial en el flux de treball del desenvolupament de programari ha deixat de ser una curiositat experimental per convertir-se en una necessitat operativa. No obstant això, treballar amb un assistent de codi durant setmanes o mesos revela un patró inevitable: els mateixos errors es repeteixen, la comunicació es torna ambigua i la confiança en les respostes de l'agent s'erosiona sense una estructura clara. A Q2BSTUDIO, on portem anys desenvolupant aplicacions a mida per a clients de diversos sectors, hem observat que la clau no està en el model d'IA escollit, sinó en el protocol de col·laboració que s'estableix amb ell. Aquest article presenta un marc original —que anomenem la Doctrina del Contrapart— compost per set eixos que permeten mantenir la coherència tècnica, l'auditabilitat a llarg termini i l'eficiència real en projectes que involucren agents d'IA.
La doctrina no va néixer d'una planificació teòrica, sinó de la sedimentació de regles informals després d'innombrables fallades recurrents. Cada eix respon a un mode de fallada específic que vam identificar en sessions reals de desenvolupament amb Claude, Copilot o altres agents. El que aquí s'exposa no és una recepta tancada, sinó una convenció viva que qualsevol equip pot adoptar i adaptar. La idea central és simple: si no documentes com et relaciones amb el teu agent d'IA, acabes redescobrint la mateixa lliçó cada setmana.
Eix 1: Verificació material — Tota afirmació factual que provingui de l'agent ('compilació exitosa', 'prova superada', 'dada confirmada') ha d'anar acompanyada de l'evidència que la recolza en el mateix missatge. Sense evidència material, l'afirmació no té valor probatori. Això implica exigir la sortida en cru d'ordres, traces SQL, logs de compilació o respostes HTTP. A Q2BSTUDIO apliquem aquesta regla fins i tot en tasques d'IA que involucren dades sensibles: cada número que es reporta ha de poder rastrejar-se fins al seu origen. Un simple 'tot correcte' sense evidències és el germen d'un error que pot costar hores de depuració.
Eix 2: Adversarialitat bidireccional — Abans de tancar una decisió arquitectònica significativa (una migració de base de dades, un refactor de més de deu fitxers, un compromís regulador), s'invoca un agent desafiador que produeixi objeccions, proves empíriques i un nivell de confiança. L'agent principal ha de respondre a aquestes objeccions amb fets, no amb complaença. Si l'usuari empeny un canvi sense noves dades, mantenir la posició original és legítim. Aquesta pràctica evita el biaix de confirmació i assegura que les decisions es basin en evidència, no en persuasió.
Eix 3: Taxonomia de dades i font única — Qualsevol columna derivada que s'emmagatzemi ha de ser categoritzada en el commit que la crea com a viva (no s'emmagatzema, es crea una vista), instantània (congelada en un esdeveniment de negoci) o memòria cau (emmagatzemada amb un refrescador declarat). Sense categoria explícita, la migració és rebutjada. Les constants de negoci es centralitzen en un únic fitxer, i els invariants irrevocables es protegeixen a nivell de base de dades (CHECK, triggers), no només en TypeScript. Aquest eix és especialment rellevant en projectes que integren serveis al núvol com AWS o Azure, on la proliferació de dades derivades pot generar inconsistències difícils de rastrejar.
Eix 4: Disciplina de sessió — Abans d'iniciar qualsevol projecte de més de dos fitxers, es redacta un ADR (Architecture Decision Record) d'una pàgina que inclogui la decisió, alternatives descartades, conseqüències i referències. L'ADR s'escriu abans del primer commit, no després. A més, s'estableix un límit de tres projectes oberts en paral·lel i s'exigeix un escaneig complet de símbols abans de proposar noves abstraccions. Les recapitulacions es limiten a cinc línies; tot el que excedeixi es divideix en missatges separats. Aquesta disciplina evita la saturació cognitiva i manté l'agent enfocat en el context rellevant.
Eix 5: Causa arrel, no pedaç — Abans d'aplicar una correcció, s'ha d'identificar la causa arrel. El workaround només és legítim si es declara explícitament tant en el commit com en un fitxer de feedback o ADR. Està prohibit el pedaç silenciós. Quan una solució sembla massa simple per al símptoma observat, s'exigeix el pipeline complet d'entrada i sortida abans d'acceptar-la. Aquest principi també s'aplica a patrons: si es confirma un cas, s'ha de buscar el patró complet a la base de dades o el codi abans de corregir-lo. A Q2BSTUDIO, aquest eix es complementa amb pràctiques de ciberseguretat, on un pedaç mal fonamentat pot obrir vulnerabilitats.
Eix 6: Pedagogia implícita i transversalitat de negoci — En àrees on l'usuari està construint experiència (PostgreSQL, EXPLAIN, compliment fiscal, normatives), s'aplica la regla de tres: primera vegada es fa per l'usuari, segona es fa amb ell, tercera la fa ell. S'utilitza vocabulari de negoci regulat, no vocabulari de proveïdor. Qualsevol menció a una norma exigeix cita textual; sense cita, és màrqueting. La pràctica d'un proveïdor no és una restricció, s'ha de confrontar amb els ADR del projecte abans de tractar-la com a invariant. Aquest eix és crucial en projectes de BI/Power BI, on la terminologia financera o fiscal s'ha de manejar amb precisió.
Eix 7: Auditabilitat a llarg termini — Els ADR s'arxiven a docs/adr/NNNN-title.md. Les sessions significatives es registren en un log. L'índex de memòria es manté en 200 línies com a màxim, amb fitxers temàtics separats. Cada memòria de feedback vinculada a una deriva activa ha d'apuntar a una sonda que la confirmi. Sense sonda, la memòria es podreix. Es programa una auditoria trimestral on es llegeix l'índex línia per línia preguntant 'això encara és veritat?' La pròpia doctrina es versiona i audita com un ADR. Aquest eix estructura tots els altres i assegura que el coneixement no es perdi quan l'agent canviï o l'equip roti.
Implementar aquests set eixos no és qüestió d'un dia. Es recomana començar pels tres mínims: verificació material (el més barat i d'impacte immediat), causa arrel (el més protector) i auditabilitat a llarg termini (el que sosté la resta). Durant les primeres sessions, n'hi ha prou amb produir almenys un fitxer de feedback datat. En un mes, aquests fitxers es converteixen en la matèria primera d'una doctrina sedimentada. A Q2BSTUDIO, hem vist com equips que adopten aquest enfocament redueixen el temps de depuració en un 30% i milloren la consistència del codi en projectes que integren múltiples tecnologies, des de automatització de processos fins a intel·ligència artificial aplicada.
La Doctrina del Contrapart no és un dogma, sinó una convenció que es revisa contínuament. Cada eix pot desactivar-se durant un sprint si s'assumeix explícitament el cost. El dia que un eix deixi de servir, es retira; el dia que aparegui un nou mode de fallada recurrent, s'afegeix un vuitè. La disciplina de la coherència llarga no és un mètode per a la productivitat curta, sinó la condició perquè el codi generat amb IA preservi la seva integritat a mesura que el projecte creix. En un entorn on la velocitat de generació de codi es duplica cada trimestre, tenir un protocol de col·laboració sòlid marca la diferència entre un prototip funcional i un sistema mantenible.
