L'agent de codi llegeix el seu fitxer d'instruccions, el CLAUDE.md o l'AGENTS.md, quan comença cada tasca. Si aquest fitxer l'ha escrit un model, cada tasca costa de mitjana més d'un 20 % més i l'agent en resol pràcticament les mateixes.
El fitxer de l'agent s'escriu amb el que l'agent no pot deduir del codi. Tota la resta li fa fer més passos i gastar més tokens sense ajudar-lo a resoldre la tasca. Un bon fitxer surt més del que l'equip treu que del que hi afegeix.
Què va mesurar l'estudi d'ETH Zúric
Thibaud Gloaguen, Niels Mündler-Sasahara i Martin Vechev, d'ETH Zúric, amb Mark Niklas Müller i Veselin Raychev, de LogicStar.ai, van mesurar què passa quan un agent treballa amb fitxer d'instruccions i sense. Van provar Claude Code amb Sonnet 4.5, Codex amb GPT-5.2 i amb GPT-5.1 mini, i Qwen Code. Van fer servir 300 tasques de SWE-bench Lite, d'11 repositoris sense fitxer d'instruccions, i 138 d'un banc propi, tretes de 12 repositoris que ja tenien el seu fitxer escrit per desenvolupadors.
Amb un fitxer generat per un model, les tasques resoltes van baixar de mitjana un 0,5 % a SWE-bench Lite i un 2 % al banc propi, i el cost va pujar un 20 % i un 23 %. Amb el fitxer escrit per desenvolupadors, al banc propi, les tasques resoltes van pujar un 2,4 % de mitjana i el cost, fins a un 19 %. Cap d'aquestes diferències d'encert és estadísticament significativa. La que sí que ho és: els fitxers escrits per persones van resoldre de mitjana un 7 % més que els generats.
L'agent obeeix el que llegeix. Quan el fitxer esmentava l'eina uv, l'agent la feia servir 1,6 vegades per tasca; quan no, gairebé mai. Amb el fitxer, a més, llançava més tests i buscava i llegia més fitxers. I el resum del repositori, que tenien vuit dels dotze fitxers dels desenvolupadors, no el feia arribar abans al fitxer que calia canviar. Quan van treure del repositori tota la documentació, els fitxers generats sí que van ajudar: el que aportaven era una còpia del que ja estava escrit.
Límit Són tasques d'un banc de proves, totes en Python, i l'estudi només mesura si la tasca es resol: deixa fora la seguretat i l'eficiència del codi. Les diferències d'encert són petites. El més sòlid és el cost i que l'agent fa cas de cada línia.
Què es queda al fitxer
Els autors ho concreten: el fitxer escrit per persones ha de portar només les instruccions que l'agent necessita i que no són ja al README, com convencions pròpies o requisits no funcionals. Amb això, el que es queda cap en tres grups:
- Ordres pròpies del repositori, sobretot les que no són les habituals: amb què s'instal·len les dependències, quins tests es llancen abans de cada canvi.
- Convencions que el codi no deixa veure: en quina zona horària es desen les dates, quina versió de l'API està congelada.
- Requisits que no es veuen al codi: un límit de rendiment, una taula que no admet consultes sense índex.
Surt el mapa de carpetes, la descripció del producte, el que ja diu el README i les regles d'estil que ja aplica el linter. Surten també les instruccions d'una sola tasca: GitHub, en l'exemple de la seva documentació, demana que les instruccions del repositori «must not be task specific» i que no passin de dues pàgines. Aquest mateix exemple demana un resum del repositori i de la seva estructura, just el que l'estudi no veu útil. Els autors ho diuen clarament: la seva recomanació va en contra del que aconsellen els fabricants d'agents.
Queda fora una tercera cosa: les regles que no es poden saltar mai. Si una regla té risc, va en permisos o en una comprovació automàtica, pel que explico a on va cada regla a Claude Code.
Com podar el fitxer, línia a línia
Una manera de fer-ho amb el fitxer que ja té el teu equip:
- Per a cada línia, pregunta't si l'agent la podria deduir del codi, del README o de la configuració del linter. Si pot, s'esborra.
- Si la línia només serveix per a una tasca, passa-la a l'especificació d'aquella tasca.
- Si és una regla que no es pot saltar mai, com no tocar les migracions o no llegir secrets, porta-la a un permís o a una comprovació automàtica.
- Revisa el que queda en una pull request, la proposta de canvi que l'equip revisa abans d'incorporar-la, com qualsevol altre canvi del repositori.
- Llança el mateix grapat de tasques abans i després, i compara els passos i el cost. Els autors demanen avaluar qualsevol canvi al fitxer abans de donar-lo per bo.
Així podria quedar un fitxer després de la poda. És un exemple inventat, de cap equip real:
# Ordres
- Dependències amb uv: `uv sync`. No fer servir pip.
- Abans de cada commit: `make test-fast`. La suite completa només corre a CI.
# Convencions que no són les habituals
- Les dates es desen en UTC i es mostren en Europe/Madrid.
- Els endpoints nous van a /v2. /v1 està congelat.
# Requisits que no es veuen al codi
- Cap consulta nova sobre orders sense índex: la taula té 40 milions de files.El que va sortir d'aquest fitxer: tres paràgrafs sobre el producte, l'arbre de carpetes i dotze regles d'estil que el linter ja comprovava.
Per on començar aquesta setmana
Obre el fitxer d'instruccions del teu equip i compta quantes línies passen el primer pas. Si en passen poques, el fitxer treballa en contra de l'agent. Per saber quina línia hi falta, mira el que el teu equip corregeix cada dia a l'agent (el que ensenyen aquestes correccions).
Si ho vols revisar amb algú de fora, el diagnòstic és gratuït. Abans, pots veure com treballem amb equips de desenvolupament a AI-Accelerated Development.
Preguntes freqüents
Què és AGENTS.md i en què es diferencia de CLAUDE.md?
Tots dos són fitxers d'instruccions que l'agent de codi llegeix quan comença a treballar en un repositori. CLAUDE.md és el que llegeix Claude Code. AGENTS.md és un nom que accepten diversos agents: GitHub Copilot, per exemple, llegeix AGENTS.md i accepta CLAUDE.md o GEMINI.md a l'arrel com a alternativa. El que convé posar-hi és el mateix en tots.
Convé que el mateix agent generi el fitxer?
No. En l'estudi d'ETH Zúric, els fitxers generats per un model no van millorar les tasques resoltes i van apujar el cost més d'un 20 % de mitjana. Els autors recomanen no fer-los servir de moment i escriure el fitxer a mà, només amb el que no sigui ja al README.
Què ha d'incloure un CLAUDE.md o un AGENTS.md?
El que l'agent no pot deduir llegint el codi o el README: per exemple, que les dependències s'instal·len amb uv o un límit de rendiment que no es veu al codi.
Ajuda posar un resum del repositori al fitxer?
En l'estudi, no. Vuit dels dotze fitxers escrits per desenvolupadors tenien un resum del codi, i amb ells l'agent no arribava abans al fitxer que calia canviar. Aquest resum es pot treure.
Quant ha d'ocupar el fitxer d'instruccions?
L'estudi no dona cap xifra. GitHub, en l'exemple de la seva documentació, demana que les instruccions no passin de dues pàgines i que no siguin d'una tasca concreta. Un criteri pràctic: cada línia ha de respondre a alguna cosa que l'agent no pot esbrinar pel seu compte.
L'agent fa cas del que posa el fitxer?
Sí. En l'estudi, quan el fitxer esmentava l'eina uv, l'agent la feia servir 1,6 vegades per tasca de mitjana; quan no l'esmentava, gairebé mai. Per això cada línia compta, també les que sobren. El que s'ha de complir sempre convé portar-ho a permisos o a comprovacions automàtiques.
Fonts
- Thibaud Gloaguen, Niels Mündler-Sasahara, Mark Niklas Müller, Veselin Raychev i Martin Vechev, «Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?», arXiv:2602.11988, v3 del 29 de setembre de 2026 (v1 del 12 de febrer de 2026).
- GitHub Docs, «Adding repository custom instructions for GitHub Copilot» (sense data; consultada el 4 de novembre de 2026).
Bernat López és fundador i CEO d'onext, boutique d'IA. Acompanya equips de desenvolupament i de producte a treballar amb IA amb mètode —especificació abans de programar, una persona que decideix on hi ha risc i Spec-Driven Development— i aplica a la seva pròpia empresa el que proposa: onext funciona amb el seu propi sistema agèntic.
LinkedIn →