Recuperación de Claude Code: modo seguro, /cd y modelos de respaldo

Material práctico sobre cómo trabajar con agentes: documentación de Ailoot.

¿Qué cambia en Claude Code en junio de 2026?#

Antes, cuando Claude Code empezaba a comportarse de forma extraña —un indicador de carga infinito, un fallo al iniciar, el agente ignoraba las reglas de CLAUDE.md o un hook no se ejecutaba sin avisar—, solo había una salida: comentar manualmente secciones de .claude/settings.json, desactivar los servidores MCP uno por uno o, en el peor de los casos, borrar ~/.claude y reinstalar. En un caso descrito, se borró ~/.claude y se perdió la configuración de los servidores MCP, que había costado hora y media preparar. Más tarde quedó claro que la causa era una línea de CLAUDE.md y que podría haberse encontrado en 10 segundos, pero eso solo se vio después de una recuperación completa.

En junio de 2026, Anthropic incorporó tres mecanismos que cambian este escenario. En resumen, esto es lo que llegó y cuándo:

A continuación se explica cada mecanismo paso a paso, junto con el orden en que conviene aplicarlos cuando una sesión de Claude Code se desvía.

¿Qué suele causar más problemas en Claude Code?#

En el ejemplo descrito, CLAUDE.md empezó con 80 líneas y funcionó durante un mes. En el segundo mes se empezó a notar que una vez por semana Claude infringía todas las reglas establecidas: tocar .env, ejecutar git push --force, curiosear en node_modules. No lo hacía con mala intención: simplemente lo olvidaba. Una vez se borró .gitignore y al principio no quedó claro el motivo. Este escenario se explica con más detalle en la guía sobre CLAUDE.md.

Cuando CLAUDE.md supera las 400 líneas, empieza a causar problemas en silencio: ocupa una parte considerable de la ventana de contexto al iniciar la sesión y diluye las instrucciones importantes entre otras secundarias. Claude sigue leyendo formalmente el archivo, así que desde fuera parece que «las reglas están, pero no funcionan»: una señal típica de un contrato sobrecargado.

Los hooks son la segunda causa más común. Los Claude Code hooks tienen un matiz que Anthropic no destaca.

Es decir, sys.exit(1) en un hook de Python (o cualquier «falló con un error» convencional en Unix) no detendrá a Claude. Solo el código 2 bloquea. En el caso descrito, el hook se consideraba una «prohibición estricta», pero en la práctica registraba una queja y permitía la acción.

Los servidores MCP son la tercera capa, y también pueden fallar a su manera.

A menudo, el síntoma es el mismo: los comandos MCP están disponibles, pero devuelven failed sin un traceback. Para saber más sobre la configuración de MCP y cómo añadir servidores con claude mcp add, consulta la guía independiente.

La cuarta causa es la jerarquía de tres niveles de settings.json. Tienes ~/.claude/settings.json (nivel de usuario), .claude/settings.json en la raíz del proyecto (proyecto), .claude/settings.local.json (local) y, opcionalmente, ajustes administrados por un administrador corporativo. Se combinan según reglas de prioridad. Si alguien añade un servidor MCP a nivel de proyecto y tú tienes una entrada similar con una configuración de inicio distinta a nivel de usuario, se produce un conflicto silencioso que parece que «Claude Code está roto».

¿Cómo funciona --safe-mode y qué desactiva?#

La formulación original de Anthropic en el registro de cambios de v2.1.169 dice:

Anthropic lo aclara en la documentación de configuración del modelo:

Es una herramienta de diagnóstico, no un «entorno limpio». El modo seguro ayuda a responder una pregunta: ¿el problema está en el comportamiento predeterminado de Claude Code o en las personalizaciones añadidas? Esto forma parte de la ingeniería de contexto: gestionar lo que Claude ve y lo que no ve en cada momento. Si todo funciona en modo seguro, queda claro que hay que revisar las capas mediante una búsqueda binaria. Si no funciona, el problema está en la propia instalación, la autorización, la red o la infraestructura; en ese caso, tiene sentido consultar claude doctor y los registros.

Qué desactiva el modo seguro (la lista oficial de Anthropic: 5 capas principales):

• CLAUDE.md en todos los niveles (usuario / proyecto)
• Plugins
• Skills
• Hooks
• Servidores MCP

Qué sigue funcionando:

• La autorización (tu sesión OAuth o clave API)
• La selección del modelo (--model sonnet, --model opus)
• Las herramientas integradas (Read, Write, Bash, Grep, etc.)
• Los permisos
• El estado de git
• Los nombres de directorio

