Skip to main content
Cuando Claude ignora una instrucción o una característica que configuró no aparece, la causa suele ser que el archivo no se cargó, se cargó desde una ubicación diferente a la que esperaba, u otro archivo la anuló. Esta guía muestra cómo inspeccionar qué cargó realmente Claude Code para que pueda reducir cuál se aplica. Para problemas de instalación, autenticación y conectividad, consulte Troubleshooting installation and login en su lugar.

​
Ver qué se cargó en el contexto

El comando /context muestra todo lo que ocupa la ventana de contexto para la sesión actual, desglosado por categoría: indicación del sistema, herramientas del sistema, herramientas MCP, subagentes personalizados con la fuente desde la que se cargó cada uno, archivos de memoria, skills y mensajes de conversación. Ejecútelo primero para confirmar si su CLAUDE.md, reglas o descripciones de skills están presentes en absoluto. La sección de skills en /context también incluye skills incluidas, que /skills no lista. Para obtener detalles sobre una categoría específica, continúe con el comando dedicado: Si falta un archivo de memoria en el desglose de /context, verifica su ubicación contra cómo se cargan los archivos CLAUDE.md. Los archivos CLAUDE.md de subdirectorios se cargan bajo demanda en lugar de al inicio de la sesión, por lo que no aparecen en ese desglose. Si /context confirma que el archivo se cargó pero Claude aún no sigue una instrucción particular, el problema probablemente sea cómo se escribe la instrucción en lugar de si se cargó. CLAUDE.md funciona bien para el tipo de orientación que daría a un nuevo compañero de equipo, como convenciones de proyecto, comandos de compilación y dónde pertenecen los archivos. La adherencia disminuye cuando una instrucción es lo suficientemente vaga como para interpretarse de múltiples formas, cuando dos archivos dan direcciones conflictivas, o cuando el archivo ha crecido lo suficiente como para que las reglas individuales reciban menos atención. Escribir instrucciones efectivas cubre los patrones de especificidad, tamaño y estructura que mantienen la adherencia alta.
CLAUDE.md y los permisos resuelven problemas diferentes. CLAUDE.md le dice a Claude cómo funciona su proyecto para que tome buenas decisiones. Permisos y hooks aplican límites independientemente de lo que Claude decida. Use CLAUDE.md para “lo hacemos de esta manera aquí”. Use permisos o hooks para límites de seguridad y cualquier cosa que nunca deba suceder, donde necesita una garantía en lugar de orientación.

​
Verificar configuración resuelta

La configuración se fusiona en ámbitos administrados, de usuario, de proyecto y locales. La configuración administrada se aplica primero cuando está presente. Entre el resto, el ámbito más cercano anula el más amplio en el orden local, luego proyecto, luego usuario. Algunos ajustes también se pueden establecer mediante banderas de línea de comandos o variables de entorno, que actúan como otra capa de anulación. Cuando una configuración no parece aplicarse, el valor que estableció generalmente se anula por otro ámbito o una variable de entorno. Para encontrar archivos de configuración inválidos, ejecute claude doctor desde su terminal. Imprime diagnósticos de instalación y configuración de solo lectura sin iniciar una sesión. Para una verificación completa que también propone correcciones y pregunta antes de aplicarlas, ejecute /doctor dentro de una sesión. Ejecute /status para ver qué fuentes de configuración están activas, incluido si la configuración administrada está en vigor. Para entender qué ámbito utiliza Claude Code para una clave determinada, consulte Precedencia de configuración.

​
Verificar servidores MCP

Ejecute /mcp para ver cada servidor configurado, su estado de conexión y si lo ha aprobado para el proyecto actual. Un servidor puede estar definido correctamente pero aún no proporcionar herramientas por algunas razones comunes:
  • Los servidores con ámbito de proyecto en .mcp.json requieren una aprobación única. Si se descartó el mensaje, el servidor permanece deshabilitado hasta que lo apruebe desde /mcp.
  • Un servidor que no se inicia se muestra como fallido en /mcp. Las rutas de archivo relativas en command o args son una causa frecuente, ya que se resuelven contra el directorio desde el que lanzó Claude Code en lugar de la ubicación de .mcp.json.
  • Un servidor que se muestra como conectado pero enumera cero herramientas se ha iniciado correctamente pero no devuelve una lista de herramientas. Seleccione Reconnect desde /mcp. Si el recuento permanece en cero, ejecute claude --debug=mcp y lea la salida stderr del servidor en el registro de depuración en ~/.claude/debug/<session-id>.txt.
Para ubicaciones de configuración y reglas de ámbito, consulte MCP.

​
Verificar hooks

