Cuando un equipo adopta Claude Code, el primer archivo que aparece en el repositorio suele ser un CLAUDE.md. Ahí van las convenciones de código, los comandos de test y, poco a poco, todo lo demás: «no toques las migraciones», «no hagas push a main», «no leas el .env». Al cabo de unas semanas, el archivo tiene trescientas líneas y el equipo cree que sus reglas están puestas.
La propia documentación de Claude Code dice otra cosa. El modelo trata CLAUDE.md como contexto, no como configuración que se impone. Las reglas que no admiten excepciones tienen otro sitio, y no es un detalle de implementación: es la diferencia entre pedirle algo al agente y que el cliente no le deje hacer lo contrario.
La tesis de esta pieza es sencilla de enunciar y menos sencilla de aplicar: si una regla tiene riesgo, no puede depender de que el agente se acuerde. Lo que orienta va en CLAUDE.md. Lo que tiene que cumplirse va en los permisos de .claude/settings.json y en hooks, que son deterministas. Y ese archivo se versiona en el repositorio y se revisa como el código.
Lo que dice la documentación, con sus palabras
No hace falta interpretar mucho. Cuatro páginas de la documentación oficial lo dicen de forma explícita.
- En la página de memoria: Claude trata CLAUDE.md y la memoria automática «como contexto, no como configuración impuesta», y para bloquear una acción decida lo que decida el modelo remite a un hook
PreToolUse. Más abajo: las reglas de settings «las aplica el cliente decida lo que decida Claude»; las instrucciones de CLAUDE.md dan forma a su comportamiento, «pero no son una capa de imposición». - En la guía de hooks: los hooks dan «control determinista», de modo que ciertas acciones ocurren siempre en lugar de depender de que el modelo decida hacerlas.
- En las buenas prácticas: a diferencia de las instrucciones de CLAUDE.md, «que son orientativas», los hooks son deterministas. Y una advertencia que conviene leer dos veces: un CLAUDE.md inflado hace que Claude ignore las instrucciones que de verdad importan.
- En la página de settings: hacer commit de
.claude/settings.jsonpara que todo el que clone el repositorio tenga los mismos permisos, hooks y plugins.
Cuatro sitios para una regla, con cuatro garantías distintas
Claude Code ofrece varios lugares donde escribir una regla. No son intercambiables: cambian quién la aplica y quién puede saltársela.
| Dónde | Qué es | Quién la aplica | Para qué sirve |
|---|---|---|---|
| CLAUDE.md (proyecto, usuario u organización) | Texto que el modelo lee al empezar cada sesión | El modelo, si la sigue | Comandos, convenciones, decisiones de arquitectura, lo que el agente no puede deducir del código |
Permisos en .claude/settings.json | Reglas de qué herramientas y comandos se permiten, se preguntan o se deniegan | El cliente de Claude Code | Qué puede hacer el agente en este repositorio, igual para todo el equipo |
| Hooks (en el mismo archivo de settings) | Comandos de shell que se ejecutan en momentos fijos, por ejemplo antes de usar una herramienta | El cliente, siempre que ocurre el evento | Bloquear una acción concreta, formatear tras cada edición, registrar lo que pasa |
| Configuración gestionada (managed settings) | Settings que despliega la organización | El cliente, por encima del resto de niveles | Política de seguridad y cumplimiento que ningún repositorio debería poder relajar |
Elaboración propia de onext, a partir de las páginas de memoria, settings y hooks de la documentación de Claude Code (consultadas el 8 de octubre de 2026)
El ejemplo que la propia guía de hooks usa para empezar es revelador: un script que se ejecuta antes de cada edición, comprueba la ruta del archivo contra una lista de patrones protegidos (.env, package-lock.json, .git/) y sale con código 2 si coincide. Con ese código, Claude Code bloquea la edición antes de que ocurra y le pasa al modelo el motivo, para que cambie de enfoque. No hay que confiar en que el agente recuerde la lista: no puede editar esos archivos aunque lo intente.
Qué va en cada sitio: la pregunta que lo decide
La forma práctica de repartir las reglas es hacerse una sola pregunta por cada una: si el agente no la sigue una vez, ¿qué pasa? Si la respuesta es «sale un código algo peor», es contexto. Si la respuesta es «se rompe algo, se filtra algo o alguien tiene que dar explicaciones», es una condición.
| Regla | Si el agente no la sigue | Dónde va |
|---|---|---|
| «Usamos módulos ES, no CommonJS» | Un cambio que se corrige en la revisión | CLAUDE.md |
«Ejecuta los tests con npm test antes de dar algo por terminado» | Trabajo sin verificar que llega a la revisión | CLAUDE.md, y un hook de parada si el equipo quiere que sea obligatorio |
«No leas ni edites el .env» | Credenciales expuestas en una sesión o en un cambio | Permiso denegado y hook PreToolUse |
«No hagas push a main» | Un despliegue que nadie ha aprobado | Permiso denegado, además de la protección de rama en el servidor |
| «No toques los archivos generados» | Cambios que se pierden en la siguiente generación | Hook PreToolUse sobre esas rutas |
| Una política de seguridad que vale para toda la empresa | Un repositorio o una persona la relaja sin que nadie lo decida | Configuración gestionada |
Elaboración propia de onext. El reparto es una propuesta de criterio, no una norma de la documentación; los ejemplos de la primera fila y de la tercera proceden de las buenas prácticas y de la guía de hooks
La cuarta fila tiene una trampa: un permiso en el cliente no sustituye a la protección de rama en el servidor. El agente no es el único que puede hacer push. Las reglas que protegen la producción tienen que vivir donde vive la producción, y la configuración del agente es una capa más, no la única. Es la misma lógica que contamos para los agentes con herramientas en inyección de prompts y permisos: lo que limita el daño es lo que el agente puede hacer, no lo que se le ha pedido.
El archivo compartido también se puede pisar
Versionar .claude/settings.json tiene un matiz que conviene conocer. La documentación ordena los niveles de configuración, de mayor a menor precedencia, así: configuración gestionada, línea de comandos, .claude/settings.local.json del proyecto, .claude/settings.json compartido y la configuración del usuario. Un valor que se fija en un nivel superior prevalece sobre el mismo valor en uno inferior.
Es decir: cada persona puede ajustar para sí misma lo que el equipo ha versionado, con su archivo local, que Claude Code mantiene fuera de git. Para preferencias personales, es lo que se quiere. Para una regla de seguridad, no basta.
Riesgo Lo que tiene que cumplirse en toda la empresa, sin excepciones por persona ni por repositorio, va en la configuración gestionada. La documentación lo plantea así: settings para la imposición técnica y un CLAUDE.md gestionado para la orientación, como estándares de código o recordatorios de cumplimiento. Y añade que algunas reglas del archivo compartido, como las de permitir, no se aplican hasta que cada persona confía en la carpeta; las de denegar y preguntar se aplican de inmediato.
Un CLAUDE.md corto se sigue mejor
Sacar las reglas que imponen tiene un efecto secundario: el CLAUDE.md adelgaza, y eso también es una ganancia. La documentación propone menos de 200 líneas por archivo, porque los archivos largos consumen más contexto y reducen el grado en que se siguen. La guía de buenas prácticas da un test para cada línea: si quitarla no haría que Claude se equivocara, sobra. Si Claude sigue haciendo algo pese a una regla en contra, probablemente el archivo es demasiado largo y la regla se pierde.
Lo que solo aplica a una parte del código puede ir en reglas por ruta dentro de .claude/rules/, que se cargan cuando el agente trabaja con esos archivos. Y lo que se necesita solo a veces, en una skill, que se carga cuando hace falta. Cómo se cura ese texto compartido para que siga siendo útil lo desarrollamos en instrucciones compartidas y curadas, y cuándo conviene convertir un procedimiento en skill, en la guía práctica de skills.
La configuración del agente es código
Si los permisos y los hooks deciden qué puede hacer el agente en un repositorio, cambiarlos es cambiar el comportamiento del sistema. Merece el mismo trato que el código: un pull request, alguien que lo revisa y un motivo escrito. Un hook nuevo que bloquea algo, o un permiso que se relaja, es exactamente el tipo de cambio que nadie debería encontrarse por sorpresa.
Es la misma idea que defendemos para los prompts y las skills en evals en cada pull request: lo que cambia el comportamiento de un agente pasa por la misma puerta que el resto del código. Y es la misma pregunta de fondo que en la especificación es donde se firma: dónde decide una persona y qué queda escrito.
Si vuestro CLAUDE.md lleva meses creciendo, la lectura útil no es «hay que escribirlo mejor». Es otra: cuántas de esas líneas son, en realidad, condiciones que nadie comprueba. Los cambios de producto que también afectan a cómo se configura Claude Code en un equipo los repasamos en los seis cambios técnicos del 15 de junio.
Preguntas frecuentes
¿Claude Code obedece siempre lo que pone el CLAUDE.md?
No está garantizado. La documentación de Claude Code dice que el modelo trata CLAUDE.md como contexto, no como configuración que se impone, y que cuanto más concretas y breves son las instrucciones, con más constancia las sigue. Para bloquear una acción decida lo que decida el modelo, remite a un hook PreToolUse.
¿Qué diferencia hay entre CLAUDE.md y .claude/settings.json?
CLAUDE.md es texto que el modelo lee al empezar cada sesión y que orienta su comportamiento. .claude/settings.json es configuración que aplica el propio cliente de Claude Code: permisos, hooks, plugins y variables de entorno. La documentación lo resume así: las reglas de settings se aplican decida lo que decida Claude; las instrucciones de CLAUDE.md dan forma a su comportamiento, pero no son una capa de imposición.
¿Qué es un hook en Claude Code?
Es un comando de shell que Claude Code ejecuta en un momento fijo de su ciclo, por ejemplo antes de usar una herramienta (PreToolUse) o después de editar un archivo. La documentación lo describe como control determinista: ciertas acciones ocurren siempre, en lugar de depender de que el modelo decida hacerlas. Un hook PreToolUse que sale con código 2 bloquea la acción y devuelve el motivo a Claude.
¿Hay que subir .claude/settings.json al repositorio?
Sí, si es la configuración del equipo. La documentación recomienda hacer commit de .claude/settings.json para que todo el que clone el repositorio tenga los mismos permisos, hooks y plugins. Las excepciones personales van en .claude/settings.local.json, que se queda fuera de git.
¿Cuánto debería ocupar un CLAUDE.md?
La documentación propone menos de 200 líneas por archivo: los archivos largos consumen más contexto y reducen el grado en que se siguen. La guía de buenas prácticas añade un test para cada línea: si quitarla no haría que Claude se equivocara, sobra. Lo que solo aplica a una parte del código puede ir en reglas por ruta dentro de .claude/rules/.
¿Cómo se impone una regla a toda la empresa y no solo a un repositorio?
Con la configuración gestionada (managed settings), que despliega la organización y está por encima del resto en el orden de precedencia. La documentación distingue entre settings para la imposición técnica y un CLAUDE.md gestionado para la orientación de comportamiento, como estándares de código o recordatorios de cumplimiento.
Fuentes
- Claude Code Docs, «How Claude remembers your project» (consultada el 8 de octubre de 2026).
- Claude Code Docs, «Settings files and precedence» (consultada el 8 de octubre de 2026).
- Claude Code Docs, «Automate actions with hooks» (consultada el 8 de octubre de 2026).
- Claude Code Docs, «Best practices for Claude Code» (consultada el 8 de octubre de 2026).
Bernat López es fundador y CEO de onext, boutique de IA. Acompaña a equipos de desarrollo y de producto a trabajar con IA con método —especificación antes de programar, una persona que decide donde hay riesgo y Spec-Driven Development— y aplica a su propia empresa lo que propone: onext funciona con su propio sistema agéntico.
LinkedIn →