Un detalle importante: el modo seguro no desactiva los ajustes administrados ni las políticas de un administrador corporativo. Si trabajas en un equipo donde Bedrock GovCloud o una configuración MDM establece availableModels, esas restricciones siguen vigentes: el modo seguro solo desactiva tus personalizaciones, no las políticas corporativas.

¿Cómo aislar una capa y encontrar al responsable en 60 segundos?#

Un procedimiento de diagnóstico para cuando Claude Code «ha dejado de escuchar». La versión mínima para todos los comandos siguientes es Claude Code v2.1.169. Si tienes una versión anterior, actualízala primero (npm update -g @anthropic-ai/claude-code o con el instalador nativo de Anthropic).

1. Abre la misma carpeta donde surgieron los problemas.
2. Ejecuta claude --safe-mode.
3. Si se inicia correctamente, comprueba tu solicitud original. ¿Funcionó? Entonces la causa está en una de las capas. Ve al paso 4.
4. Si sigue fallando en modo seguro, no toques las configuraciones. Ejecuta primero claude doctor; comprueba la autenticación, la versión y si hay instalaciones en conflicto.

Cuando el modo seguro se inicie correctamente, activa las capas de una en una, empezando por la causa más probable. Este es el orden basado en la experiencia descrita:

1. CLAUDE.md. Ejecuta claude sin el modo seguro, pero cambia temporalmente el nombre del archivo: mv CLAUDE.md CLAUDE.md.bak. Si funciona, la causa es ese archivo. Después puedes hacer una búsqueda binaria: conserva la mitad de las líneas y comprueba.
2. Hooks. Abre .claude/settings.json y establece temporalmente [] en la sección hooks. Reinicia claude. ¿Funciona? Entonces la causa es uno de los hooks. Actívalos uno por uno.
3. Servidores MCP. Del mismo modo, en ~/.claude.json o .claude/settings.json, establece temporalmente la sección mcpServers como un objeto vacío, reinicia y comprueba.
4. Skills. Mueve .claude/skills/ a una carpeta temporal. Inicia Claude y comprueba.

«Cambiar el nombre temporalmente» significa que los archivos no se borran durante el diagnóstico. mv o git stash permiten restaurarlo todo con un solo comando si esa capa no es la causa.

¿Cómo cambiar la carpeta de trabajo con /cd sin perder el contexto?#

Del registro de cambios de v2.1.169, el 8 de junio:

Por qué resulta útil al solucionar problemas. Supón que estás en la carpeta del proyecto ~/work/myapp y Claude Code se comporta de manera extraña. Antes, la única forma de comprobar «si funciona en absoluto» era cerrar la sesión, ir a otra carpeta y volver a iniciarla. Perdías el contexto, el historial y la caché del prompt ya calentada. Ahora puedes hacer esto:

# In the same session:
/cd ~/sandbox/test

Claude cambia a la nueva carpeta y lee su CLAUDE.md (si existe) como un mensaje, no como reemplazo del prompt del sistema; así se conserva la caché. Si todo funciona en ~/sandbox/test, está claro que el problema estaba en la configuración de ~/work/myapp.

El 12 de junio, v2.1.176 corrigió una regresión molesta: /cd mostraba la rama de git anterior hasta que se reiniciaba por completo. Si tienes una versión anterior, actualízala o ignora git status durante los primeros mensajes después del cambio; se actualizará.

¿Cómo configurar modelos de respaldo para un error 529?#

En el escenario descrito, una vez por semana se ejecuta una tarea larga con Opus en un proyecto; al cabo de 10 minutos, la API devuelve 529 Overloaded y la sesión se bloquea. Antes había que esperar o cambiar manualmente a Sonnet con --model sonnet, perdiendo todo el contexto ya calentado. En una carpeta business/ grande con una estructura de segundo cerebro, esto supone unos veinte minutos de trabajo. Ahora existe un mecanismo adecuado.

La cita exacta de la documentación oficial:

Y, por separado, así funciona la cadena:

Hay dos formas de configurarlo. Desde la CLI:

claude --fallback-model sonnet,haiku

En ~/.claude/settings.json:

{
  "fallbackModel": ["claude-sonnet-4-6", "claude-haiku-4-5"]
}

Hay un matiz aparte sobre los límites de solicitudes. Anthropic no envía deliberadamente un error 429 a través de la cadena, para impedir que se eluda el límite de solicitudes cambiando al siguiente modelo. El respaldo solo funciona cuando el modelo principal está sobrecargado, no está disponible o devuelve un error de servidor no reintentable (por ejemplo, 529 Overloaded). Los límites de solicitudes siguen la lógica habitual de reintentos y espera progresiva.

