Quan un equip adopta Claude Code, el primer fitxer que apareix al repositori sol ser un CLAUDE.md. Hi van les convencions de codi, les ordres de test i, a poc a poc, tota la resta: «no toquis les migracions», «no facis push a main», «no llegeixis el .env». Al cap d'unes setmanes, el fitxer té tres-centes línies i l'equip creu que les seves regles ja hi són.
La mateixa documentació de Claude Code diu una altra cosa. El model tracta CLAUDE.md com a context, no com a configuració que s'imposa. Les regles que no admeten excepcions tenen un altre lloc, i no és un detall d'implementació: és la diferència entre demanar-li una cosa a l'agent i que el client no el deixi fer el contrari.
La tesi d'aquesta peça és senzilla d'enunciar i menys senzilla d'aplicar: si una regla té risc, no pot dependre que l'agent se'n recordi. El que orienta va a CLAUDE.md. El que s'ha de complir va als permisos de .claude/settings.json i als hooks, que són deterministes. I aquest fitxer es versiona al repositori i es revisa com el codi.
El que diu la documentació, amb les seves paraules
No cal interpretar gaire. Quatre pàgines de la documentació oficial ho diuen de manera explícita.
- A la pàgina de memòria: Claude tracta CLAUDE.md i la memòria automàtica «com a context, no com a configuració imposada», i per bloquejar una acció decideixi el que decideixi el model remet a un hook
PreToolUse. Més avall: les regles de settings «les aplica el client decideixi el que decideixi Claude»; les instruccions de CLAUDE.md donen forma al seu comportament, «però no són una capa d'imposició». - A la guia de hooks: els hooks donen «control determinista», de manera que certes accions passen sempre en lloc de dependre que el model decideixi fer-les.
- A les bones pràctiques: a diferència de les instruccions de CLAUDE.md, «que són orientatives», els hooks són deterministes. I una advertència que convé llegir dues vegades: un CLAUDE.md inflat fa que Claude ignori les instruccions que de debò importen.
- A la pàgina de settings: fer commit de
.claude/settings.jsonperquè tothom qui cloni el repositori tingui els mateixos permisos, hooks i plugins.
Quatre llocs per a una regla, amb quatre garanties diferents
Claude Code ofereix diversos llocs on escriure una regla. No són intercanviables: canvien qui l'aplica i qui se la pot saltar.
| On | Què és | Qui l'aplica | Per a què serveix |
|---|---|---|---|
| CLAUDE.md (projecte, usuari o organització) | Text que el model llegeix en començar cada sessió | El model, si la segueix | Ordres, convencions, decisions d'arquitectura, el que l'agent no pot deduir del codi |
Permisos a .claude/settings.json | Regles de quines eines i ordres es permeten, es pregunten o es deneguen | El client de Claude Code | Què pot fer l'agent en aquest repositori, igual per a tot l'equip |
| Hooks (al mateix fitxer de settings) | Ordres de shell que s'executen en moments fixos, per exemple abans de fer servir una eina | El client, sempre que passa l'esdeveniment | Bloquejar una acció concreta, formatar després de cada edició, registrar el que passa |
| Configuració gestionada (managed settings) | Settings que desplega l'organització | El client, per sobre de la resta de nivells | Política de seguretat i compliment que cap repositori no hauria de poder relaxar |
Elaboració pròpia d'onext, a partir de les pàgines de memòria, settings i hooks de la documentació de Claude Code (consultades el 8 d'octubre de 2026)
L'exemple que la mateixa guia de hooks fa servir per començar és revelador: un script que s'executa abans de cada edició, comprova la ruta del fitxer contra una llista de patrons protegits (.env, package-lock.json, .git/) i surt amb el codi 2 si coincideix. Amb aquest codi, Claude Code bloqueja l'edició abans que passi i li comunica el motiu al model, perquè canviï d'enfocament. No cal confiar que l'agent recordi la llista: no pot editar aquests fitxers encara que ho intenti.
Què va a cada lloc: la pregunta que ho decideix
La manera pràctica de repartir les regles és fer-se una sola pregunta per a cadascuna: si l'agent no la segueix una vegada, què passa? Si la resposta és «surt un codi una mica pitjor», és context. Si la resposta és «es trenca alguna cosa, es filtra alguna cosa o algú ha de donar explicacions», és una condició.
| Regla | Si l'agent no la segueix | On va |
|---|---|---|
| «Fem servir mòduls ES, no CommonJS» | Un canvi que es corregeix a la revisió | CLAUDE.md |
«Executa els tests amb npm test abans de donar res per acabat» | Feina sense verificar que arriba a la revisió | CLAUDE.md, i un hook d'aturada si l'equip vol que sigui obligatori |
«No llegeixis ni editis el .env» | Credencials exposades en una sessió o en un canvi | Permís denegat i hook PreToolUse |
«No facis push a main» | Un desplegament que ningú no ha aprovat | Permís denegat, a més de la protecció de branca al servidor |
| «No toquis els fitxers generats» | Canvis que es perden a la generació següent | Hook PreToolUse sobre aquestes rutes |
| Una política de seguretat que val per a tota l'empresa | Un repositori o una persona la relaxa sense que ningú ho decideixi | Configuració gestionada |
Elaboració pròpia d'onext. El repartiment és una proposta de criteri, no una norma de la documentació; els exemples de la primera fila i de la tercera provenen de les bones pràctiques i de la guia de hooks
La quarta fila té un parany: un permís al client no substitueix la protecció de branca al servidor. L'agent no és l'únic que pot fer push. Les regles que protegeixen la producció han de viure on viu la producció, i la configuració de l'agent és una capa més, no l'única. És la mateixa lògica que expliquem per als agents amb eines a injecció de prompts i permisos: el que limita el dany és el que l'agent pot fer, no el que se li ha demanat.
El fitxer compartit també es pot trepitjar
Versionar .claude/settings.json té un matís que convé conèixer. La documentació ordena els nivells de configuració, de més a menys precedència, així: configuració gestionada, línia d'ordres, .claude/settings.local.json del projecte, .claude/settings.json compartit i la configuració de l'usuari. Un valor fixat en un nivell superior preval sobre el mateix valor en un d'inferior.
És a dir: cada persona pot ajustar per a si mateixa el que l'equip ha versionat, amb el seu fitxer local, que Claude Code manté fora de git. Per a preferències personals, és el que es vol. Per a una regla de seguretat, no n'hi ha prou.
Risc El que s'ha de complir a tota l'empresa, sense excepcions per persona ni per repositori, va a la configuració gestionada. La documentació ho planteja així: settings per a la imposició tècnica i un CLAUDE.md gestionat per a l'orientació, com ara estàndards de codi o recordatoris de compliment. I hi afegeix que algunes regles del fitxer compartit, com les de permetre, no s'apliquen fins que cada persona confia en la carpeta; les de denegar i preguntar s'apliquen de seguida.
Un CLAUDE.md curt se segueix millor
Treure les regles que imposen té un efecte secundari: el CLAUDE.md s'aprima, i això també és un guany. La documentació proposa menys de 200 línies per fitxer, perquè els fitxers llargs consumeixen més context i redueixen el grau en què se segueixen. La guia de bones pràctiques dona un test per a cada línia: si treure-la no faria que Claude s'equivoqués, sobra. Si Claude continua fent una cosa malgrat una regla en contra, probablement el fitxer és massa llarg i la regla es perd.
El que només s'aplica a una part del codi pot anar en regles per ruta dins de .claude/rules/, que es carreguen quan l'agent treballa amb aquells fitxers. I el que només cal de tant en tant, en una skill, que es carrega quan fa falta. Com es cura aquest text compartit perquè continuï sent útil ho desenvolupem a instruccions compartides i curades, i quan convé convertir un procediment en skill, a la guia pràctica de skills.
La configuració de l'agent és codi
Si els permisos i els hooks decideixen què pot fer l'agent en un repositori, canviar-los és canviar el comportament del sistema. Mereix el mateix tracte que el codi: una pull request, algú que la revisa i un motiu escrit. Un hook nou que bloqueja alguna cosa, o un permís que es relaxa, és exactament el tipus de canvi que ningú no s'hauria de trobar per sorpresa.
És la mateixa idea que defensem per als prompts i les skills a evals a cada pull request: el que canvia el comportament d'un agent passa per la mateixa porta que la resta del codi. I és la mateixa pregunta de fons que a l'especificació és on se signa: on decideix una persona i què queda escrit.
Si el vostre CLAUDE.md fa mesos que creix, la lectura útil no és «cal escriure'l millor». És una altra: quantes d'aquestes línies són, en realitat, condicions que ningú no comprova. Els canvis de producte que també afecten com es configura Claude Code en un equip els repassem a els sis canvis tècnics del 15 de juny.
Preguntes freqüents
Claude Code obeeix sempre el que diu el CLAUDE.md?
No està garantit. La documentació de Claude Code diu que el model tracta CLAUDE.md com a context, no com a configuració que s'imposa, i que com més concretes i breus són les instruccions, amb més constància les segueix. Per bloquejar una acció decideixi el que decideixi el model, remet a un hook PreToolUse.
Quina diferència hi ha entre CLAUDE.md i .claude/settings.json?
CLAUDE.md és text que el model llegeix en començar cada sessió i que n'orienta el comportament. .claude/settings.json és configuració que aplica el mateix client de Claude Code: permisos, hooks, plugins i variables d'entorn. La documentació ho resumeix així: les regles de settings s'apliquen decideixi el que decideixi Claude; les instruccions de CLAUDE.md donen forma al seu comportament, però no són una capa d'imposició.
Què és un hook a Claude Code?
És una ordre de shell que Claude Code executa en un moment fix del seu cicle, per exemple abans de fer servir una eina (PreToolUse) o després d'editar un fitxer. La documentació el descriu com a control determinista: certes accions passen sempre, en lloc de dependre que el model decideixi fer-les. Un hook PreToolUse que surt amb el codi 2 bloqueja l'acció i retorna el motiu a Claude.
Cal pujar .claude/settings.json al repositori?
Sí, si és la configuració de l'equip. La documentació recomana fer commit de .claude/settings.json perquè tothom qui cloni el repositori tingui els mateixos permisos, hooks i plugins. Les excepcions personals van a .claude/settings.local.json, que queda fora de git.
Quant hauria d'ocupar un CLAUDE.md?
La documentació proposa menys de 200 línies per fitxer: els fitxers llargs consumeixen més context i redueixen el grau en què se segueixen. La guia de bones pràctiques hi afegeix un test per a cada línia: si treure-la no faria que Claude s'equivoqués, sobra. El que només s'aplica a una part del codi pot anar en regles per ruta dins de .claude/rules/.
Com s'imposa una regla a tota l'empresa i no només a un repositori?
Amb la configuració gestionada (managed settings), que desplega l'organització i que és per sobre de la resta en l'ordre de precedència. La documentació distingeix entre settings per a la imposició tècnica i un CLAUDE.md gestionat per a l'orientació del comportament, com ara estàndards de codi o recordatoris de compliment.
Fonts
- Claude Code Docs, «How Claude remembers your project» (consultada el 8 d'octubre de 2026).
- Claude Code Docs, «Settings files and precedence» (consultada el 8 d'octubre de 2026).
- Claude Code Docs, «Automate actions with hooks» (consultada el 8 d'octubre de 2026).
- Claude Code Docs, «Best practices for Claude Code» (consultada el 8 d'octubre 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 →