Claude Code settings: qué va en cada capa y quién gana
Claude Code settings por capas: qué va en settings.json, settings.local.json, usuario y managed, quién gana cuando chocan y qué errores evitar en el repo.
El 9 de enero de 2026 alguien abrió el issue #17017 en el repo de Claude Code. El título lo decía todo: "Project-level permissions replace global permissions instead of merging". Tenía herramientas aprobadas en sus Claude Code settings globales, abrió un proyecto con su propio bloque de permisos y Claude volvió a pedirle permiso para esas mismas herramientas.
Hoy, nueve meses después, el issue sigue abierto. Pero lo interesante no es el bug. Es que buena parte del hilo se va en averiguar en qué archivo estaba cada cosa.
Ese es el problema real de los Claude Code settings. No son un archivo. Son cuatro capas, más la línea de comandos, y cada una tiene su alcance, su dueño y sus reglas para decidir quién gana.
En corto: los Claude Code settings se leen en este orden de prioridad: managed, --settings, .claude/settings.local.json, .claude/settings.json y ~/.claude/settings.json. Si dos capas definen la misma clave, gana la más alta; las listas como permissions.allow se fusionan en vez de sustituirse. Lo del equipo va al repo, lo tuyo de un proyecto va en local y lo tuyo de todos los proyectos va en usuario.
¿Qué son los Claude Code settings?
Los Claude Code settings son archivos JSON (settings.json y sus variantes local y managed) que fijan permisos, hooks, variables de entorno, modelo e interfaz, y que Claude Code lee de varias capas con un orden de precedencia fijo.
No son instrucciones para el modelo: según la documentación de permisos, las reglas las hace cumplir Claude Code, y CLAUDE.md solo orienta lo que Claude intenta hacer.
Son JSON estricto: un comentario // o una coma final provocan un Settings Error al arrancar.
Las capas de settings.json en Claude Code: ruta, git y riesgo
Cada capa responde a una pregunta: ¿esto aplica a mí, a mi equipo o a la organización? La tabla resume la página oficial de settings, consultada el 10 de octubre de 2026:
| Capa | Ruta | ¿Va a git? | Para qué | Riesgo |
|---|---|---|---|---|
| Managed | managed-settings.json, política MDM o server-managed desde la consola de claude.ai |
No. La despliega tu organización | Política de seguridad y cumplimiento | Nada de lo tuyo la sobrescribe, ni siquiera --settings |
| CLI | claude --settings '<json o ruta>' |
No | Probar un valor durante una sesión | Desaparece al cerrar la sesión |
| Local | .claude/settings.local.json |
No. Claude Code lo añade a tus excludes globales de git la primera vez que lo escribe | Overrides personales en un proyecto y aprobaciones de "Yes, and don't ask again" | Si lo creas a mano, tienes que ignorarlo tú; si no, acaba en un commit |
| Proyecto | .claude/settings.json |
Sí | Permisos, hooks, plugins y env que necesita el equipo |
Lo lee cualquiera con acceso al repo |
| Usuario | ~/.claude/settings.json (en Windows, %USERPROFILE%\.claude) |
No | Tus preferencias en todos los proyectos: tema, modelo, status line | Pierde contra cualquier proyecto que defina la misma clave |
Dos matices que la tabla no cuenta. Las reglas allow, additionalDirectories y la mayoría de valores de env del archivo compartido esperan a que cada compañero confíe en la carpeta, mientras que deny y ask aplican desde el primer momento.
Y en una sesión en la nube solo se lee el archivo de proyecto y los managed de servidor: tu settings.json de usuario y tu settings.local.json se quedan en tu máquina.
Quién gana cuando dos capas de Claude Code settings chocan
Para valores simples gana la capa más alta que define la clave. Para listas, se suman. El orden, de mayor a menor prioridad:
- Managed. No se puede sobrescribir.
- CLI, con
--settings. - Local,
.claude/settings.local.json. - Proyecto,
.claude/settings.json. - Usuario,
~/.claude/settings.json.
El ejemplo de la doc es spinnerTipsEnabled. Lo pones a false en usuario y el equipo lo pone a true en el proyecto: en ese proyecto verás los tips. Para recuperar tu valor, lo pones a false en settings.local.json, que está por encima del proyecto y no afecta a nadie más.
Con las listas cambia la lógica. Si permissions.allow aparece en varios archivos, Claude Code combina las listas en lugar de elegir una.
Y en permisos manda otro orden: primero deny, después ask y por último allow, sin importar de qué capa venga cada regla. Un deny en tu usuario bloquea un allow del proyecto, y al revés.
Las excepciones:
| Clave | Comportamiento | Fuente |
|---|---|---|
fallbackModel |
No se fusiona: la capa más alta que la define aporta la cadena entera | settings-reference |
permissions.defaultMode con auto o bypassPermissions |
Se ignora en proyecto y en local; solo vale en usuario, managed o con --permission-mode |
settings-reference |
modelPicker |
Se ignora en proyecto y en local | settings |
ANTHROPIC_MODEL exportada en la shell |
No es una capa: se aplica por encima de model en cualquier archivo |
settings |
Qué poner en settings.json, settings.local.json y usuario
Mi regla: cada clave va en la capa más baja en la que tiene sentido, y nada personal va al repo.
En el proyecto, lo que protege al equipo. Este es un .claude/settings.json realista para un repo de Node:
{
"$schema": "https://json.schemastore.org/claude-code-settings.json",
"permissions": {
"allow": [
"Bash(npm run lint)",
"Bash(npm run test *)"
],
"ask": [
"Bash(git push *)"
],
"deny": [
"Read(./.env)",
"Read(./.env.*)"
]
},
"env": {
"NODE_ENV": "development"
}
}
Los deny son la parte valiosa de este archivo. Aplican sin esperar a la confianza en la carpeta, ganan a cualquier allow de otra capa y viajan con cada clon.
En .claude/settings.local.json, lo tuyo en ese proyecto. Si el equipo fija "model": "claude-sonnet-5" y tú quieres Opus solo aquí, pones "model": "claude-opus-5-5" en local y no tocas a nadie. Ahí también acaban las aprobaciones que das con "Yes, and don't ask again".
En ~/.claude/settings.json, lo tuyo en todas partes: theme, tu model por defecto, tu statusLine y, si lo usas, permissions.defaultMode en auto. Si quieres ver el flujo completo, de la idea al producto, lo hacemos paso a paso en el curso Construye con IA.
Tres errores típicos con los Claude Code settings
Meter secretos en el settings compartido. Un env con ANTHROPIC_API_KEY o el token de una base de datos en .claude/settings.json es un secreto commiteado. Si necesitas generar credenciales, existe apiKeyHelper, que ejecuta tu propio comando para obtenerlas. Y si es una variable personal, va en local.
Esperar que una lista sobrescriba. Si el proyecto permite Bash(npm run test *), no lo quitas omitiéndolo en tu settings.local.json: las listas se suman. Para cortar algo, añade un deny, que gana desde cualquier capa.
Aquí vuelve el issue #17017. La doc dice que las listas se fusionan, pero el hilo tiene reproducciones que dicen lo contrario. En mayo de 2026, un usuario en Windows tenía Read(//c/REPOS/**) en el allow de su ~/.claude/settings.json. En cuanto el .claude/settings.local.json del proyecto tuvo su propio allow, Claude volvió a pedirle permiso para leer esos archivos. En julio, otro lo reprodujo con la CLI v2.1.206 y un defaultMode global.
Y otro comentarista señaló que el propio reporte original guardaba sus permisos globales en ~/.claude/settings.local.json, un archivo que, según la doc de permisos, solo se lee cuando arrancas Claude Code en tu home, no en cada proyecto. Lo práctico: no te fíes de la teoría. Abre /permissions, que lista cada regla y el archivo del que sale.
Poner auto mode en el proyecto. "defaultMode": "auto" en .claude/settings.json no hace nada. "bypassPermissions" sí se aplicaba desde cualquier archivo, pero desde la v2.1.257 también se ignora en proyecto y en local. Tiene sentido: un repo que clonas no debería poder quitarte los avisos de permisos. Si lo quieres, va en tu usuario o en --permission-mode para una sesión.
Lo que no va en Claude Code settings
Los Claude Code settings son configuración declarativa, y forzarlos acaba en un settings.json que nadie entiende.
Las instrucciones no van aquí. "Usa pnpm", "no toques la carpeta legacy" o "escribe los tests primero" son contexto para el modelo, y su sitio es CLAUDE.md. Settings controla lo que Claude Code permite, no lo que Claude decide.
La lógica condicional tampoco. Una regla deny sobre Bash compara el texto del comando; la propia doc avisa de que no es una frontera de seguridad alrededor del programa, porque el mismo binario invocado de otra forma no coincide. Si necesitas inspeccionar argumentos o validar rutas, eso es un hook. Lo explico en hooks vs permissions en Claude Code y en la guía de hooks como guardrails.
/status no te dice qué archivo puso cada clave. Te dice qué archivos cargó. Para saber de dónde sale un valor concreto tienes /permissions para las reglas y claude doctor para las entradas rechazadas, pero no hay una vista de "valor efectivo" por clave.
Qué hacer hoy con tus Claude Code settings
Abre /status en el proyecto en el que más trabajas y mira la línea Setting sources. Después abre /permissions y busca reglas tuyas que estén en el archivo equivocado: aprobaciones personales en el settings.json compartido o deny de seguridad que solo existen en tu local.
Mueve cada una a su capa y haz commit del archivo de proyecto. Es el mismo principio que defiendo en el libro de Spec-Driven Development: lo que el equipo debe cumplir se escribe una vez, en un sitio que todos leen, y no se deja a la memoria de nadie. Punto de partida general: cómo configurar Claude Code para programar.
Preguntas frecuentes
¿Dónde está el settings.json de Claude Code?
Hay varios. El de usuario está en ~/.claude/settings.json (en Windows, %USERPROFILE%\.claude\settings.json). El de proyecto, en .claude/settings.json dentro del repo, y el local en .claude/settings.local.json.
¿settings.local.json va a git?
No. Claude Code añade **/.claude/settings.local.json a tus excludes globales de git la primera vez que escribe el archivo. Si lo creaste a mano antes de eso, añádelo tú al .gitignore.
¿Qué pasa si el usuario y el proyecto definen la misma clave?
Gana el proyecto, porque está por encima del usuario. La excepción son las listas, como permissions.allow, que se fusionan. Para recuperar tu valor en ese proyecto, defínelo en .claude/settings.local.json.
¿Por qué no funciona defaultMode auto en el settings.json del proyecto?
Porque Claude Code ignora auto y bypassPermissions en .claude/settings.json y en .claude/settings.local.json. Ponlo en ~/.claude/settings.json, deja que lo fije tu organización en managed o usa --permission-mode para una sesión.
¿Puedo sobrescribir los managed settings de mi empresa?
No. Ni tus archivos ni --settings cambian una clave managed. Solo hay excepciones para algunas claves de seguridad, en las que Claude Code acepta un valor más restrictivo desde una capa inferior. /status te dice qué fuente managed te aplica.
Por Bezael Pérez — Developer senior con más de 15 años de experiencia y fundador de Dominicode.
¿Quieres construir con agentes en serio?
Curso «Construye con IA» con Claude Code, de la idea al producto.
Developer con más de 15 años en frontend y creador de Dominicode. Escribe sobre IA aplicada al desarrollo de software.
¿Te resultó útil este artículo?
Compártelo con tu comunidad y ayuda a otros desarrolladores.