settings.json: Configuración a nivel de usuario y proyecto

📚 Navegación de la serie: El artículo anterior 30 Elegir características: CLAUDE.md vs Skill vs Hook vs MCP vs Subagent te enseñó qué extensión utilizar según tu necesidad. En este artículo profundizaremos un nivel: dónde guardar los interruptores detrás de estas extensiones, en qué archivo escribirlos y qué nivel de configuración tiene prioridad. settings.json es el cuadro eléctrico principal de Claude Code; hoy organizaremos sus conexiones para que lo entiendas a la perfección.

Hay un error absurdo en el que es muy fácil caer, y que una vez que tropiezas con él no lo olvidas jamás.

Cuando empecé a usar Claude Code en serio, lo primero que hice fue escribir la línea defaultMode: "auto" en el archivo .claude/settings.json de un proyecto, con la intención de que se ejecutara en modo automático al entrar y no me pidiera confirmaciones. Lo guardé y no ocurrió nada. Mi primera reacción fue pensar que había escrito mal el nombre del campo, por lo que comparé la documentación oficial letra por letra tres veces: no había ningún error tipográfico. Luego sospeché que el JSON estaba mal formateado, así que lo pasé por un validador en línea: era totalmente correcto. Estuve dando vueltas unos veinte minutos, llegando a pensar que esta versión de Claude Code tenía un bug.

Más tarde, en un rincón de la documentación, leí esta frase: cuando estableces defaultMode como "auto", la configuración escrita a nivel de proyecto se ignora por completo. Esto es una restricción deliberada del sistema para evitar que un repositorio active el modo automático de forma silenciosa al clonarlo (algo que también mencionamos en el artículo 20). La sintaxis de esa línea de configuración era correcta y el archivo estaba bien; el error fue escribirla en el nivel equivocado. Al moverla al archivo de configuración a nivel de usuario ~/.claude/settings.json, funcionó al instante.

Te cuento esto para que recuerdes una regla: los problemas con settings.json rara vez se deben a "cómo escribirlo", sino a "en qué nivel colocarlo y qué nivel prevalece". Hoy desglosaremos esta "regla de niveles" para que la próxima vez que configures sepas exactamente si colocar la línea en tu directorio personal o en el proyecto.

Al terminar de leer este artículo, obtendrás:

• Una explicación directa de qué es settings.json y cómo se divide el trabajo entre este y CLAUDE.md.
• La ubicación en el sistema, el ámbito de impacto y el contenido recomendado para cada uno de los tres niveles de configuración (Usuario / Proyecto / Local).
• Una tabla de prioridades ("quién prevalece sobre quién") junto con la excepción que va contra la intuición (los arrays se fusionan, no se sobrescriben).
• Qué hacen y en qué nivel deben guardarse las opciones más habituales (model, permissions, env, hooks, statusLine).
• Un ejercicio práctico para verificar el funcionamiento: escribir una configuración y comprobar que se aplica usando /status.

---

01 Primero entiende: Qué es settings.json y su división del trabajo con CLAUDE.md

Empecemos con la conclusión: settings.json es el cuadro de mandos de Claude Code: gestiona mediante JSON los permisos, variables de entorno, modelo por defecto, Hooks y la barra de estado. Es diferente de CLAUDE.md: settings.json define "cómo funciona la herramienta" y CLAUDE.md define "qué debe recordar".

Es muy común confundir estos dos archivos al principio. A lo largo de la serie hemos escrito reglas en CLAUDE.md (artículo 18), configurado permisos (artículo 20) y editado configuraciones; todo esto se almacena en el archivo settings.json, pero su contenido es totalmente distinto al de CLAUDE.md.

Analogía: El archivador del proyecto frente a la caja de fusibles de tu puesto de trabajo. CLAUDE.md es como el manual impreso dentro del archivador: contiene instrucciones como "usar pnpm en lugar de npm" o "ejecutar las pruebas antes de confirmar" redactadas en lenguaje natural para que las lea Claude en cada sesión. settings.json es diferente: es la caja de fusibles de la pared, con interruptores bien definidos: qué herramientas están permitidas, qué modelo usar por defecto o qué script ejecutar automáticamente al guardar. El archivador contiene "las normas explicadas al agente"; la caja de fusibles contiene "el comportamiento predefinido del software".

