Inicio / Extender: habilidades, MCP, subagentes, hooks, plugins

settings.json en profundidad

Cinco niveles de settings.json se suceden del más fuerte al más débil, una clave escalar común a dos archivos se decide según el nivel más prioritario, pero la mayoría de las listas, entre ellas permissions.allow y permissions.deny, se fusionan entre niveles en lugar de sobrescribirse.

Un settings.json de proyecto reemplaza el del usuario en una clave escalar que ambos archivos definen, y cinco niveles se suceden antes de llegar a este resultado (fuente code.claude.com/docs/en/settings, consultada el 2026-09-02).

Cinco niveles, uno solo gana por defecto

Del más fuerte al más débil: los ajustes gestionados, impuestos por un MDM o por la consola claude.ai; la opción --settings pasada en la línea de comandos, válida para una sola sesión; .claude/settings.local.json, privado del equipo, nunca compartido por git; .claude/settings.json, compartido por git con el resto del equipo en ese proyecto; y por último ~/.claude/settings.json, fijado una vez para todos los proyectos abiertos en ese equipo. Ante una clave simple presente en dos niveles a la vez, el de rango más fuerte se impone por completo, el nivel más débil no se lee. Los ajustes gestionados quedan fuera del alcance de edición desde el puesto de trabajo, impuestos por una organización, mientras que los otros cuatro niveles son simples archivos de texto que cualquiera puede abrir y modificar directamente.

Las listas se fusionan, salvo cuatro claves

La regla cambia en cuanto una clave lleva una lista. permissions.allow y permissions.deny, entre otras, se fusionan entre niveles: una entrada fijada a nivel de usuario sigue activa aunque el proyecto agregue otra al lado. Cuatro claves escapan a esta fusión, cada una según su propia regla en lugar de una regla única. fallbackModel toma el valor completo del nivel más prioritario que la define. modelPicker toma el valor completo del más prioritario entre los ajustes gestionados, --settings y los settings de usuario, e ignora simplemente la clave si solo está fijada a nivel de proyecto o local. availableModels, cuando los ajustes gestionados la definen, se aplica tal cual e ignora lo que agreguen el usuario, el proyecto o el local, y tampoco se fusiona entre varias fuentes gestionadas entre sí. modelSettings se resuelve modelo por modelo, con effortLevel, cada entrada precisando por sí misma qué archivo se aplica a qué modelo.

{
  "permissions": {
    "allow": ["Bash(npm test)"],
    "deny": []
  },
  "env": {
    "NODE_ENV": "development"
  }
}

El bloque env sigue la misma regla

El bloque env insertado en un archivo de ajustes es una clave ordinaria que sigue los mismos cinco niveles que el resto del archivo, pero la mayoría de sus valores, al igual que las reglas permissions.allow, solo entran en vigor después de que cada compañero de equipo haya confiado en la carpeta del proyecto. Una variable de entorno del shell no es un nivel de esta pila: cuando un comportamiento dispone a la vez de una variable y de una clave de ajuste, cuál de las dos se aplica se decide par por par, no por nivel, ANTHROPIC_MODEL exportada en el shell se impone por ejemplo sobre la clave model de cualquier archivo, mientras que ANTHROPIC_DEFAULT_MODEL solo se aplica si ningún archivo fija model.

Esta jerarquía cobra todo su sentido en cuanto entra en juego un hook: la declaración de un evento, como la descrita en los eventos de hook, del desencadenamiento al mensaje, también vive en este mismo archivo, y sigue exactamente el mismo orden de prioridad entre proyecto y equipo personal.