Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Pràctiques de treball amb agents

Aquest capítol baixa al nivell operatiu: git, sandboxing, revisió, testing, seguretat, debugging, documentació i un resum final del flux de treball recomanat.

Treballar amb agents en el dia a dia vol dir convertir tot el marc anterior en pràctica operativa. El que segueix és el nivell concret: com revisar, contenir i verificar la feina d’un agent sense perdre control del que arriba al repositori.

Quan l’agent actua sobre el projecte, la feina crítica no s’acaba quan genera una resposta. Cal decidir què revisar, què contenir i quines garanties automatitzar perquè el codi plausible no arribi al repositori sense entendre’l.

Git amb agents

Git es torna més important amb IA, no menys. Quan un agent escriu codi, git és com descobreixes què ha passat. Moltes eines ofereixen la seva pròpia visualització dels canvis — ressaltant línies modificades, mostrant diffs inline o permetent acceptar blocs individualment. Aquestes eines són útils durant la sessió, però git segueix sent la referència: és el registre permanent, independent de l’eina, i el que permet revertir, comparar i auditar els canvis un cop la sessió s’ha tancat.

  • Commit abans de delegar. Fes commit o stash de l’estat actual abans de donar una tasca a un agent. Això crea un punt de restauració net — si la sortida és dolenta, reverteixes i ja.
  • El diff és la teva revisió. Quan delegues a un agent CLI, no has vist el codi escrivint-se. El git diff és la teva primera oportunitat d’entendre què ha fet. No només què ha canviat, sinó: ha introduït dependències noves? Ha tocat fitxers que no hauria? La lògica aguanta en casos límit?
  • El rollback és rutinari. Amb agents, desfer canvis passa d’emergència a rutina. Cal dominar les comandes de rollback (reset, checkout, revert) i saber quan usar cadascuna.
  • Staging parcial. L’agent sovint encerta alguns blocs i falla en altres. git add -p permet acceptar o rebutjar cada bloc individualment.
  • Disciplina de branques. Els agents mai haurien de treballar directament sobre main. Branca de feature → agent → revisió del diff → pull request.
  • Compte amb les migracions. Les migracions de base de dades estan fora de la xarxa de seguretat del rollback. Un git reset reverteix codi, però si ja has executat una migració que elimina una columna, les dades ja han canviat. Llegeix el SQL complet abans d’executar qualsevol migració generada per IA.

Execució aïllada (sandboxing)

Aïllar l’entorn de desenvolupament és bona pràctica en qualsevol projecte — facilita l’onboarding, fa els builds reproduïbles i evita que el que funciona a la teva màquina falli a la del company. Amb agents, però, passa de bona pràctica a requisit: quan qui executa les comandes no ets tu, el cost de no tenir aïllament es multiplica.

Quan un agent pot executar comandes — instal·lar paquets, modificar fitxers, cridar APIs externes — el risc no és només que generi codi dolent, sinó que executi accions irreversibles al teu sistema. Un rm -rf mal calibrat, un git push --force sobre una branca compartida, o una comanda que consumeix crèdits d’una API de pagament no es desfan amb un git revert.

El sandboxing consisteix a donar a l’agent un entorn on pugui treballar lliurement però on els errors quedin continguts. L’objectiu no és impedir que l’agent actuï, sinó limitar el radi de l’explosió quan s’equivoca.

  • Contenidors o VMs efímeres. Executar l’agent dins un contenidor (Docker, devcontainer) o una VM dedicada. El sistema host queda intacte, i destruir l’entorn és tan barat com tornar-lo a crear.
  • Worktrees i branques aïllades. Per a canvis al codi, un git worktree dedicat permet que l’agent treballi sense contaminar la teva còpia de treball principal. Si el resultat és dolent, elimines el worktree.
  • Permisos mínims. Credencials de només lectura per defecte, tokens amb scope limitat, variables d’entorn sense secrets de producció. L’agent no necessita accés a producció per escriure una funció.
  • Llistes de comandes permeses. Moltes eines d’agent permeten configurar quines comandes s’executen automàticament i quines requereixen confirmació. Permet el que és reversible (ls, cat, tests); requereix confirmació explícita per a tot el que toca xarxa, fitxers fora del projecte o estat remot.
  • Xarxa restringida. Si l’agent no necessita Internet per a la tasca, desactiva-la. Això elimina d’una tacada l’exfiltració accidental de dades i la instal·lació de dependències no auditades.