La documentación oficial define su posición claramente:

El archivo settings.json es el mecanismo oficial para configurar Claude Code mediante opciones jerárquicas.

Presta atención a los términos "mecanismo oficial" y "opciones jerárquicas", que marcan las dos ideas de este artículo: es la vía formal para configurar Claude Code (en lugar de pasar parámetros temporales por consola) y se organiza en diferentes niveles jerárquicos superpuestos (usuario, proyecto, local).

En el día a día, settings.json se encarga de definir:

• "En este proyecto, bloquear por completo comandos como rm -rf" → Configurando permissions.deny.
• "Usar Sonnet por defecto en este proyecto para no consumir el presupuesto de Opus" → Configurando model.
• "Ejecutar prettier automáticamente al guardar un archivo" → Configurando hooks.
• "Mostrar la rama actual de git en la barra de estado de la terminal" → Configurando statusLine.

Ninguna de estas son instrucciones dirigidas a Claude en lenguaje natural; son interruptores técnicos que modifican el funcionamiento de la aplicación. Esta es la división fundamental entre settings.json y CLAUDE.md.

💡 Resumen en una frase: CLAUDE.md contiene "instrucciones en lenguaje natural dirigidas a Claude"; settings.json es el "cuadro de mandos con interruptores técnicos que modifican el comportamiento del software". El primero define qué recordar; el segundo, cómo funcionar. No los confundas.

---

02 Tres niveles: Global, en el proyecto o solo en tu máquina

Lo más importante que debes entender sobre settings.json no son sus campos, sino los tres niveles jerárquicos en los que puede existir. Un archivo con el mismo nombre ubicado en rutas distintas tendrá un impacto muy diferente. El error del principio se debió precisamente a no distinguir estos niveles.

Analogía: Dónde colocar un cartel de aviso. Imagina el aviso "Apagar el aire acondicionado al salir". Puedes colocarlo en la puerta de la empresa (afecta a todas las oficinas y proyectos), en la puerta de una oficina específica (afecta solo a ese proyecto y se registra en sus normas de uso) o escribirlo en una nota adhesiva en tu monitor (solo te afecta a ti y los demás no la ven). El ámbito de aplicación varía por completo. Los tres niveles de settings.json funcionan igual.

Revisa los tres niveles en esta tabla (existe un nivel superior llamado Managed, usado en entornos corporativos administrados, que los desarrolladores individuales apenas tocan y que comentaremos brevemente en la siguiente sección):

Nivel	Ruta del archivo	Ámbito	¿Se sube a git?	Contenido recomendado
Usuario (User)	~/.claude/settings.json	Tu usuario, en todos tus proyectos	No (está en tu directorio personal)	Preferencias personales: modelo habitual, tema, barra de estado global
Proyecto (Project)	.claude/settings.json	Todos los desarrolladores de este proyecto	Sí (se incluye en el repositorio)	Reglas del equipo: permisos compartidos, Hooks comunes, MCP del proyecto
Local (Local)	.claude/settings.local.json	Tu usuario, solo en este proyecto	No (se ignora automáticamente)	Anulaciones personales, configuraciones con credenciales de prueba

Quédate con estas tres reglas básicas para elegir el nivel:

• "Lo quiero en todos mis proyectos" → Nivel de Usuario (~/.claude/settings.json). Por ejemplo: "mi modelo preferido es Sonnet" o "el diseño de mi barra de estado". Se configura una vez y se aplica a cualquier repositorio.
• "Es una regla de equipo que debe acompañar al código" → Nivel de Proyecto (.claude/settings.json). Se sube a git para que todos los desarrolladores tengan la misma configuración. Esto es "configuración como código".
• "Es solo para mí, en este proyecto, y no debe subirse a git" → Nivel Local (.claude/settings.local.json).

Aquí hay un detalle de diseño excelente que detalla la documentación oficial: al crear .claude/settings.local.json, Claude Code configurará automáticamente git para ignorarlo.

Claude Code configurará git para ignorar .claude/settings.local.json en el momento de su creación.

