Depurar la configuración de Claude Code

Cuando Claude ignora una instrucción, o un hook, una skill o un servidor MCP que montaste no hace nada, la causa suele ser una de tres: el archivo no se cargó, se cargó desde un sitio distinto del que esperabas, o lo pisó otro archivo. Claude Code tiene comandos que muestran lo que cargó de verdad, así que puedes dejar de adivinar.

Paso 1: mira qué se cargó

Ejecuta primero /context. Desglosa lo que llena la ventana de contexto: el prompt del sistema, las herramientas, las herramientas MCP, los subagentes, los archivos de memoria, las skills y la conversación. Si tu CLAUDE.md o una skill no sale en la lista, no se cargó. Después usa el comando de lo que busques:

/memory: dónde están tus archivos de memoria, con una forma de abrir cada uno.
/skills: las skills disponibles de las fuentes de proyecto, usuario y plugins.
/hooks: los hooks que están activos.
/mcp: los servidores MCP conectados y su estado.
/permissions: las reglas de permitir y denegar en vigor.
/status: qué fuentes de ajustes están activas, incluido si se aplican ajustes gestionados.
/doctor: una revisión que busca archivos de ajustes inválidos y otros problemas, y propone arreglos.
/debug: activa el registro de depuración de la sesión y le pide a Claude que lo lea.

Los CLAUDE.md de subcarpetas se cargan cuando hacen falta, no al empezar la sesión, así que no salen en /context hasta que Claude lee algo de esa carpeta.

Se cargó, pero Claude lo ignora

Entonces el problema probablemente es cómo está escrita la instrucción, no si se cargó. La documentación señala tres causas: la instrucción es tan vaga que se puede leer de dos formas, dos archivos se contradicen, o el archivo ha crecido tanto que cada regla recibe menos atención. Mira la guía de memoria. Y si algo tiene que pasar siempre, no te apoyes en CLAUDE.md: los permisos y los hooks imponen límites decida lo que decida Claude. Esta guía explica cuál usar.

Ajustes: qué valor gana

Los ajustes se combinan entre los ámbitos gestionado, de usuario, de proyecto y local. Los ajustes gestionados se aplican primero cuando existen. Entre el resto, el local pisa al de proyecto, y el de proyecto pisa al de usuario. Las opciones de línea de comandos y las variables de entorno pueden pisar otra vez. Así que un valor que pusiste a menudo solo está siendo pisado en otro sitio. Ejecuta claude doctor en tu terminal para un diagnóstico de solo lectura, que incluye archivos de ajustes inválidos, sin abrir una sesión. Más en la guía de ajustes.

Servidores MCP que no aparecen

Los servidores del .mcp.json de un proyecto necesitan una aprobación única. Si descartaste el aviso, aprueba el servidor desde /mcp.
Un servidor que no arranca sale como fallido en /mcp. Las rutas relativas en command o args son una causa frecuente, porque se resuelven desde donde lanzaste Claude Code, no desde el archivo .mcp.json.
Conectado pero con cero herramientas: elige Reconnect en /mcp. Si sigue en cero, ejecuta claude --debug=mcp y lee los errores del servidor en el registro de depuración.
Los servidores de proyecto van en un .mcp.json en la raíz del repositorio, bajo la clave mcpServers, no dentro de .claude/ ni en settings.json.

Mira cómo añadir un servidor MCP.

Hooks que nunca se disparan

Ejecuta /hooks. Si tu hook no sale en la lista, no se cargó. Los hooks van bajo la clave "hooks" de un archivo de ajustes, no en un archivo suelto. Si sale en la lista pero nunca se dispara, mira el matcher:

Usa una sola cadena de texto, no una lista JSON. Para varias herramientas, únelas con |, por ejemplo "Edit|Write".
Distingue mayúsculas y minúsculas. Los nombres de herramienta van con mayúscula inicial: Bash, Edit, Write, Read.
Un nombre de herramienta mal escrito no coincide con nada, y el hook falla en silencio.

Para verlo en directo, abre una sesión con claude --debug y provoca la llamada a la herramienta. El registro muestra qué matchers se comprobaron y el código de salida del hook. Mira la guía de hooks.

Otros sospechosos habituales

Los permisos o hooks que pongas en ~/.claude.json se ignoran. Ese archivo guarda el estado de la app. Van en ~/.claude/settings.json, que es otro archivo.
Un valor de settings.json parece ignorado: mira settings.local.json, que lo pisa.
Una skill no aparece en /skills: tiene que ser una carpeta con un SKILL.md dentro, como .claude/skills/nombre/SKILL.md, no un nombre.md suelto. Mira cómo escribir una skill.
Un subagente ignora CLAUDE.md: los agentes integrados Explore y Plan lo saltan al arrancar, así que repite la instrucción en tu petición. Para un subagente propio, pon las instrucciones críticas en el archivo del agente. Mira cómo escribir un subagente.
Una regla de denegar Bash(rm *) no frena /bin/rm ni find -delete, porque las reglas de Bash comparan el texto literal del comando. Para una garantía firme, usa un hook o el sandbox. Mira la guía de permisos.

Prueba con una configuración limpia

Empieza con claude --safe-mode. Abre una sesión con tus personalizaciones desactivadas: CLAUDE.md, skills, plugins, hooks, servidores MCP, comandos y agentes propios, estilos de salida y atajos de teclado. El inicio de sesión, la elección de modelo, las herramientas integradas y los permisos funcionan con normalidad, y la política gestionada de tu organización sigue aplicándose. Si el problema desaparece, es una de las cosas que se apagaron, y puedes revisarlas una a una con los pasos de arriba.

Si persiste, empieza sin nada de tu propia configuración. En un directorio vacío, apunta Claude Code a una carpeta de configuración nueva y desactiva los ajustes de proyecto:

CLAUDE_CONFIG_DIR=~/claude-clean/config claude --setting-sources user

En PowerShell, define antes $env:CLAUDE_CONFIG_DIR = "$HOME/claude-clean/config". Se queda definida en esa ventana hasta que ejecutes Remove-Item Env:CLAUDE_CONFIG_DIR. Espera ver otra vez las pantallas de primera configuración; eso indica que se usa la carpeta limpia. Si allí el problema desaparece, copia tus archivos uno a uno para encontrar al culpable. Si sigue, la causa está fuera de tu configuración propia, por ejemplo en ajustes gestionados o en una variable de entorno.

Bueno saber

Esta página trata de configuración. Los problemas de instalación y de inicio de sesión tienen sus propias páginas de solución de problemas.
Algunos comandos y arreglos dependen de tu versión, así que ejecuta claude --version y mira la documentación si falta alguno.

Pruébalo con algo inofensivo

Ejecuta /context y busca tu CLAUDE.md en la lista.
Ejecuta /doctor y lee lo que informa.
Ejecuta claude --safe-mode una vez y fíjate en lo que falta.

Esta página sigue la documentación de Anthropic sobre depurar tu configuración tal como la leemos en octubre de 2026. No tenemos relación con Anthropic. La escribimos a partir de la documentación y no hemos probado todos los casos. Donde esta página y la documentación no coincidan, manda la documentación.

Mira también: Arreglar «command not found: claude».

La skill gratis loop-stop da a las tareas largas un límite y una regla de parada. Si quieres una segunda mirada a tu CLAUDE.md y a tus ajustes, el Tune-Up Kit es una lista de comprobación para eso (la ficha está en inglés).