← Volver al listado de tecnologías ← Índice de Claude Partner Badge: Claude Code

Capítulo 14 — Jerarquía de configuración y precedencia

10 de octubre de 2026 Por: Artiko

claude-codeanthropicpartner-badgeconfiguracionprecedencia

Jerarquía de configuración y precedencia

Módulo 4 · Configuración y personalización · Lección 1 de 5

Al terminar esta lección sabrás qué ámbito gana cuando dos ajustes entran en conflicto y cuál debes usar en un engagement con un cliente.

Una configuración no encaja en todos los casos. Cuatro ámbitos lo resuelven.

¿Por qué cuatro ámbitos?

Hay cuatro lugares desde los que Claude lee la configuración, y no todos tienen el mismo peso.

Claude Code lee la configuración de cuatro fuentes. Cuando el mismo ajuste aparece en más de un lugar, un orden de prioridad fijo decide qué valor se aplica.

Las cuatro fuentes son Managed (desplegada por TI, la prioridad más alta), Local (sobrescrituras personales del proyecto, ignoradas por git), Project (ajustes compartidos por el equipo y confirmados en el repositorio) y User (valores personales por defecto que te siguen a todos los proyectos). Cada ámbito solo puede ser sobrescrito por algo que esté por encima de él en la cadena. Los permisos son la excepción: las listas de allow y deny se combinan entre ámbitos en lugar de sobrescribirse, de modo que la configuración local de un desarrollador se suma a las reglas del proyecto en lugar de reemplazarlas.

Regla de trabajo

El ámbito es primero una cuestión de propiedad y después una cuestión técnica. ¿Quién controla este ajuste? ¿A quién debe afectar? ¿Puede alguien sobrescribirlo? Si respondes esas tres preguntas, el ámbito correcto se elige solo.

Los cuatro ámbitos

Cada ámbito tiene una ubicación fija y un público definido.

Estos dos datos son lo que necesitas para elegir el ámbito correcto en cualquier engagement con un cliente.

Ámbito	Ubicación	Descripción
Managed	macOS: `/Library/Application Support/ClaudeCode/` · Linux: `/etc/claude-code/`	Desplegada por TI mediante MDM, Group Policy o un archivo de configuración a nivel de sistema. Se aplica a todas las sesiones de la máquina. Ningún ajuste de usuario o de proyecto puede sobrescribirla.
Local	`.claude/settings.local.json`	Sobrescrituras personales para un proyecto concreto. Git la ignora automáticamente cuando Claude Code crea el archivo. Solo te aplica a ti y solo en este repositorio.
Project	`.claude/settings.json`	Ajustes compartidos por el equipo y confirmados en git. Se aplican a todas las personas que trabajan en este repositorio. Úsalo para herramientas permitidas y denegadas, hooks y servidores MCP aprobados.
User	`~/.claude/settings.json`	Valores personales por defecto en todos tus proyectos. Es la prioridad más baja: se aplica cuando ningún ámbito superior ha definido el valor. Úsalo para el modelo preferido, los atajos del editor y las preferencias de notificaciones.

Precedencia

Managed no puede sobrescribirse. User es el último recurso.

Cuando Claude Code resuelve un ajuste, recorre esta cadena de arriba abajo y toma el primer valor que encuentra.

Managed: máxima autoridad. Lo define TI o DevOps mediante un archivo a nivel de sistema. Se aplica a toda la máquina y ningún ajuste de usuario o de proyecto puede sobrescribirlo. Aquí es donde van los requisitos de cumplimiento del cliente.
Flags de CLI: sobrescrituras de sesión. Son los flags que se pasan al iniciar Claude Code, como --allowedTools o --model. Sobrescriben todos los ajustes basados en archivos, pero solo para esa sesión. No se persisten.
Local: sobrescritura personal del proyecto. .claude/settings.local.json en el repositorio. Es tu configuración personal para este proyecto. Sobrescribe los ajustes del proyecto solo para tu sesión, sin modificar el archivo compartido.
Project: base compartida del equipo. .claude/settings.json confirmado en git. Todos los colaboradores del repositorio reciben estos ajustes. Úsalo para los estándares del equipo: comandos preaprobados, hooks y servidores MCP.
User: respaldo personal. ~/.claude/settings.json. Se aplica cuando nada de lo anterior ha definido el valor. Es la prioridad más baja de la cadena.