¿Por qué este comportamiento? El nivel local está pensado para almacenar información personal: tus pruebas de configuración, accesos con tokens o configuraciones experimentales que no deben subirse al repositorio común. Al forzar la exclusión en git de forma automática, se evita que subas información sensible por error (lo que conecta con la seguridad que vimos en el artículo 21). Evitar la fuga de datos desde el origen es una gran medida de seguridad.

Uso práctico: Distribución en tres niveles de un proyecto real

Veamos un ejemplo de qué información colocar en cada nivel en un proyecto real:

• Usuario: la configuración de tu barra de estado personalizada y tu modelo preferido. Son hábitos que te acompañan a cualquier proyecto.
• Proyecto: reglas en permissions.deny (bloquear curl, prohibir leer .env) y un Hook para pasar el linter antes de confirmar. Son las normas básicas del equipo que deben compartirse en git.
• Local: permisos adicionales que te das a ti mismo para pruebas locales (que tus compañeros no necesitan) o un Hook experimental que aún estás depurando.

Para elegir el nivel de una opción, hazte esta pregunta: "¿esta opción me sirve solo a mí? → Usuario o Local; ¿la necesita todo el equipo? → Proyecto". Y para elegir entre usuario y local: "¿aplica a todos mis proyectos? → Usuario; ¿es exclusiva de este repositorio pero no debe ir a git? → Local".

Un error común es colocar reglas de permisos de un proyecto específico a nivel de Usuario; como consecuencia, al cambiar de proyecto, esas reglas te seguirán acompañando, aplicando restricciones innecesarias en repositorios donde no tienen sentido. Ten claro esto: ¿la configuración me acompaña a mí, o acompaña al proyecto?. Si acompaña al proyecto, guárdala en el proyecto.

💡 Resumen en una frase: Los tres niveles se resumen así: global para todos tus proyectos en ~/.claude/settings.json (Usuario), compartido con el equipo en .claude/settings.json en git (Proyecto), y personal específico del proyecto en .claude/settings.local.json ignorado por git (Local); decide según si la opción te acompaña a ti o al proyecto.

---

03 Prioridad de niveles: Qué opción prevalece y una excepción importante

Es posible definir el mismo campo en los tres niveles. En ese caso, si el nivel de usuario dice usar Opus y el de proyecto dice usar Sonnet, ¿cuál se aplica? De esto se encarga la prioridad (precedencia), un concepto clave de settings.json.

La prioridad oficial se organiza de la siguiente forma, de mayor a menor (los niveles superiores anulan a los inferiores):

Prioridad	Nivel	Descripción
1 (Máxima)	Managed (Administrado)	Directrices de la empresa corporativa, no se pueden modificar
2	Parámetros de consola (--settings, etc.)	Opciones pasadas al iniciar; se aplican solo a esta sesión
3	Local .claude/settings.local.json	Tu configuración personal para este proyecto
4	Proyecto .claude/settings.json	Configuración compartida con el equipo
5 (Mínima)	Usuario (User)	Configuración global por defecto, actúa de respaldo

Esta relación de anulación se puede visualizar como capas superpuestas, donde la capa superior tapa la información de las capas inferiores:

La prioridad va de arriba a abajo: las capas superiores sobrescriben a las inferiores (para campos de valor único). Cuanto más arriba esté la opción en la pila, más específica y temporal es; cuanto más abajo, más general y secundaria, sirviendo el nivel de usuario como el respaldo final si ningún otro nivel define la opción.

Quédate con esta regla: lo más específico prevalece sobre lo general. El parámetro de consola (solo para esta sesión) anula al nivel local (solo para ti en este proyecto), el local al proyecto (para todos en este repositorio) y el de proyecto al de usuario (global). La documentación oficial muestra este ejemplo:

Por ejemplo, si tu configuración de usuario permite Bash(npm run *) pero la configuración compartida del proyecto la deniega, prevalece la del proyecto y el comando se bloquea.

Es decir, los permisos que te des a ti mismo a nivel global pueden ser revocados por la configuración específica de un proyecto. Esto responde a lo que planteamos al final del artículo anterior: una misma opción puede tener efectos opuestos según dónde se defina. El error del principio con defaultMode: "auto" se debió a no comprender esta prioridad de niveles.