El principi general darrere de tot això: res que afecti l’entorn global no s’hauria de tocar mai, sempre que sigui possible. Instal·lar paquets al sistema host, modificar la configuració global de git, escriure fora del directori del projecte, alterar variables d’entorn persistents — tot això hauria de passar dins del sandbox, no al teu sistema. Si l’agent necessita una dependència, l’instal·la al contenidor; si necessita una configuració, viu al projecte. L’entorn global del desenvolupador és sagrat per defecte.

Un projecte ben dissenyat aïlla el seu entorn des del primer dia — tot el que l’agent toca hauria de viure al repositori i estar sota control de git. Si alguna cosa va malament, git reset ho desfà.

Code review de codi generat per IA

El codi de la IA ja ha passat el filtre de “sembla correcte” — per defecte, ho sembla tot. La pregunta de revisió no és “sembla correcte?” sinó “he verificat independentment que és correcte?”

Què buscar

  • Quins errors no gestiona? La IA detecta les excepcions òbvies i ignora les subtils.
  • Què passa als límits? Errors off-by-one en bucles, llistes buides, valors nuls — els casos que fallen en producció.
  • Quines entrades no valida? La IA omet guards que són òbvies per a qui coneix el domini.
  • Ha afegit dependències? Paquets que poden estar abandonats, insegurs o innecessaris.
  • Ha tocat coses que no li has demanat? De vegades la IA refactoritza codi adjacent o renomena variables fora de l’abast de la tasca.
  • Segueix els patrons del projecte? La IA aplicarà per defecte el que és comú a les seves dades d’entrenament, que pot no coincidir amb les convencions del teu codi.
  • Ha resolt el problema correcte? De vegades la IA resol un problema relacionat en què és més confident, no el que li has plantejat.

Entén el que acceptes

No deleguis la revisió a la IA

No deleguis la revisió de codi generat per IA a una altra sessió de IA. Encara que una sessió nova no tingui el biaix de confirmar la seva pròpia sortida, comparteix els mateixos biaixos d’entrenament: si el model que ha generat el codi no ha vist un problema, el model que el revisa tampoc el veurà. La revisió és el moment on construeixes l’enteniment del codi que publiques — saltar-la és acumular deute cognitiu i erosionar l’ownership del codi de l’equip.

Coneixement i judici

La IA pot saber més que tu en un domini concret — sovint ho fa. Quan no domines una tecnologia, pots usar-la com a font d’aprenentatge: demanant explicacions, contrastant amb documentació, construint comprensió abans de publicar. El perill no és que en sàpiga més, sinó acceptar la seva sortida sense entendre-la.

El que aportes com a revisor no és només coneixement — és judici contextual: avaluar si una solució és excessiva per la teva escala, si confondria el pròxim desenvolupador, o si contradiu com el teu equip utilitza realment aquelles dades. Aquest judici ve d’entendre el projecte, l’equip i les restriccions del domini — coses que no són al codi i que la IA no pot inferir.

Documenta el raonament

Entendre no és suficient si l’enteniment se’n va amb tu. Amb codi escrit a mà, almenys l’autor va tenir un model mental — i sovint queda rastre en el commit o la PR. Amb codi generat per IA, aquest model mental pot no haver existit mai per a ningú més de l’equip. Quan acceptis una decisió no trivial, deixa’n constància: un comentari al codi, un missatge de commit explicatiu, una nota a la PR — qualsevol rastre val més que cap.

Limita la teva generació