Otro matiz: el 12 de junio, v2.1.174 corrigió una regresión por la que la compactación no respetaba --fallback-model. Si tienes una sesión larga y se compacta mientras el servicio está sobrecargado, antes de esa corrección no se llamaba al modelo de respaldo. Si trabajas con sesiones largas (/compact, /loop durante la noche), actualiza al menos a v2.1.174.

¿Qué corregir si la causa es CLAUDE.md, un hook, MCP o un skill?#

Estrategias concretas para cada capa.

Si la causa es CLAUDE.md

Abre el archivo y comprueba su tamaño. Según la experiencia descrita, limita el CLAUDE.md activo a un máximo de 200 líneas; mueve el resto a enrutadores y documentos de apoyo junto al proyecto (la estructura completa del segundo cerebro está en la guía sobre el segundo cerebro). Si tiene más de 400 líneas, casi con toda seguridad es la causa. Pasos:

1. Haz una copia de seguridad: cp CLAUDE.md CLAUDE.md.full.
2. Vuelve a una plantilla breve que funcione. Encontrarás una lista para usar en la guía «Cómo configurar CLAUDE.md».
3. Reinicia Claude Code. Comprueba.
4. Si funciona, restaura las reglas en bloques pequeños de 10–20 líneas y comprueba después de cada bloque.
5. Encuentra el bloque que altera el comportamiento. Reescríbelo como un hook con el código de salida correcto (los códigos de salida de los hooks se explican en la siguiente subsección de este H2).

Si la causa es un hook

La pregunta principal es si el código de salida es correcto. Los hooks de Claude Code utilizan:

• Exit 0: todo bien; la acción continúa.
• Exit 1: error, pero no bloqueante. Claude sigue como si no hubiera ocurrido nada.
• Exit 2: error bloqueante. Solo este código detiene realmente la acción.

Si escribiste sys.exit(1) o exit 1 en un hook de shell pensando que bloqueaba la acción, en Claude Code ese código funciona como un aviso en el registro, sin detenerla. Cámbialo a 2. Para conocer los detalles de los hooks y cómo configurarlos sin este problema, consulta la guía independiente.

Otro caso frecuente es que un hook devuelva JSON no válido en stdout. Claude Code analiza la respuesta del hook como JSON y, si contiene algo adicional (un registro, un indicador de progreso, un emoji), considera que el hook ha fallado y la acción continúa. Regla: stdout solo contiene JSON; todo lo demás va a stderr.

El tercer caso es un hook que lee algo de ~/.claude/ que el modo seguro ha ocultado. Es un caso normal. No lo soluciones parcheando el hook: comprueba os.environ.get('CLAUDE_CODE_SAFE_MODE') al principio y termina con el código 0.

Si la causa es un servidor MCP

Síntomas: los comandos MCP están disponibles, pero devuelven failed sin un traceback claro. Pasos:

1. Ejecuta claude mcp list: ¿qué servidores están definidos?
2. Desactiva los servidores de uno en uno en ~/.claude.json: cambia el nombre de la clave claude-server-A a _claude-server-A (así se desactiva sin eliminarla).
3. Reinicia claude. Comprueba qué llamadas funcionan.
4. Cuando encuentres el servidor responsable, revisa su registro: claude mcp logs <name>.
5. Si es un servidor de terceros (@modelcontextprotocol/server-postgres y similares), comprueba si tiene una versión reciente. El ecosistema MCP sigue siendo inestable; los servidores suelen dejar de funcionar con las actualizaciones de Claude Code.

Si te encuentras con «se bloquea al iniciarse y solo cuando hay dos MCP», compara el comportamiento en modo seguro sin MCP.

Si la causa es un skill

Un skill consta de SKILL.md y código en .claude/skills/<name>/. Síntomas: Claude ignora el skill, lo aplica en el momento equivocado o lo aplica pero produce resultados inútiles. Pasos:

1. Abre SKILL.md. Comprueba la descripción: debe tener 1–2 frases y especificar claramente cuándo debe utilizarse. Si dice «un asistente universal para todo», Claude no entiende cuándo debe invocarlo.
2. Comprueba que no haya contradicciones con CLAUDE.md. Si CLAUDE.md dice «escribe siempre pruebas», pero la descripción del skill dice «úsalo para crear prototipos rápidamente sin pruebas», hay un conflicto.
3. Si el skill utiliza comandos externos (npm, python, git), comprueba que estén disponibles en el PATH de todo el sistema. Un skill tiene su propio entorno mínimo.