El nivel Managed (Administrado) se aplica en entornos corporativos. Son directivas distribuidas a través de MDM, políticas de grupo o servidores de la empresa. Tienen la prioridad máxima y el usuario no puede modificarlas (por ejemplo, para prohibir el uso de curl en toda la red corporativa). Si trabajas por tu cuenta o en equipos pequeños no la verás; te basta con saber que es el "límite superior" del sistema.

La excepción que va contra la intuición: Los arrays se fusionan, no se sobrescriben

La regla de "sobrescribir" aplica a campos de valor único (como model, donde un valor superior reemplaza al inferior). Sin embargo, hay un tipo de configuración que funciona al revés, y donde es muy habitual cometer errores: los campos tipo array (como permissions.allow o permissions.deny) se fusionan entre niveles, no se sobrescriben.

Palabras oficiales de la documentación:

Las configuraciones de tipo array se fusionan entre ámbitos. Cuando el mismo array se define en varios niveles, los arrays se concatenan y se eliminan duplicados, en lugar de reemplazarse.

Básicamente: tus reglas de permisos no se sustituyen por las del proyecto, sino que se suman y aplican juntas.

Veamos un ejemplo para entenderlo:

Escenario	Intuición (errónea)	Comportamiento real (correcto)
Usuario: allow: ["Bash(npm run *)"] Proyecto: allow: ["Bash(git diff *)"]	Prevalece el de proyecto, por lo que solo se permite git diff	Se aplican ambas: se permite ejecutar tanto npm run * como git diff *

Esto es una lógica totalmente distinta a la de los valores únicos. Recuérdala de esta forma:

• Valores únicos (como model, defaultMode): el nivel de mayor prioridad anula por completo al inferior.
• Arrays (como permissions.allow / deny, o la declaración de variables en env): se suman y consolidan entre todos los niveles, sin anularse mutuamente.

Este detalle suele dar problemas: puedes pensar que al escribir una lista de bloqueo deny a nivel de proyecto has anulado una regla de acceso laxo allow del nivel de usuario, cuando en realidad ambas se están sumando. Comprender esto te evitará dejar accesos abiertos sin darte cuenta.

💡 Resumen en una frase: La prioridad sigue la regla "lo específico anula a lo general" (consola > local > proyecto > usuario, con Managed en la cúspide); sin embargo, los arrays (como las reglas de permisos) se fusionan entre todos los niveles, no se sobrescriben.

---

04 Opciones de configuración más habituales: Qué hacen y dónde ponerlas

Con los niveles y la prioridad claros, veamos las opciones de configuración que usarás con más frecuencia. settings.json cuenta con decenas de opciones, pero el 90% del tiempo trabajarás con estas cinco. Explicaremos su función y el nivel más adecuado para guardarlas.

Comencemos con un ejemplo de configuración sencillo pero representativo:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "model": "claude-sonnet-4-6",
  "permissions": {
    "allow": ["Bash(npm run test *)"],
    "deny": ["Bash(curl *)", "Read(./.env)"]
  },
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1"
  }
}

Te recomendamos incluir siempre la primera línea $schema. Enlaza con el esquema JSON oficial de la herramienta, de modo que al editar tu configuración en VS Code, Cursor u otros editores, dispondrás de autocompletado y validación en tiempo real. Si el nombre del campo está mal escrito o el tipo de valor es incorrecto, el editor te lo marcará en rojo de inmediato. Si hubiera usado la línea $schema al principio, el editor me habría avisado del error con defaultMode al instante. Palabras oficiales:

Añadirlo a tu settings.json activa el autocompletado y la validación en VS Code, Cursor y cualquier editor que soporte esquemas JSON.

Analicemos las opciones más comunes:

model: Modelo por defecto

Define el modelo de IA predeterminado para ese nivel. Se introduce el identificador del modelo (como "claude-sonnet-4-6").

• Dónde colocarlo: depende de tu flujo. "Mi preferencia personal es usar X modelo" → Usuario; "el equipo ha acordado usar Sonnet para este proyecto para controlar el gasto" → Proyecto.
• Detalle de funcionamiento: a diferencia de la mayoría de campos, la opción model solo se lee al iniciar la conversación. Si la modificas durante una conversación, tendrás que reiniciar la sesión o cambiar el modelo en caliente con /model. El parámetro --model al iniciar o la variable de entorno ANTHROPIC_MODEL la sobrescribirán temporalmente (ver detalles en el artículo 05).