Limita conscientment quant codi generes al que genuïnament pots revisar. Codi generat però no revisat no és un actiu — és un passiu esperant a ser descobert. Si no pots revisar tot el que generes, la resposta correcta és generar menys, no revisar menys.

La temptació és forta perquè la velocitat de generació crea una il·lusió de productivitat — en minuts tens centenars de línies que “funcionen”, i sembla un malbaratament no aprofitar-ho. Però la productivitat real es mesura en codi que entens i que pots mantenir, no en línies generades.

Algunes estratègies pràctiques:

  • Treballa en increments petits. Demana canvis fitxer per fitxer o funció per funció, no refactoritzacions massives. Un diff de 30 línies es revisa de debò; un de 300 es fa servir els ulls per sobre.
  • Reconeix els senyals d’alerta. Si acceptes diffs sense llegir-los, si fas “approve all” per inèrcia, o si no pots explicar què ha canviat l’últim commit — estàs generant més del que pots absorbir.

Testing amb IA

Quan la IA escriu tant la implementació com els tests, els tests tendeixen a confirmar el que la IA pensava que el codi havia de fer — no el que l’especificació requereix. Els tests passen no perquè el codi és correcte, sinó perquè comparteixen els mateixos punts cecs. Això s’anomena tests tautològics.

Com evitar-ho

  • Escriu els tests tu primer. Des de l’especificació, no de la implementació. Confirma que fallen — si ja passen, no validen res. Després demana a l’agent que implementi codi que els passi. Això és TDD amb agents.
  • Executa els tests al principi de cada sessió. Estableix una línia base verda i assenyala a l’agent que existeix una suite.
  • No confiïs només en la cobertura. La IA pot generar una suite amb 95% de cobertura sense testejar res significatiu. La cobertura indica quin codi s’ha executat, no si funciona bé. El testing de mutacions — introduir petits bugs deliberadament i comprovar si la suite els detecta — és un senyal molt més fort.

Seguretat

La IA copia patrons insegurs de les seves dades d’entrenament perquè són comuns, no perquè siguin correctes — queries construïdes per concatenació de strings, execució dinàmica de codi amb entrada d’usuari, algoritmes de hash obsolets, credencials hardcoded. El model no distingeix entre codi funcional i codi segur: ambdós “semblen correctes” al seu entrenament estadístic.

Això fa que el codi de seguretat generat per IA sigui especialment perillós: funciona, passa tests, i conté vulnerabilitats que només un ull entrenat detecta.

Com protegir-te

El principi general: qualsevol codi que toqui seguretat — autenticació, autorització, criptografia, validació d’entrada, accés a dades — necessita revisió humana explícita. La IA pot fer l’esborrany, però no pot avaluar si el resultat és segur perquè no distingeix entre un patró funcional i un patró segur.

Alguns exemples concrets del que cal vigilar:

  • Codi criptogràfic o d’autenticació: contrastar sempre amb una implementació de referència. Un hash MD5, un token sense expiració o un JWT sense validació de signatura són errors que el model genera amb total confiança.
  • Queries a bases de dades: verificar que usen consultes parametritzades, mai concatenació de strings. La concatenació és el patró per defecte en molts exemples d’entrenament i obre la porta a injeccions.
  • Dependències noves: escanejar-les contra bases de dades de vulnerabilitats. La IA afegeix paquets sense avaluar-ne el manteniment ni l’historial de seguretat.
  • Secrets al codi: executar un escàner de secrets a cada commit generat per IA. La IA no distingeix entre codi d’exemple amb credencials fictícies i codi de producció.
  • Privacitat i serveis al núvol: quan uses una eina IA connectada a un servei al núvol, tot el que li passes — codi, fitxers de context, fragments de dades — s’envia als servidors del proveïdor. Abans d’enviar res, considera si conté codi propietari, dades personals o informació confidencial. En entorns professionals amb NDA o dades sensibles, verifica la política de retenció del proveïdor i valora eines que s’executin localment.

Debugging amb IA

