📋 settings.json: anatomía y ubicación
🧠 Imagínalo así: settings.json es el archivo de configuración técnica de Claude Code. Si CLAUDE.md es el «qué hacer», settings.json es el «cómo funcionar». Controla los permisos, las herramientas y el comportamiento del sistema.
O settings.json existe en dos niveles: ~/.claude/settings.json (global) y .claude/settings.json (por proyecto, dentro del repo). La configuración global define los valores predeterminados personales; la local los ajusta al proyecto específico.
La estructura es JSON puro con claves como allowedTools, permissions, model e env. Cuando existen ambos, el local se combina con el global y las claves locales prevalecen.
~/.claude/settings.json ← global (seu usuario) .claude/settings.json ← projeto (commitavel no git) .claude/settings.local.json ← projeto local (NÃO commitar)
En 1 frase: settings.json (global y local) controla cómo funciona técnicamente Claude Code.
🚫 .claudeignore — qué ocultar
🧠 Imagínalo así: así como .gitignore le dice a git qué no versionar, .claudeignore le dice a Claude Code qué no leer. Protege secretos, reduce el ruido y acelera al agente.
El archivo .claudeignore en la raíz del proyecto usa la misma sintaxis glob que .gitignore. Todo lo que esté listado allí será invisible para Claude Code: no leerá, indexará ni hará referencia a esos archivos.
Patrones recomendados: .env* (secretos), node_modules/ (dependencias), dist/ e build/ (artefactos), archivos binarios grandes y carpetas de vendor. Cuanta menos basura vea Claude Code, más rápido y preciso trabaja.
# Secrets .env* *.pem credentials*.json # Dependências e build node_modules/ dist/ build/ .next/ # Binários e media *.mp4 *.zip *.wasm
En 1 frase: .claudeignore = .gitignore para el agente; protege secretos y reduce el ruido.
🔐 Permisos y allowedTools
🧠 Imagínalo así: los permisos controlan lo que Claude Code puede hacer sin pedir confirmación. Tú decides el equilibrio entre seguridad (pedir permiso para todo) y velocidad (aprobar automáticamente las operaciones seguras).
Por defecto, Claude Code pide permiso antes de ejecutar operaciones potencialmente destructivas: editar archivos, ejecutar comandos bash, etc. Puedes configurar allowedTools en settings.json para aprobar herramientas específicas automáticamente.
Ejemplo práctico: si confías en que Claude Code puede ejecutar npm test e npm run lint sin preguntar, agrega estas herramientas a allowedTools. Esto acelera drásticamente los workflows iterativos en los que el agente necesita ejecutar pruebas repetidamente.
{
"permissions": {
"allowedTools": [
"Read",
"Glob",
"Grep",
"Bash(npm test)",
"Bash(npm run lint)",
"Bash(git status)",
"Bash(git diff)"
]
}
}
En 1 frase: allowedTools controla qué se ejecuta automáticamente y qué requiere permiso.
🌍 Variables de entorno
🧠 Imagínalo así: las variables de entorno son la forma más limpia de pasar configuración sin tocar archivos. API key, modelo predeterminado, flags de comportamiento: todo mediante env vars.
Claude Code reconoce diversas variables de entorno. La más importante es ANTHROPIC_API_KEY, que define la clave de API cuando no usas el inicio de sesión mediante el browser. Otras útiles: CLAUDE_MODEL (modelo predeterminado), CLAUDE_CODE_USE_BEDROCK (usar AWS Bedrock), CLAUDE_CODE_USE_VERTEX (usar Google Vertex).
Para configurar por proyecto sin commitear secretos, usa un archivo .env local (y agrega .env* en .claudeignore). O exporta las variables en tu .bashrc/.zshrc para que se apliquen globalmente.
💡 Nunca hagas commit de API keys
Usa .env local + .claudeignore. O mejor: usa el inicio de sesión mediante el browser (claude sin ninguna variable de entorno) y deja que Anthropic gestione la autenticación. Así no hay ninguna key que pueda filtrarse.
En 1 frase: ANTHROPIC_API_KEY, CLAUDE_MODEL y otras env vars se configuran sin tocar archivos.
👤 Perfiles de proyecto
🧠 Imagínalo así: los distintos proyectos tienen necesidades distintas. Un proyecto personal puede aprobarlo todo automáticamente. Un proyecto corporativo puede exigir confirmación para cada operación. Settings local permite hacerlo.
El settings.json por proyecto (.claude/settings.json) permite que cada repositorio tenga sus propias reglas. Puedes hacer commit de este archivo en git para que todo el equipo use la misma configuración de Claude Code.
En cambio, el .claude/settings.local.json es para personalizaciones que no deben compartirse (como allowedTools más permisivos para quienes ya conocen el proyecto). Nunca debe subirse a git.
En 1 frase: settings.json por proyecto + settings.local.json personal = configuración por contexto.
🔀 Sobrescritura de modelo y proveedores
🧠 Imagínalo así: tú no estás atado a un solo modelo. Claude Code permite cambiar de modelo por sesión o por comando, e incluso usar proveedores alternativos como AWS Bedrock y Google Vertex.
Cambiar de modelo es sencillo: usa --model en la línea de comandos, /model dentro de la sesión, o CLAUDE_MODEL como variable de entorno. Los modelos disponibles son los de la familia Claude: Opus (más capaz), Sonnet (equilibrado), Haiku (rápido y económico).
Para uso corporativo, Claude Code es compatible con AWS Bedrock e Google Vertex AI como providers. Esto permite usar Claude Code con las credenciales y el cumplimiento normativo de tu empresa, sin pasar por la API directa de Anthropic.
# por comando claude --model opus # na sessão interativa /model sonnet # via env var export CLAUDE_MODEL=opus # usando Bedrock export CLAUDE_CODE_USE_BEDROCK=1 # usando Vertex AI export CLAUDE_CODE_USE_VERTEX=1
En 1 frase: usa --model, /model o env vars para cambiar de modelo; Bedrock y Vertex para uso empresarial.
🧾 Resumen del módulo
Siguiente módulo:
1.5 — Memory y contexto persistente: cómo funciona la memoria y cómo no perder el contexto.