Esta opción es muy útil para definir modelos por defecto distintos según el proyecto. Por ejemplo, en un proyecto de redacción de documentación técnica donde las tareas no son complejas, puedes configurar en su settings.json a nivel de proyecto el uso de un modelo más ligero. En cambio, en tu proyecto de código principal puedes dejar que use tu modelo global más potente por defecto. De este modo, al entrar en cada proyecto se seleccionará el modelo adecuado automáticamente, optimizando el gasto sin tener que cambiarlo manualmente con /model. Esta es la utilidad práctica de la prioridad de niveles: el proyecto personaliza su entorno, y el usuario actúa de respaldo general.

permissions: Control de accesos y herramientas

Como vimos en el artículo 20, define las reglas allow (permitir), ask (preguntar) y deny (bloquear) para controlar el uso de comandos e inspección de archivos.

• Dónde colocarlo: las medidas de seguridad del equipo (como "bloquear curl" o "bloquear lectura de .env") deben ir a nivel de Proyecto e incluirse en git. Si quieres darte más libertad en tu entorno local, configúralo a nivel Local o de Usuario.
• Recuerda la sección 03: los permisos se organizan como arrays, por lo que se fusionan entre niveles y no se anulan mutuamente al definirse en capas distintas.

env: Variables de entorno en la sesión

Los pares clave-valor definidos en env se inyectarán como variables de entorno en la conversación de Claude Code y en los subprocesos que ejecute.

Analogía: La equipación y credenciales de entrada al taller. Sin importar qué desarrollador acceda a la sesión, al entrar al espacio de trabajo (la conversación) dispondrá de las mismas variables de entorno. env define ese "equipamiento de entrada"; cada comando o subproceso ejecutado por Claude heredará estas variables.

• Uso típico: activar la telemetría (CLAUDE_CODE_ENABLE_TELEMETRY) o definir una variable fija requerida por tus herramientas.
• Dónde colocarlo: variables específicas de la base de código (como la dirección de pruebas del backend) → Proyecto; variables de uso personal global → Usuario.

hooks: Automatización ante eventos

Define el punto de entrada para los Hooks (de los que hablaremos en detalle en el artículo 33) que ejecutan acciones ante eventos, como "formatear el código tras guardar" o "mostrar un mensaje al iniciar".

• Dónde colocarlo: flujos obligatorios del equipo ("ejecutar linter antes de confirmar") → Proyecto; automatizaciones de uso personal → Usuario.
• Explicaremos cómo redactar la lógica de los Hooks en el artículo 33; de momento, quédate con que se configuran dentro del archivo settings.json.

statusLine: Personalización de la barra de estado

Como vimos en el artículo 14, define la información mostrada en la barra inferior de la consola. Puedes personalizar qué mostrar (por ejemplo, enlazando un script para mostrar la rama actual de git, el modelo en uso o el consumo de tokens).

{
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh"
  }
}

• Dónde colocarlo: al ser una preferencia de visualización personal, se guarda casi siempre a nivel de Usuario (~/.claude/settings.json) para usarla en todos tus proyectos.

He resumido la ubicación recomendada para estas opciones en la siguiente tabla:

Opción	Función	Ubicación recomendada
model	Modelo por defecto	Preferencia personal → Usuario; regla de equipo → Proyecto
permissions	Autorización de herramientas	Seguridad básica → Proyecto (en git)
env	Variables de entorno	Específicas del código → Proyecto; globales → Usuario
hooks	Acciones automáticas	Reglas de equipo → Proyecto; flujos personales → Usuario
statusLine	Personalización de barra inferior	Preferencia visual → Usuario

Una confusión común: No todo se guarda en settings.json

Esto es algo que muchos desarrolladores no conocen hasta que se topan con un error. Claude Code utiliza otro archivo de configuración llamado ~/.claude.json (ubicado directamente en tu directorio de inicio; no lo confundas con ~/.claude/settings.json). Este archivo almacena datos de la sesión: tus tokens de inicio de sesión, la configuración de servidores MCP a nivel local o de usuario (artículo 22), el estado de confianza de cada proyecto y datos de caché.