Ejecuta /hooks para enumerar cada hook registrado para la sesión actual, agrupado por evento. Si un hook que definiste no aparece, Claude Code no lo cargó. Comprueba estas causas:
  • El hook está definido en un archivo independiente. Los hooks van bajo la clave "hooks" en un archivo de configuración.
  • El valor de matcher es una matriz en lugar de una cadena única. Claude Code muestra la entrada como un ajuste no válido cuando inicias una sesión interactiva y en claude doctor. Si la matriz está bajo PreToolUse o PermissionRequest, tampoco se carga ninguno de los otros hooks de ese archivo.
Si el hook aparece pero no se dispara, el matcher es la causa habitual. Compruébalo para estos errores:
  • El campo matcher es una cadena única que usa | para coincidir con múltiples nombres de herramientas, por ejemplo "Edit|Write". Un separador , es equivalente, por lo que "Edit,Write" coincide con las mismas herramientas. Antes de v2.1.191, una coma se evaluaba como expresión regular y el matcher nunca coincidía, así que usa | si aún no estás en v2.1.191.
  • Un nombre de herramienta mal escrito produce un matcher que no coincide con nada, por lo que el hook falla silenciosamente.
Cuando editas settings.json, el cambio surte efecto en la sesión en ejecución después de un breve retraso de estabilidad de archivo, incluso si creas el archivo o la carpeta .claude/ del proyecto después de que la sesión comenzó. No necesitas reiniciar. Antes de v2.1.257, Claude Code no detectaba ediciones en una carpeta .claude/ creada después de que la sesión comenzó. Si /hooks aún muestra la definición anterior unos segundos después de guardar, ejecuta /hooks nuevamente para actualizar la vista. Si /hooks muestra el hook pero aún no se dispara, el siguiente paso es ver la evaluación del hook en vivo. Inicia una sesión con claude --debug y activa la llamada a herramienta. El registro de depuración registra cada evento, qué matchers se verificaron, y el código de salida y la salida del hook. Consulta Depurar hooks para el formato del registro y solución de problemas de hooks para patrones de fallo comunes.

​
Probar contra una configuración limpia

Comienza con claude --safe-mode, que inicia una sesión con tus personalizaciones deshabilitadas, incluidos:
  • CLAUDE.md
  • Skills, plugins y hooks
  • Servidores MCP
  • Comandos y agentes personalizados
  • Estilos de salida personalizados
  • Atajos de teclado personalizados
La autenticación, la selección de modelo, las herramientas integradas y los permisos funcionan normalmente. Si el problema desaparece en modo seguro, has reducido la causa a uno de los elementos que desactivaste. Para encontrarlo, usa la comprobación correspondiente a ese elemento, como Ver qué se cargó en el contexto, Comprobar servidores MCP o Comprobar hooks. El modo seguro aún aplica los hooks administrados y la política de configuración de tu organización. Los plugins administrados, skills, CLAUDE.md y servidores MCP están desactivados. Si el problema persiste en modo seguro, o si tu configuración en sí es sospechosa, inicia una sesión sin nada de tu propia configuración y comprueba si el problema continúa.
1

Crea un directorio vacío y entra en él

En tu shell, sin ninguna sesión de Claude Code en ejecución, crea el directorio y muévete a él:
2

Inicia Claude Code con un directorio de configuración limpio

Desde el mismo shell, establece CLAUDE_CONFIG_DIR en un directorio nuevo en lugar de ~/.claude, y pasa --setting-sources user para desactivar la configuración del proyecto, como .claude/settings.json, CLAUDE.md y .mcp.json:
La variable se aplica solo a este lanzamiento.
En el primer lanzamiento, pasas de nuevo por las pantallas de configuración inicial, una señal de que el directorio de configuración limpio está en vigor. La configuración administrada aún se aplica, y los conectores aún se cargan si inicias sesión con una cuenta de claude.ai.
3

Reproduce el problema

Repite en la sesión limpia lo que provocó el problema:
  • El problema desaparece: la causa está en tu configuración de usuario o de proyecto. Copia ~/.claude.json y los archivos de ~/.claude en ~/claude-clean/config uno a la vez. Si ninguno hace que vuelva el problema, ve al directorio de tu proyecto en el mismo shell e inicia Claude Code sin --setting-sources user. En Bash o Zsh, ejecuta CLAUDE_CONFIG_DIR=~/claude-clean/config claude. En PowerShell, la variable sigue establecida, así que ejecuta claude.
  • El problema persiste: la causa está fuera de tu configuración de usuario y de proyecto. Ejecuta /status en la sesión para verificar si hay configuración administrada, revisa las variables de entorno de tu shell y luego consulta Solución de problemas.

​
Verificar causas comunes

La mayoría de las sorpresas de configuración se remontan a un pequeño conjunto de reglas de ubicación y sintaxis. Verifique estos antes de asumir un error: Para una referencia completa en cada superficie de configuración, consulte la página dedicada: