settings.json: qué configura y dónde vive

En el curso anterior, CLAUDE.md y memoria, trabajaste el contexto: lo que el modelo intenta seguir. Este curso es lo que se aplica de verdad, decida lo que decida el modelo. Y todo empieza en settings.json, el fichero de configuración de Claude Code: permisos, hooks, variables de entorno, modelo por defecto.

La diferencia clave: si en CLAUDE.md escribes "no hagas force-push", el modelo normalmente obedece — pero podría no hacerlo. Si lo pones como regla en settings.json, Claude Code no le deja, pase lo que pase. Contexto convence; configuración obliga.

La jerarquía: cuatro niveles y quién gana

Igual que CLAUDE.md, vive en cuatro sitios. El orden de precedencia (de mayor a menor) es:

Nivel	Fichero	¿Se versiona?
Managed (org)	gestionado por IT (`/etc/claude-code/managed-settings.json`, etc.)	manda siempre
Local	`.claude/settings.local.json`	❌ va al `.gitignore`
Project	`.claude/settings.json`	✅ commiteado, lo hereda el equipo
User	`~/.claude/settings.json`	personal, todos tus proyectos

Cuando un ajuste aparece en varios niveles, gana el de mayor precedencia. Y una regla que verás en la lección 2: un deny en cualquier nivel no lo puede revertir un allow de otro inferior.

Anatomía de un settings.json

Un .claude/settings.json de proyecto típico:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": ["Bash(pnpm *)", "Bash(git commit *)"],
    "deny": ["Bash(git push --force*)", "Read(./.env)"]
  },
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1"
  }
}

El $schema no es decorativo: le da autocompletado y validación a tu editor mientras escribes el fichero. Póntelo.

Qué conviene versionar

Versiona lo que define cómo trabaja el equipo en este repo: permisos comunes, hooks del proyecto, variables de entorno no secretas. Commiteas .claude/settings.json y cualquiera que clone arranca con tu misma configuración.

Lo personal (tu modelo preferido, tus overrides) va en .claude/settings.local.json (gitignored) o en tu ~/.claude/settings.json.

Variables de entorno

La clave env fija variables para cada sesión y para los subprocesos que Claude lanza:

{ "env": { "OTEL_METRICS_EXPORTER": "otlp", "MI_FLAG": "value" } }

Nunca pongas secretos (API keys, tokens) en un settings.json versionado: acabarían en git. Para secretos, settings.local.json (gitignored) o el entorno de tu shell.

La mayoría de claves se recargan en caliente al guardar (permissions, hooks, env). Un par necesitan reinicio: model (cámbialo en vivo con /model) y outputStyle.

Qué llevas hasta aquí

settings.json es configuración que se aplica, no contexto que se sugiere.
Cuatro niveles con precedencia; lo del equipo va en .claude/settings.json versionado.
env para variables; nunca secretos en lo versionado.

En la siguiente lección, la clave más importante del fichero: permissions.

Fuente oficial: Settings · Environment variables

¿Quieres llevar la cuenta de las lecciones que has terminado?

Entrar para guardar progreso