El problema radica en que ciertos campos solo pueden definirse en ~/.claude.json; si los escribes en settings.json provocará un error de validación de esquema. Opciones como autoConnectIde (conexión automática con el IDE) o teammateDefaultModel (modelo predeterminado de los compañeros de equipo) pertenecen a esta categoría.

Si intentas configurar "conectar automáticamente con VS Code" escribiendo la opción en settings.json, verás que el esquema $schema lo marca en rojo y el comando /status devuelve un error. Esa opción debe guardarse en ~/.claude.json. Recuerda esta distinción: settings.json gestiona "interruptores de comportamiento" y ~/.claude.json almacena "datos de sesión, MCP y caché". En el día a día interactuarás casi siempre con el primero, pero ten presente esta regla si una opción da error al escribirla en settings.json.

💡 Resumen en una frase: Las opciones habituales son model (modelo), permissions (permisos), env (variables), hooks (automatizaciones) y statusLine (barra inferior); las reglas de equipo van a nivel de proyecto en git y las preferencias a nivel de usuario, usando $schema para validarlas en el editor. Ten en cuenta que opciones de sesión como autoConnectIde pertenecen a ~/.claude.json.

---

05 Edición, aplicación de cambios y confirmación

Una vez que sabemos qué escribir y dónde, nos quedan tres dudas prácticas: cómo editar la configuración, si es necesario reiniciar la consola para aplicar los cambios y cómo confirmar que Claude ha leído la configuración. Los veinte minutos que perdí al principio se debieron en gran parte a no saber si el sistema estaba leyendo el archivo.

Cómo editar: Archivo directo o comando /config

Dispones de dos vías:

1. Editar directamente el archivo JSON con tu editor → Busca el archivo en la ruta del nivel que corresponda y modifícalo. En CLAUDE.md recomendamos realizar los cambios directamente en el archivo para tener mayor control.
2. Usar el comando /config en la sesión → Abre una interfaz interactiva en la consola para modificar opciones comunes (como el tema visual o el nivel de detalle de las respuestas).

Un detalle importante aclarado por la documentación oficial: la interfaz interactiva de /config no muestra todo el contenido de tu archivo settings.json; está limitada a opciones básicas del sistema. Para gestionar reglas de permisos o Hooks complejos, edita directamente el archivo de configuración.

Cuándo se aplican los cambios: Carga en caliente con dos excepciones

Casi todas las opciones de configuración se aplican en caliente: Claude Code vigila los archivos de configuración y aplica los cambios al guardar, sin necesidad de reiniciar la consola. Palabras oficiales:

Claude Code vigila tus archivos de configuración y los recarga cuando cambian... Esto incluye los permisos (permissions), hooks y asistentes de credenciales.

Existen dos excepciones que solo se leen al iniciar la aplicación; si las modificas, tendrás que reiniciar la sesión o usar su comando específico:

Campo	Cómo aplicar el cambio
model	Reiniciar la sesión, o usar /model en la conversación
outputStyle (estilo de respuesta, artículo 32)	Reiniciar la sesión, o limpiar con /clear e iniciar otra conversación

Esto tiene implicaciones prácticas: si modificas permissions o hooks, el cambio se aplica al guardar y puedes seguir trabajando; si modificas model y no ves cambios, no te preocupes, simplemente requiere reiniciar la sesión para aplicarse. Si mi error inicial hubiera sido con los permisos, lo habría detectado al guardar; al ser con una opción sujeta a restricciones de nivel, tardé más en aislar el problema.

Cómo confirmar que se ha leído: Comando /status y "Setting sources"

Este es el truco definitivo para saber qué archivos de configuración están activos. Escribe /status en la sesión y busca la línea Setting sources: te listará qué niveles de configuración ha cargado la conversación actual (por ejemplo, User settings, Project local settings... los nombres exactos pueden variar según la versión).

La documentación oficial lo aclara así:

La línea Setting sources confirma qué fuentes de configuración se están leyendo... Un nivel de la jerarquía solo aparecerá en la lista si tiene al menos una opción configurada; si la lista está vacía significa que no se ha cargado ninguna fuente de configuración.