¿Qué comprobar antes de restablecer una instalación de Claude Code?#

Borrar estado de usuario no es un atajo de diagnóstico. Usa las comprobaciones siguientes para identificar el fallo; si no concluyen nada, conserva las pruebas e investiga. Toda reparación empieza por una copia verificada y mantiene la identidad de cuenta y almacén de credenciales existentes. Orden:

1. claude doctor: diagnóstico automático. Anthropic escribe en su documentación:

2. Comprueba si hay instalaciones en conflicto. Muchas personas tienen instaladas a la vez una versión global de npm y el instalador nativo:

3. Comprueba si ANTHROPIC_API_KEY está interfiriendo con tu sesión OAuth. Es una causa habitual de «nada funciona, la clave ha caducado»:

Solución: ejecuta unset ANTHROPIC_API_KEY en la sesión de shell actual o elimínala de ~/.zshrc / ~/.bashrc.

4. Repara solo la instalación identificada por el diagnóstico y conserva antes todo el estado de usuario. Fallar en modo seguro o recibir un informe inconcluyente de doctor no demuestra que deban borrarse datos. Detén todas las sesiones Claude y otros procesos que escriban antes de crear una copia coherente. Mantén la misma cuenta Unix, HOME, almacén de credenciales del sistema y cuenta Anthropic; no rotes claves ni crees otra identidad.

El ejemplo de copia siguiente es para Linux con GNU tar. En macOS o Windows usa una herramienta que preserve ACL, atributos extendidos, enlaces y metadatos de la plataforma, y verifica la restauración antes de continuar; no supongas que funcionan las opciones exclusivas de GNU. El archivo contiene credenciales y transcripciones: guárdalo privado y fuera de repositorios.

# Run as the same user who owns the Claude state, after stopping writers.
set -eu
umask 077
backup_dir=$(mktemp -d "$HOME/.claude-recovery-XXXXXXXX")
set --
if [ -e "$HOME/.claude" ] || [ -L "$HOME/.claude" ]; then
  set -- "$@" .claude
fi
if [ -e "$HOME/.claude.json" ] || [ -L "$HOME/.claude.json" ]; then
  set -- "$@" .claude.json
fi
[ "$#" -gt 0 ] || exit 1
tar --acls --xattrs --numeric-owner -cpf "$backup_dir/claude-state.tar" -C "$HOME" "$@"
tar --acls --xattrs --compare -f "$backup_dir/claude-state.tar" -C "$HOME"
sha256sum "$backup_dir/claude-state.tar" > "$backup_dir/claude-state.sha256"
(cd "$backup_dir" && sha256sum -c claude-state.sha256)
mkdir "$backup_dir/restore-check"
tar --acls --xattrs -xpf "$backup_dir/claude-state.tar" -C "$backup_dir/restore-check"
tar --acls --xattrs --compare -f "$backup_dir/claude-state.tar" -C "$backup_dir/restore-check"
printf 'Verified recovery directory: %s\n' "$backup_dir"

Todos los comandos deben terminar correctamente. La copia cubre todo el árbol .claude existente, incluidas sesiones ignoradas o sin seguimiento y estado de plugins, y .claude.json, no solo ajustes versionados. Si una ruta es un enlace o los datos están en otra ubicación configurada, detente e incluye el destino resuelto en la misma copia verificada; archivar el enlace no copia su destino. El archivo no incluye Keychain de macOS u otro almacén externo de credenciales, por lo que debes conservar esas identidades.

Si el diagnóstico identifica específicamente la instalación local antigua como la copia en conflicto, mueve solo esa instalación al directorio privado de recuperación en vez de borrar configuración y sesiones:

# Use the verified backup_dir from the previous block.
if [ -d "$HOME/.claude/local" ]; then
  mv "$HOME/.claude/local" "$backup_dir/legacy-local"
fi

Desinstala npm solo si el diagnóstico lo identifica como instalación en conflicto y quieres conservar la nativa. Usa después el instalador nativo documentado, sin borrar .claude ni .claude.json:

curl -fsSL https://claude.ai/install.sh | bash
claude --version
claude doctor

En Windows, el comando de instalación nativa sigue siendo:

irm https://claude.ai/install.ps1 | iex