El siguiente diagrama resume la cadena.

flowchart TD
    S(["Claude Code resuelve un ajuste"]) --> M{"¿Lo define Managed?"}
    M -- "Sí" --> R1["Gana Managed (no sobrescribible)"]
    M -- "No" --> C{"¿Hay flag de CLI?"}
    C -- "Sí" --> R2["Gana el flag de CLI (solo esta sesión)"]
    C -- "No" --> L{"¿Lo define Local?"}
    L -- "Sí" --> R3["Gana .claude/settings.local.json"]
    L -- "No" --> P{"¿Lo define Project?"}
    P -- "Sí" --> R4["Gana .claude/settings.json del proyecto"]
    P -- "No" --> U{"¿Lo define User?"}
    U -- "Sí" --> R5["Gana ~/.claude/settings.json"]
    U -- "No" --> N(["Ningún ámbito lo define"])

Excepción en los permisos

Las listas de allow y deny se combinan entre ámbitos en lugar de sobrescribirse. Una regla allow en settings.local.json se suma a la lista del proyecto. Un desarrollador puede ampliar sus propios permisos en local, pero no puede eliminar una regla deny definida en el ámbito de proyecto o en el gestionado.

Elegir el ámbito

La pregunta no es qué estás configurando, sino quién es el dueño.

En la mayoría de los engagements con clientes, las dos decisiones más importantes son si un ajuste debe viajar con el repositorio y si debe ser privado de un solo desarrollador.

Ámbito	Qué va ahí	Dónde vive
Project · Viaja con el repositorio	Cualquier ajuste que necesite todo el equipo: comandos preaprobados, herramientas denegadas, configuración de servidores MCP y hooks. Se confirma en git, así que cada desarrollador que clona el repositorio lo recibe automáticamente. Lo cambias una vez y se aplica a todos.	`.claude/settings.json`
Local · Se queda en tu máquina	Configuración personal para este proyecto: URLs de sandbox, credenciales de prueba y ajustes experimentales que aún no estás listo para compartir. Se ignora en git automáticamente. No hay riesgo de confirmarlo por error ni de aplicarlo a otra persona.	`.claude/settings.local.json`

Comprueba tu comprensión

Simulación: El despliegue de Meridian

Día 3 de una activación de Claude Code en Meridian Bank. El equipo de seguridad y el equipo de desarrollo tienen requisitos. Tres decisiones, hasta 6 puntos.

Decisión 1 de 3 · Requisito de seguridad

El equipo de seguridad de Meridian Bank quiere bloquear todas las llamadas a curl en las máquinas de todos los desarrolladores. La política debe sobrevivir a que un desarrollador desinstale y vuelva a instalar Claude Code.

¿Qué ámbito aplica ese bloqueo de forma fiable?

A. Ámbito Managed: política distribuida por MDM, sobrevive a la reinstalación.
B. Project .claude/settings.json: lista de denegación en la configuración del repositorio.
C. Ajustes de User: preferencia personal de cada máquina.

Ver respuesta

A. Mejor opción (2 puntos). +2. La capa Managed es la única que los desarrolladores no pueden sobrescribir. La política distribuida por MDM sobrevive a una reinstalación. Los ajustes de proyecto y de usuario se aplican por debajo de ella.
B. Parcial (1 punto). +1. Los ajustes de proyecto cubren un solo repositorio. Un desarrollador con dos repositorios, o una instalación nueva, se salta esto por completo. El ámbito Managed es la capa de cumplimiento que se sostiene.
C. Incorrecta (0 puntos). +0. Los ajustes de usuario viven en una sola máquina y el desarrollador puede cambiarlos. No hay garantía de cumplimiento a nivel empresarial.

Decisión 2 de 3 · Preferencia del desarrollador