Esta regla aporta información muy valiosa:

• Si el nivel que has modificado aparece en la lista, significa que el archivo se ha leído correctamente.
• Si el nivel no aparece, significa que Claude Code no lo detecta (suele deberse a que el archivo está en una ruta incorrecta, por ejemplo, guardando .claude/settings.json en la raíz como settings.json a secas).
• Si el archivo contiene errores de sintaxis (JSON mal estructurado, valores no válidos), el comando /status mostrará un error explícito en la terminal.

Cada vez que configures un settings.json, ejecuta /status para comprobar que aparece en la lista. Esto me habría ahorrado dieciocho de los veinte minutos perdidos.

¿No se aplica la configuración? Guía de autodiagnóstico

Reunimos las causas comunes de error en esta tabla de diagnóstico. Si una configuración no funciona, sigue estos pasos antes de dudar de tu sintaxis:

Síntoma	Descarte inicial	Causa probable a comprobar
Modificas el archivo y no ocurre nada	¿Escribiste mal la opción?	Ejecuta /status y comprueba si el archivo aparece en Setting sources. Si no está, la ruta del archivo es incorrecta.
Cambias el modelo (model) y no se aplica	¿Está mal el nombre del modelo?	El modelo requiere reiniciar la sesión (o usar /model en el chat).
defaultMode: "auto" no funciona	¿Error tipográfico?	El modo automático auto se ignora a nivel de proyecto y local por seguridad; debes configurarlo a nivel de usuario (sección 03).
Creas una regla de bloqueo deny y se puede ejecutar el comando	¿Formato del bloqueo incorrecto?	Los permisos se fusionan entre niveles; comprueba si hay alguna regla allow en otro nivel que lo permita (sección 03).
Un campo da error al guardarlo en settings.json	¿JSON mal estructurado?	Ciertas opciones de sesión (como autoConnectIde) deben ir en ~/.claude.json, no en settings.json (sección 04).

Como ves, casi ningún error se debe a la sintaxis del JSON; la inmensa mayoría de fallos responde a una mala gestión de los niveles, la prioridad, los momentos de aplicación de cambios o la fusión de arrays. Quédate con la idea central del artículo: lo complicado de settings.json no es escribirlo, sino entender su jerarquía de niveles.

💡 Resumen en una frase: Modifica la configuración en el archivo o usa /config (para opciones básicas); los permisos y Hooks se recargan al guardar, mientras que el modelo requiere reiniciar; ejecuta /status tras cambiar la configuración para confirmar que se ha cargado el nivel jerárquico correspondiente; si falla, investiga la prioridad antes de reescribir la sintaxis.

---

06 Práctica: Configurar dos niveles y validar con /status

Pasemos a la práctica. Escribiremos configuraciones en dos niveles distintos y usaremos /status para verificar que se cargan, experimentando el flujo completo de creación, jerarquía y validación de forma sencilla en una carpeta vacía.

Paso 1: Crear una carpeta de prueba (en tu terminal)

mkdir settings-demo && cd settings-demo

Paso 2: Escribir la configuración a nivel de proyecto

Crea el archivo settings-demo/.claude/settings.json e introduce las siguientes reglas de permisos (permitir comandos de prueba, bloquear curl), incluyendo la línea $schema para que tu editor te ayude a validarlo:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": ["Bash(npm run test *)"],
    "deny": ["Bash(curl *)"]
  }
}

Paso 3: Escribir la configuración a nivel local

Crea ahora el archivo settings-demo/.claude/settings.local.json e introduce una regla de uso personal (permitir ver el estado de git) que no deba compartirse con el equipo:

{
  "permissions": {
    "allow": ["Bash(git status *)"]
  }
}

Resultado esperado: has creado configuraciones a nivel de Proyecto y Local. Como explicamos en la sección 02, el archivo settings.local.json será excluido automáticamente en git en el siguiente paso.

Paso 4: Validar que el archivo local se excluye en git

git init -q && git status --short

Resultado esperado: la salida mostrará .claude/settings.json (nivel de proyecto, listo para añadirse al repositorio) pero no mostrará .claude/settings.local.json, ya que el sistema lo ha añadido automáticamente a la exclusión de git. Has comprobado el comportamiento de aislamiento local que vimos en la sección 02.

