Code review amb IA: manen les instruccions, no l'eina

El 2024, GitHub va documentar públicament el que molts equips ja sospitaven: pujar de versió el model darrere de Copilot Code Review no disparava la qualitat dels comentaris de revisió al mateix ritme que millorava l'escriptura de codi. L'empresa va introduir les instruccions personalitzades de repositori, un fitxer `.github/copilot-instructions.md` on l'equip descriu convencions, arquitectura i prioritats de revisió en llenguatge natural. El que va canviar la percepció d'utilitat no va ser el salt d'un model a un altre, sinó aquell fitxer de context que l'equip trigava una tarda a escriure. Hem vist el mateix patró en clients que van provar primer Copilot i després altres eines: la sensació de 'això no entén el nostre codi' es repeteix amb qualsevol proveïdor si ningú li explica les regles del joc. El problema mai va ser quina IA, era què sabia aquella IA sobre l'equip.

Aquesta dada de productivitat en escriure codi no és el mateix problema que revisar codi aliè. Generar una funció nova és una tasca amb context local: el model veu el que té davant i completa un patró raonable. Revisar un pull request és una tasca amb context històric: cal saber per què l'equip evita una llibreria, quin servei és intocable per una migració pendent, o quin patró de noms es va decidir fa dos anys arran d'un incident. Un model més gran escriu millor autocompletat perquè el patró és al codi que té davant. Un model més gran no revisa millor per si sol perquè la informació que necessita no és al diff, és al cap d'algú de l'equip que mai la va escriure enlloc.

Quan una IA revisa un pull request, normalment veu el diff, potser alguns fitxers relacionats i poc més: no ha viscut l'incident de producció de fa dos anys, no sap que aquell endpoint es va reescriure tres vegades per un problema de concurrència, ni que l'equip va decidir no fer servir una dependència després d'una vulnerabilitat coneguda. Cada pull request nou és, per al model, un arrencada en fred: no acumula memòria entre revisions llevat que algú l'hi doni explícitament. Augmentar la mida del model no resol això, perquè el problema no és quant pot processar sinó quina informació existeix per processar. Si aquella decisió d'arquitectura mai es va escriure enlloc, ni el model més avançat la pot intuir a partir del codi.

El punt cec que cap model resol tot sol

Aquest punt cec no és un defecte que la propera versió del model arreglarà, és estructural: cap sistema pot raonar sobre informació que no rep. La solució passa per tractar el context de revisió com un actiu de l'empresa a mantenir, igual que es manté la documentació tècnica. En la pràctica significa capturar per escrit les decisions que avui només viuen al cap de dues o tres persones sènior de l'equip. Quan aquestes persones marxen, aquest coneixement desapareix també per als revisors humans, no només per a la IA. Per això el fitxer d'instruccions no és un caprici de configuració, és documentació d'arquitectura que la majoria de pimes mai va arribar a escriure.

• Convencions reals de l'equip, no una guia d'estil genèrica copiada d'internet
• Decisions d'arquitectura documentades amb el motiu, no només la regla
• Llista explícita de patrons o dependències prohibides i el perquè
• Exemples reals de comentaris de revisió útils i altres considerats soroll
• Nivell de severitat esperat segons el tipus de codi: no és el mateix el mòdul de pagaments que un script intern

Errors típics en escriure instruccions per a IA

• No copiar una guia d'estil genèrica com a instrucció principal
• Actualitzar el fitxer d'instruccions cada vegada que passi un incident evitable
• Versionar el fitxer d'instruccions a git, igual que el codi que revisa
• Revisar cada trimestre si les instruccions reflecteixen l'estat real del projecte
• No delegar la seva redacció a algú sense context històric de l'equip

Convé ser honestos, encara que no ajudi a vendre més servei: cap instrucció converteix una IA en un revisor sènior. Les instruccions redueixen el soroll i alineen els comentaris amb la realitat de l'equip, però no doten el model de pensar com un atacant, ni d'intuir un cas de negoci mai documentat. Hem vist revisions amb IA molt ben configurades que igualment deixen passar una condició de cursa subtil o una validació de permisos incompleta. Per això no recomanem substituir la revisió humana en codi que toca pagaments, autenticació o dades personals. El que sí recomanem és fer servir la IA per absorbir el volum de comentaris menors i deixar el revisor humà centrat en el que de veritat requereix criteri.

La IA no revisa pitjor codi amb el pas de les versions, revisa el mateix codi amb la mateixa ignorància sobre per què el teu equip va decidir el que va decidir. Aquest buit no l'omple un model millor, l'omple una instrucció escrita per algú que era a la reunió on es va prendre la decisió.

Començar no requereix un projecte de mesos. N'hi ha prou amb triar un repositori actiu, reunir dues o tres persones amb més experiència en ell, i anotar durant una hora les decisions que avui només tenen al cap. Aquest primer fitxer d'instruccions no serà perfecte, i no cal que ho sigui: es corregeix amb el primer incident que reveli un buit. L'important és tractar-lo com un document viu que creix amb cada error evitable, no com una tasca de configuració que es fa una vegada i s'oblida.