Un desarrollador del equipo de Meridian prefiere un modelo distinto para su propio flujo de trabajo. Quiere establecer esa preferencia sin afectar a sus compañeros.

¿Qué ámbito debería usar?

A. Ámbito Local: ~/.claude/ se queda en su máquina, no se confirma.
B. Ámbito User: configuración global, aislada para esa persona.
C. Project settings.json: visible para todo el equipo.

Ver respuesta

A. Mejor opción (2 puntos). +2. El ámbito Local se queda en la máquina del desarrollador y nunca toca el repositorio. Los compañeros no se ven afectados y la preferencia nunca llega al control de versiones.
B. Parcial (1 punto). +1. El ámbito User aísla la configuración a una persona, pero se aplica en todos los proyectos. El ámbito Local es el límite más limpio para una preferencia de una sola máquina.
C. Incorrecta (0 puntos). +0. Los ajustes de proyecto afectan a todas las personas que clonan el repositorio. Las preferencias personales de modelo, si se suben aquí, sobrescriben o entran en conflicto con los estándares del equipo.

Decisión 3 de 3 · Regla de permiso del equipo

El equipo de Meridian quiere preaprobar docker run para su flujo de despliegue, para todos los desarrolladores y no solo para uno.

¿Dónde debe estar esa regla allow?

A. Project .claude/settings.json: viaja con el repositorio y se aplica a todos.
B. Ámbito Local: solo en la copia de trabajo de cada desarrollador.
C. Sin configurar: aprobar manualmente en cada sesión.

Ver respuesta

A. Mejor opción (2 puntos). +2. El ámbito de proyecto es el correcto. La regla allow viaja con el repositorio. Cada desarrollador que lo clona obtiene la preaprobación, y la regla es visible en la revisión de código.
B. Parcial (1 punto). +1. El ámbito Local funciona para un solo desarrollador, pero el resto del equipo seguirá recibiendo avisos en cada ejecución. El ámbito de proyecto es lo que significa «para todos» en la configuración de Claude Code.
C. Incorrecta (0 puntos). +0. La aprobación manual por sesión no escala y genera un comportamiento inconsistente: un desarrollador aprueba y otro rechaza. El ámbito de proyecto resuelve esto desde el origen.

Ver cierre de la simulación

5–6 puntos · Maestro del ámbito. Relacionaste cada necesidad de política con la capa de cumplimiento correcta. Esa precisión es lo que evita sobrescrituras inesperadas en los entornos de los clientes.
3–4 puntos · Instintos sólidos. Acertaste la dirección, pero en al menos una ocasión no distinguiste las capas. Vuelve a leer el flujo de precedencia. La diferencia entre el ámbito de proyecto y el gestionado aparece en la primera semana de un despliegue.
0–2 puntos · Vuelve a leer la jerarquía. La selección del ámbito se relaciona directamente con el límite de cumplimiento y la visibilidad. Cada respuesta incorrecta aquí representa un fallo real de configuración en un engagement.

Ideas clave

Ya conoces el orden. Ahora ponlo en práctica.

Un ámbito es una cuestión de propiedad tanto como técnica. En un engagement con un cliente, la distinción entre managed (no negociable) y project (base del equipo) es donde los requisitos de seguridad se sostienen o se vienen abajo.

Claude Code lee la configuración de cuatro ámbitos: Managed, Local, Project y User. Cuando un ajuste aparece en varios, gana el primer valor de la cadena: Managed, flags de CLI, Local, Project y User.
Managed no puede ser sobrescrito por ningún ajuste de usuario o de proyecto: ahí van los requisitos de cumplimiento del cliente.
Las listas de allow y deny se combinan entre ámbitos. Un archivo local puede añadir reglas, pero no eliminar un deny definido en Project o en Managed.
Elegir el ámbito es una cuestión de propiedad: quién controla el ajuste, a quién afecta y si alguien puede sobrescribirlo.
Project se comparte con el equipo a través de git; Local y User se quedan contigo.

Siguiente: CLAUDE.md: memoria de empresa vs. memoria del repositorio