Paso 5: Iniciar la conversación y verificar la carga con /status

claude

Escribe en el chat:

/status

Resultado esperado: en la información mostrada verás que la sección Setting sources incluye Project local settings (y User settings si tienes configuración global configurada). Ver los nombres en la lista confirma que los archivos se han cargado correctamente. Si alguno falta, vuelve a la sección 02 y comprueba las rutas del archivo.

Paso 6: Comprobar la consolidación de reglas con /permissions

/permissions

Resultado esperado: verás reflejadas las reglas configuradas: se permite npm run test * y git status *, y se bloquea curl *. Observa este detalle: git status * proviene del nivel local y las otras dos del de proyecto, pero se aplican juntas en la conversación, mostrando en la práctica cómo las reglas de permisos se fusionan entre niveles en lugar de sobrescribirse (sección 03).

Al completar este ejercicio habrás comprobado el funcionamiento de settings.json: configurar en varios niveles, aislar la configuración personal, verificar la carga con /status e inspeccionar la consolidación de permisos con /permissions. Cualquier configuración que realices en el futuro seguirá estos mismos pasos.

💡 Resumen en una frase: Practica el flujo básico: crear configuraciones de proyecto y local → verificar la exclusión de git de la local → confirmar la carga de niveles con /status → inspeccionar la fusión de reglas con /permissions; realizar esta prueba te ayudará a asimilar el comportamiento de los niveles y la consolidación de arrays.

---

07 Resumen

En este artículo hemos estructurado la gestión de la configuración en Claude Code mediante settings.json, cubriendo desde su función hasta su jerarquía de niveles y métodos de validación.

Repasemos las ideas clave:

Aspecto	Definición / Comportamiento	Detalle clave
Relación con CLAUDE.md	Herramientas distintas	CLAUDE.md define instrucciones en lenguaje natural; settings.json define el comportamiento de la aplicación.
Niveles jerárquicos	Tres niveles	global en ~/.claude/ (Usuario), compartido en .claude/ en git (Proyecto) y personal local en .claude/settings.local.json (Local).
Resolución de conflictos	Prevalece lo específico	Parámetros de consola > local > proyecto > usuario, con Managed en la parte superior.
Excepción de prioridad	Fusión de arrays	Los arrays de configuración (como los permisos) se suman y consolidan, no se sobrescriben.
Opciones comunes	Cinco habituales	model (modelo), permissions (permisos), env (variables), hooks (automatizaciones) y statusLine (barra de estado).
Método de validación	Comando /status	Comprueba la línea Setting sources para saber qué niveles se han cargado.

Ahora deberías ser capaz de: explicar la diferencia de uso entre settings.json y CLAUDE.md, determinar en qué nivel jerárquico colocar cada opción de configuración, entender cómo se resuelven las prioridades y la fusión de arrays, configurar las opciones más habituales y usar /status para comprobar que la configuración se aplica de forma correcta. Aprender a gestionar los niveles de configuración es la clave para adaptar Claude Code a tu flujo de trabajo y al de tu equipo.

Conocer la jerarquía de niveles te ahorrará dar rodeos al configurar tus proyectos: si algo no se aplica, antes de reescribir la opción, comprueba si está en el nivel jerárquico adecuado ayudándote del comando /status.

---

En el próximo artículo, 32 "Estilos de salida (Output Styles)", nos enfocaremos en la personalización de las respuestas. Hemos mencionado la opción outputStyle en este artículo, indicando que requiere reiniciar la sesión para aplicarse. En la siguiente sección explicaremos detalladamente cómo configurar esta opción para cambiar el tono, estilo y directrices del sistema de Claude, adaptando sus respuestas para que sean más explicativas, directas o adaptadas a tareas de formación según lo necesites. Piensa en esto: ¿cuánto puede variar el tono y el detalle de las respuestas de Claude con solo cambiar el estilo de salida? Lo veremos en el próximo artículo.

---

Lecturas recomendadas

• El sistema de memoria: Cómo hacer que te recuerde a lo largo de las conversaciones
• Plugins: Empaquetar y distribuir configuraciones en un solo módulo
• Introducción a Claude Code