L'adopció d'eines de IA en el desenvolupament de programari ha seguit un patró previsible: primer, developers individuals experimenten amb prompts ad hoc; després, alguns descobreixen tècniques especialment efectives; finalment, sorgeix la pregunta inevitable: com compartim el que funciona?
La resposta és a les instruccions compartides i curades per a equips de programari — una pràctica que transforma el coneixement dispers sobre com interactuar amb la IA en un actiu organitzacional gestionat i millorat contínuament.
Per què el prompting individual no escala
Quan cada membre de l'equip desenvolupa els seus propis prompts, es generen diversos problemes:
Inconsistència en els resultats. Un developer obté codi ben estructurat mentre un altre s'esforça amb outputs de baixa qualitat, simplement per diferències en com formulen les seves peticions.
Duplicació d'esforç. Múltiples persones resolen el mateix problema de comunicació amb la IA, cadascuna invertint temps que s'hauria pogut estalviar.
Pèrdua de coneixement. Quan algú descobreix un prompt especialment efectiu per revisar pull requests o generar tests, aquest coneixement queda aïllat a la seva màquina local.
Corba d'aprenentatge repetida. Cada nou membre de l'equip ha de descobrir per si mateix què funciona i què no.
El resultat: El 80% dels equips fa servir la IA de manera individual. Només el 20% ha sistematitzat el coneixement col·lectiu sobre com fer-la servir efectivament.
La solució: instruccions com a codi
L'enfocament més directe per implementar instruccions compartides és tractar-les com tractem qualsevol altre artefacte d'enginyeria: versionant-les al repositori del projecte.
AGENTS.md: l'estàndard emergent
El fitxer AGENTS.md s'ha convertit en una convenció adoptada per múltiples eines d'AI-coding. Aquest fitxer, ubicat a l'arrel del projecte, conté instruccions que les eines de IA llegeixen automàticament per contextualitzar el seu comportament.
Un AGENTS.md efectiu normalment inclou:
# Context del Projecte
Aquest és un servei de pagaments escrit en Python 3.11 fent servir FastAPI.
Seguim arquitectura hexagonal amb ports i adaptadors.
## Convencions de codi
- Fem servir type hints en totes les funcions públiques
- Els tests segueixen el patró Arrange-Act-Assert
- Preferim composició sobre herència
## Patrons específics
En generar endpoints:
- Sempre incloure validació amb Pydantic
- Implementar gestió d'errors amb HTTPException
- Documentar amb docstrings compatibles amb OpenAPI
## Què evitar
- No fer servir ORMs; preferim queries SQL explícites
- No crear classes singleton
- Evitar imports circulars separant interfícies
Suport a les eines modernes
Les principals eines d'AI-coding han adoptat mecanismes per a instruccions compartides:
Cursor permet definir regles en fitxers .cursorrules i crear comandes slash personalitzades que l'equip pot invocar de manera consistent.
Windsurf suporta fitxers de configuració que estableixen el context del projecte i guies d'estil que la IA respecta en els seus suggeriments.
Claude Code llegeix automàticament fitxers com CLAUDE.md o AGENTS.md i permet configurar instruccions a nivell de projecte que persisteixen entre sessions.
Més enllà del codi: instruccions per a tot el delivery
El valor de les instruccions curades s'estén a totes les activitats de lliurament de programari:
Revisió de codi. Prompts estandarditzats perquè la IA revisi PRs enfocant-se en els criteris específics de l'equip: seguretat, rendiment, adherència a patrons arquitectònics.
Documentació. Instruccions que garanteixen que la documentació generada segueixi el format, el to i el nivell de detall que el projecte requereix.
Testing. Prompts per generar casos de prova que cobreixin els escenaris edge que històricament han causat bugs al projecte.
Anàlisi de requisits. Instruccions per extreure històries d'usuari o criteris d'acceptació de converses amb stakeholders.
Biblioteques de prompts organitzacionals
Per a tasques que no estan vinculades a un repositori específic, les organitzacions poden mantenir biblioteques centralitzades de prompts provats:
- Wikis interns amb prompts categoritzats per cas d'ús
- Snippets compartits en eines com Notion o Confluence
- Repositoris dedicats de prompts amb exemples i resultats esperats
El cicle de millora contínua
El veritable avantatge de les instruccions compartides emergeix quan s'estableix un procés de refinament:
- Contribució. Qualsevol membre de l'equip pot proposar noves instruccions o millores a les existents.
- Revisió. Les propostes passen pel mateix procés de revisió que el codi, avaluant claredat, efectivitat i alineació amb els estàndards de l'equip.
- Validació. Es proven les instruccions en escenaris reals abans d'incorporar-les al conjunt principal.
- Distribució immediata. Un cop mergejades, tot l'equip té accés instantani a les millores.
- Retroalimentació. Es recull feedback sobre l'efectivitat de les instruccions en ús.
El resultat: Un sistema que es torna més intel·ligent amb cada iteració. El descobriment d'un developer beneficia automàticament tot l'equip.
Implementació pràctica: 4 setmanes
Per a equips que volen començar, aquest és l'enfocament incremental que recomanem:
Setmana 1-2: Recol·lecció
Demana a cada membre de l'equip que comparteixi els 3-5 prompts que més fa servir i que millors resultats li donen. No jutgis, només recopila.
Setmana 3: Consolidació
Agrupa els prompts per categoria, identifica patrons comuns i elimina redundàncies. Busca els prompts que diversos developers fan servir de manera similar.
Setmana 4: Documentació inicial
Crea el primer AGENTS.md (o CLAUDE.md, segons la teva eina) amb les instruccions més universalment útils.
Mes 2+: Iteració
Estableix un canal (Slack, Teams) on l'equip comparteixi descobriments i proposi millores. Revisa i actualitza les instruccions cada 2 setmanes.
L'impacte en la productivitat de l'equip
Els equips que adopten instruccions compartides reporten beneficis tangibles:
- Reducció del temps d'onboarding per a nous membres que hereten mesos d'aprenentatge col·lectiu
- Més consistència en el codi generat, reduint friccions en les revisions
- Democratització del coneixement — el junior amb el millor prompt per a debugging ara beneficia tot l'equip
- Millora acumulativa on cada refinament eleva la línia base de tothom
Cas real: equip de 8 developers
Abans: Cada developer amb els seus propis prompts. Inconsistència en el codi generat. Els nous membres trigaven 3+ setmanes a ser productius amb IA.
Després: CLAUDE.md compartit + biblioteca de prompts a Notion. Codi generat consistent. Onboarding amb IA reduït a 3 dies.
Resultat: +40% productivitat de l'equip en 6 setmanes
Estructura recomanada per al teu AGENTS.md
Basat en la nostra experiència implementant això en equips, aquesta és l'estructura que millor funciona:
# AGENTS.md
## Context del projecte
[Breu descripció: què fa, stack, arquitectura]
## Convencions de codi
[Regles que la IA ha de seguir SEMPRE]
## Patrons específics
[Com generar endpoints, components, tests, etc.]
## Què evitar
[Antipatterns, dependències prohibides, etc.]
## Exemples
[Codi de referència perquè la IA entengui l'estil]
## Prompts freqüents
[Templates per a tasques comunes del projecte]
Conclusió: d'habilitat individual a capacitat organitzacional
Les instruccions compartides i curades representen la maduració natural de l'ús de IA en equips de programari. Així com fa anys vam aprendre a versionar configuracions, pipelines i scripts d'infraestructura, ara incorporem les instruccions de IA com un artefacte més del projecte.
El resultat és un multiplicador de productivitat que creix amb cada millora que qualsevol membre de l'equip aporta — transformant el prompting d'una habilitat individual en una capacitat organitzacional.
La pregunta no és si el teu equip farà servir la IA. És si el coneixement sobre com fer-la servir es quedarà en silos individuals o es convertirà en un actiu col·lectiu que millora contínuament.
Jordi García és Tech Lead a onext. Treballa a portar la IA a producció governada en equips de desenvolupament i de producte —amb Spec-Driven Development, enginyeria de context i verificació humana a cada pas— i signa els insights tècnics d'onext sobre mètode, qualitat i cost de la IA aplicada.
LinkedIn →