Restaura por separado. Detén otra vez los procesos que escriben. Comprueba la suma del archivo y extrae en un directorio de recuperación vacío como antes; compáralo correctamente antes de usar sus archivos. Si debes restaurar la instalación antigua movida, confirma primero que no exista $HOME/.claude/local y mueve $backup_dir/legacy-local a esa ruta exacta. Restaura un ajuste diagnosticado desde la extracción verificada solo tras conservar cualquier sustituto actual; no superpongas todo el árbol a ciegas. Sesiones, ajustes MCP e identidad original permanecen conservados. Una instantánea Git por sí sola no cubre transcripciones ignoradas o sin seguimiento, credenciales ni metadatos del sistema de archivos.

¿Qué NO debes hacer cuando Claude Code está roto?#

No cambies las claves antes del diagnóstico

En el 90% de los casos, «la autorización no funciona» se debe a que ANTHROPIC_API_KEY interfiere con la suscripción, a un error de interfaz de un hook o a un fallo de MCP. Rotar las claves no solucionará nada de esto, pero provocará otra hora de interrupción: tendrás que revocar la clave antigua, emitir una nueva, volver a firmar CI con ella y actualizar las variables en producción. Ejecuta primero claude --safe-mode. ¿Funciona? Entonces el problema está en las personalizaciones; no hace falta tocar las claves.

No hagas un restablecimiento completo antes de probar el modo seguro

El modo seguro proporciona un entorno aislado en 1 segundo. Borrar .claude puede destruir sesiones, configuración MCP y otro estado sin seguimiento. Diagnostica primero, verifica una copia privada y utiliza un movimiento reversible solo para la capa de instalación o configuración realmente implicada.

No entres en pánico por un error de interfaz en un hook

Antes de corregir nada, comprueba si el hook realmente se ejecutó (mediante un registro en stderr o una salida explícita), en lugar de fiarte del indicador visual.

No aumentes el código de salida de un hook antes de corregir la lógica

Cuando un hook de bloqueo no bloquea, es tentador establecer exit 2 y darlo por resuelto. Es un parche que funciona, pero oculta otro problema: si el bloqueo no funcionó durante un mes, todo lo que el hook debía prohibir pudo llevarse a cabo. Revisa primero el historial de git y averigua exactamente qué se filtró. Luego añade el bloqueo. De lo contrario, cerrar la puerta no deshace lo que ocurrió antes.

No edites el CLAUDE.md de producción sin protegerte con el modo seguro

En el caso descrito, editas CLAUDE.md, Claude empieza a comportarse de forma extraña, ejecutas git diff y ves que esa misma tarde alguien también añadió al repositorio un servidor MCP y un hook. Culpas a tu cambio, lo reviertes y Claude sigue comportándose de forma extraña. Regla: antes de git revert, ejecuta claude --safe-mode. Si el problema persiste en modo seguro, tu cambio no tenía nada que ver; no hace falta revertirlo.

No creas que «Claude repara su propio MCP»

Un caso típico: pides a Claude que «añada una herramienta determinada al servidor MCP»; Claude reescribe una configuración que funcionaba, todo se rompe y luego Claude pasa varios turnos depurando los daños que él mismo causó, consumiendo la cuota de la sesión. Cuando MCP está roto, obtén la configuración manualmente; no se la dejes al agente. Parte de su arsenal de herramientas también funciona mediante MCP, y un MCP roto implica un diagnosticador roto.

¿Qué hacer después de repararlo?#

Después de analizar el incidente, no vuelvas al trabajo de inmediato. Añade primero medidas de prevención para que no se repita. Un segundo cerebro (la carpeta business/ con la estructura del proyecto) y CLAUDE.md pueden llevar horas de trabajo; restaurarlos manualmente es difícil, y esa es una buena razón para protegerlos. Conjunto mínimo:

1. ~/.claude/settings.json con permissions.disableBypassPermissionsMode: "disable": una prohibición arquitectónica del modo de omisión, para que un --dangerously-skip-permissions iniciado por accidente simplemente no funcione.
2. Hooks para Read(./env*), Bash(git push --force), Write(./node_modules/**): cosas que deben controlarse como reglas obligatorias, no como simples deseos.
3. Configuración del entorno aislado para ejecuciones autónomas largas (/loop, /schedule).
4. /compact con tus propias reglas sobre qué descartar del contexto, para que Claude no se consuma a sí mismo.

El esquema completo de protección en cuatro capas está en la guía «Cómo configurar Claude Code para que no rompa tu proyecto durante la noche». Una guía trata la prevención antes de iniciar /loop; la otra, la recuperación después de que /loop ya haya roto algo. Un par lógico.

Material práctico: documentación de Ailoot.

Más materiales y herramientas: Ailoot.