El debugging és on el teu enteniment del codi importa més. La IA pot ajudar-te a raonar sobre causes, però només pot treballar amb el que li dones — si la teva descripció del problema és vaga, la resposta serà igualment vaga o simplement amagarà el problema en lloc de resoldre’l. Només tu pots saber o intuir que el problema va més enllà del que passa dins d’una funció — potser la causa real s’ha transmès al llarg d’una pila de crides. Obtens el que dones.

Diagnostica abans de corregir

  • Descriu el símptoma, no la solució. En lloc de “arregla aquest error”, explica què observes, què esperaves, i què ja has descartat. Això força el model a raonar sobre causes, no a generar el fix més ràpid:
"Tinc un NullPointerException a UserService.getProfile().
El mètode rep un userId vàlid, la query retorna un Optional buit
quan l'usuari existeix a la DB. Ja he descartat que sigui un
problema de connexió. Quina podria ser la causa?"
  • Demana causes, no fixes. Si demanes una causa, l’has d’avaluar i decidir el fix tu — i en el procés entendràs el problema. Si demanes un fix directament, l’acceptaràs sense entendre’l.
  • Avalua abans d’actuar. Un cop la IA et proposa una causa, para. Té sentit amb el que saps del sistema? Explica tot el comportament que observes? El punt de control humà entre el diagnòstic i l’acció és el que separa un fix sòlid d’un pegat superficial.
  • No iteris a cegues. Quan un fix no funciona, la temptació és enganxar el nou error i demanar a la IA que ho torni a intentar. Això crea un bucle de correccions superficials sense entendre mai la causa real. Si el primer intent no ha funcionat, para i diagnostica per què abans de demanar un segon.

Documentació

La IA pot llegir el codi i descriure què fa — quins paràmetres rep, què retorna, com s’utilitza. Però no pot explicar per què existeix — quina decisió de disseny hi ha darrere, quina restricció del domini codifica, quin problema resolía que no és evident mirant el codi. Aquesta segona part és la documentació que realment importa, i només la pot escriure qui ha pres les decisions.

Què delegar i què escriure tu

  • Delega la mecànica. Signatures, tipus, exemples d’ús — la IA ho fa bé i és feina repetitiva que no requereix judici.
  • Escriu el “per què” tu. La justificació, les decisions de disseny, les restriccions de domini — si no les escrius tu, ningú ho farà, perquè la IA no les pot inferir del codi.
  • Revisa cada frase generada. La IA descriu el que veu al codi, no el que saps sobre el seu propòsit. Una frase de documentació incorrecta és pitjor que cap frase — enganya activament qui la llegeix.
  • La documentació que escrius avui és context per a la IA de demà. Les decisions de disseny, les restriccions de domini i els “per què” que documentes es poden carregar com a context en futures sessions — i fan que la IA generi codi més alineat amb el projecte.

Resum: flux de treball recomanat

Totes les tècniques anteriors es componen en una seqüència per defecte que val la pena interioritzar:

  1. Entén la tasca abans de demanar res. Si no pots explicar què vols canviar, la IA omplirà els buits per tu.
  2. Tria el mode adequat. Chat per entendre, Plan per concretar, Autònom només quan el patró i la verificació són clars.
  3. Dona context específic. Apunta a exemples existents, restriccions i contractes; evita prompts vagues.
  4. Genera en increments petits. Demana canvis revisables d’un cop, no blocs massius de codi.
  5. Revisa tu el diff. Comprova personalment que resol el problema correcte i que no toca res fora d’abast.
  6. Executa verificacions. Tests, linting, comprovacions manuals o el que correspongui al canvi.
  7. Explica el canvi amb les teves paraules abans d’acceptar-lo. Si no pots fer-ho, encara no l’entens prou bé.

A banda del cicle: quan un canvi inclou una decisió no òbvia — sobretot les que fas tu, que la IA no pot prendre ni documentar — deixa’n rastre en una nota, al commit o a la PR. Aquest rastre no només serveix l’equip — és context que la IA podrà carregar en sessions futures per no contradir o desfer decisions que ja s’han pres.

Last change: , commit: 213b9a6