20/02/2026
Descobreix què són AGENTS.md i copilot-instructions.md, com funcionen els fitxers de context per a agents d’IA i per què són clau per generar codi coherent, segur i alineat amb els estàndards del projecte.
La intel·ligència artificial s’ha integrat de manera accelerada en el desenvolupament de softaware. Hem passat de cicles de desenvolupament de diversos mesos a crear MVPs en qüestió de dies gràcies a la IA generativa.
Avui dia, qualsevol IDE competitiu incorpora xats o agents capaços de generar funcionalitats completes amb poques instruccions, permetent escollir entre múltiples models especialitzats segons la tasca.
Tanmateix, sense el context adequat, aquests “companys de programació” poden:
- Trencar convencions del projecte.
- Generar codi inconsistent.
- Introduir errors crítics o comportaments no desitjats.
AGENTS.md, el README.md de les màquines
Tots els desenvolupadors coneixen el README.md, un fitxer que explica com instal·lar un projecte, quines tecnologies utilitza i com contribuir-hi.
Els agents d’IA també necessiten el seu propi manual: aquí és on entren en joc AGENTS.md i copilot-instructions.md.
Quina informació aporten els fitxers de context
Un fitxer AGENTS.md pot incloure:
- Estructura de carpetes.
- Convencions de programació.
- Estàndards per als commits.
- Com executar els tests.
- Patrons i antipatrons del projecte.
- Regles que no s’han de trencar.
L’objectiu és clar: evitar que la IA “improvisi” i assegurar que treballi alineada amb les decisions de l’equip.
AGENTS.md vs copilot-instructions.md
Tot i que AGENTS.md és un estàndard emergent consensuat entre diverses companyies, alguns proveïdors utilitzen configuracions pròpies, com copilot-instructions.md a GitHub Copilot.
Avantatge clau d’AGENTS.md
AGENTS.md és agnòstic respecte a l’eina, cosa que permet reutilitzar el mateix context amb diferents agents i models d’IA, reduint la dependència d’un únic proveïdor.
Com s’estructura un fitxer AGENTS.md
A la documentació oficial d’AGENTS.md es mostren exemples clars del seu ús. En aquests es pot observar com, mitjançant llenguatge natural, es pot descriure el funcionament intern del projecte.
Contingut habitual d’un AGENTS.md
- Comandes importants del projecte.
- Directrius per als commits.
- Estructura de directoris.
- Estil de programació.
- Procés d’instal·lació i desplegament.
Aquest fitxer s’ha de desar a l’arrel del projecte i pot referenciar altres documents per mantenir una estructura neta i escalable.
Un document viu
Igual que el repositori, aquests fitxers evolucionen amb el temps. La seva funció és optimitzar el context que reben els models d’IA i millorar l’ús de tokens, aconseguint resultats més precisos i personalitzats.
Exemple real d’ús en un projecte
En el projecte NewClientsOnlineOnboarding (Banksy) es va implementar copilot-instructions.md després d’un refactor, amb l’objectiu de garantir que les noves funcionalitats respectessin:
- L’estructura existent.
- Les bones pràctiques.
- Les convencions arquitectòniques definides.
Instruccions especialitzades per àrea
Les regles es van dividir en diversos fitxers, cadascun enfocat a una part concreta del sistema. Això facilita que un nou desenvolupador entengui ràpidament com treballar en el projecte.
Control sobre el que la IA ha i no ha de fer
Aquest enfocament permet definir, per exemple, com estructurar un component React:
- Quines carpetes utilitzar.
- Quins fitxers generar.
- Quines convencions seguir.
A més, impedeix accions no desitjades com generar fitxers innecessaris o trencar patrons arquitectònics.
Estàndard emergent o moda passatgera?
Com passa amb tota nova tecnologia, l’adopció dels fitxers de context serà progressiva.
Segons un estudi de la Universitat de Heidelberg (Context Engineering for AI Agents in Open-Source Software), només el 5% dels 10.000 repositoris més populars de GitHub utilitzen actualment aquest tipus de fitxers.
Això indica que ens trobem davant d’una tendència emergent, però amb un potencial de creixement significatiu.
Reptes i limitacions dels fitxers de context
Malgrat la seva utilitat, AGENTS.md i copilot-instructions.md no estan exempts de riscos.
Principals desafiaments
- No existeix un estàndard formal universal.
- Interpretació diferent segons el proveïdor.
- Riscos de seguretat si es concedeixen permisos excessius.
- Manca de control de versions natiu.
- Possible ignorància parcial del fitxer per part del model.
Aquests factors fan imprescindible la supervisió humana.
Conclusió: una nova capa en el desenvolupament assistit per IA
Els fitxers de context com AGENTS.md i copilot-instructions.md representen un pas natural en l’evolució del desenvolupament de software assistit per IA.
Permeten alinear els agents amb l’arquitectura del projecte, reduir errors i millorar la coherència del codi generat.
No són una solució màgica ni un estàndard definitiu, però sí una eina potent que veurem adoptar-se de manera creixent en projectes professionals.
tags:
Comparteix:
