Claude Code viene bien de fábrica. El problema es que los defaults están calibrados para que funcione en la máquina de cualquiera, y tú no eres cualquiera: tienes un proyecto, un stack y una forma de trabajar.
El resultado son fricciones chicas que pagas cien veces al día. Aprobar el mismo comando de pruebas por décima vez. Un build que se muere a los dos minutos porque el timeout es genérico. Un modelo caro corriendo tareas que no lo necesitan.
Estos son los seis ajustes que cambio el primer día en cualquier máquina, con el archivo completo al final listo para pegar.
Dónde vive el archivo
Antes de tocar nada, hay que saber en cuál de los tres archivos escribir. Es la decisión que más gente se equivoca.
~/.claude/settings.json— tuyo, en todos tus proyectos. Aquí van tus preferencias personales: modelo, esfuerzo, atribución de commits..claude/settings.json— del proyecto, se sube a git. Aquí van los permisos del repositorio y todo lo que quieres que aplique igual para tu equipo..claude/settings.local.json— tuyo, en este repositorio, no se sube. Aquí van tus experimentos y lo que solo aplica a tu máquina. Es donde Claude Code guarda solo las aprobaciones de "sí, no vuelvas a preguntar".
Cuando la misma llave aparece en varios, gana el más específico: local le gana a proyecto, y proyecto le gana a usuario. Las reglas de permisos son la excepción: esas se suman en lugar de reemplazarse.
Los 6 ajustes
1. El modelo con el que arranca model
Si no lo defines, cada sesión empieza en el default de tu plan, y ese default rara vez es el que quieres para todo. Fijarlo en tu archivo de usuario evita la decisión diaria; si un proyecto específico pide otro, lo pones en el archivo del proyecto.
Acepta los alias opus, sonnet, haiku y fable, o un identificador completo si quieres anclar la versión exacta. Ojo: esta llave se lee una sola vez al arrancar la sesión, así que a media sesión se cambia con /model.
Qué te ahorra: dinero, si estabas corriendo el modelo más caro para tareas que no lo necesitan.
2. Cuánto piensa antes de responder effortLevel
El nivel de esfuerzo es la palanca de costo más directa que existe y casi nadie la toca. Acepta low, medium, high y xhigh en el archivo de settings. El default es high en casi todos los modelos.
Si tu trabajo diario son ediciones acotadas, medium baja el consumo de forma notoria sin que se sienta. Para las tareas grandes lo subes en el momento con /effort, que también acepta max para la sesión actual.
Qué te ahorra: tokens en cada mensaje del día, no solo en los pesados.
3. Los comandos que ya no te va a preguntar permissions.allow
Esta es la que más tiempo devuelve. Cada comando que apruebas manualmente cinco veces al día es una interrupción que puedes borrar de una vez, escribiéndola como regla en el archivo del proyecto para que aplique también a tu equipo.
La sintaxis es Herramienta(especificador). Un asterisco al final con espacio antes exige límite de palabra: Bash(ls *) cubre ls -la pero no lsof. Y ojo con los comandos compuestos: una regla para Bash(npm test *) no autoriza npm test && rm -rf dist, porque cada parte se evalúa por separado.
Qué te ahorra: las veinte interrupciones diarias que rompen tu concentración y la de Claude.
4. Las carpetas fuera del proyecto permissions.additionalDirectories
Claude Code trabaja dentro de la carpeta desde donde lo abriste. Si tu documentación, tus assets o el repositorio hermano viven un nivel arriba, cada acceso es una negociación.
Declarar esos directorios de una vez resuelve el 90% de los "no puedo leer ese archivo". El matiz que hay que conocer: dar acceso a una carpeta adicional no hace que Claude Code lea la configuración que viva ahí dentro. Da acceso a archivos, no a configuración.
Qué te ahorra: el ida y vuelta cada vez que el contexto que necesita está afuera del repositorio.
5. El timeout de los comandos largos env
Por default, un comando de terminal se corta a los dos minutos. Si tu suite de pruebas, tu build o tu migración tardan más, Claude Code lo ve como una falla y empieza a "arreglar" algo que no estaba roto.
El bloque env aplica variables de entorno a cada sesión y a los procesos que lanza. BASH_DEFAULT_TIMEOUT_MS sube ese piso; hay un techo separado, BASH_MAX_TIMEOUT_MS, que limita lo que el modelo puede pedir por su cuenta.
Qué te ahorra: ciclos completos de diagnóstico falso en proyectos con builds pesados.
6. La firma en tus commits attribution
Por default, los commits llevan un trailer de coautoría y las descripciones de pull request llevan una línea de atribución. En muchos equipos eso está bien. En otros ensucia el historial o rompe una convención de commits.
El objeto attribution tiene tres campos: commit, pr y sessionUrl. Una cadena vacía en los dos primeros oculta la atribución; también puedes reemplazarla por tu propio texto. Reemplaza a la llave vieja includeCoAuthoredBy.
Qué te ahorra: la conversación con el equipo que revisa tus pull requests.
El paso que todo mundo se salta: verificar que el archivo cargó. Un settings.json con una coma de más no da error: simplemente no aparece, y tú te quedas creyendo que tus ajustes están activos. Después de editarlo, corre /status dentro de Claude Code y busca la línea de fuentes de settings: un archivo con JSON roto no se lista aunque exista. Si algo no cuadra, /doctor te dice qué entrada se descartó y por qué.
El archivo completo, listo para pegar
Este va en ~/.claude/settings.json. Cambia los valores a los tuyos y borra lo que no uses.
{
"$schema": "https://json.schemastore.org/claude-code-settings.json",
"model": "sonnet",
"effortLevel": "medium",
"permissions": {
"allow": [
"Bash(npm run test *)",
"Bash(npm run lint *)",
"Bash(npm run build)",
"Bash(git diff *)",
"Bash(git log *)",
"Bash(git status)"
],
"deny": [
"Read(./.env)",
"Read(./.env.*)",
"Read(./secrets/**)",
"Bash(curl *)"
],
"additionalDirectories": [
"../docs/"
]
},
"env": {
"BASH_DEFAULT_TIMEOUT_MS": "300000",
"BASH_MAX_TIMEOUT_MS": "900000"
},
"attribution": {
"commit": "",
"pr": "",
"sessionUrl": false
},
"cleanupPeriodDays": 30,
"spinnerTipsEnabled": false
}La línea de $schema no cambia el comportamiento: le da autocompletado y validación a tu editor, que es la forma más barata de no escribir una llave que no existe.
Las dos últimas son de cortesía. cleanupPeriodDays es cuántos días guarda los archivos de sesión antes de limpiarlos —bájalo si te preocupa el espacio o el historial en disco—, y spinnerTipsEnabled apaga los tips del spinner cuando ya te los sabes todos.
El orden en el que los pondría
No pongas los seis de golpe. Cada ajuste cambia cómo se siente la herramienta y si cambias todo a la vez no sabes qué mejoró.
- Primero los permisos de tu proyecto. Es el que más se nota y el más fácil de calibrar: trabaja una mañana normal y agrega a la lista cada comando que te haya interrumpido dos veces.
- Luego el modelo y el esfuerzo. Baja el esfuerzo un escalón y trabaja dos días así. Si no notaste la diferencia en calidad, quédate ahí.
- Al final los de fricción —timeouts, directorios, atribución—. Son los que arreglas cuando te topas con ellos, no antes.
La mayoría de las llaves se recargan solas al guardar el archivo, sin reiniciar la sesión. Las dos excepciones que vas a notar son model, que se lee al arrancar y se cambia en caliente con /model, y el estilo de salida, que forma parte del prompt del sistema y se reconstruye al reiniciar o al limpiar la conversación.
Si el bloque de permisos te dejó con ganas de más, ahí es donde está el resto del valor: la lista de permitidos y de prohibidos es el ajuste que convierte a Claude Code en algo que puedes dejar corriendo solo. Y si quieres que además arranque sabiendo de tu proyecto, sigue con el archivo CLAUDE.md.