Resolución de problemas y recuperación

Cuando Claude da vueltas en círculos

Un bucle ocurre cuando Claude repite el mismo enfoque fallido: reintenta el mismo comando, reescribe el mismo archivo, o se disculpa y vuelve a cometer el mismo error. Detectar un bucle a tiempo ahorra tokens (las unidades de texto que procesa el modelo) y evita acumular errores.

La salida más rápida es un cambio de alcance: en lugar de pedirle a Claude que repare el conjunto defectuoso, aísle la parte más pequeña que debe funcionar primero. Proporcione a Claude un único archivo, una única función o un único mensaje de error en lugar del contexto completo. Un alcance menor implica menos variables y un camino más corto hacia una respuesta correcta.

Cuando reducir el alcance no es suficiente, cambie por completo el enfoque. Indíquele explícitamente a Claude qué estrategia debe descartar y qué intentar en su lugar. Expresiones como /clear en Claude Code (que reinicia el contexto de la conversación) o iniciar una nueva sesión evitan que los intentos fallidos anteriores influyan en los siguientes.

• Use /clear para borrar la conversación y empezar de nuevo sin perder sus archivos.
• Pegue solo el error o el bloque de código relevante, no todo el proyecto.
• Declare la restricción de forma explícita: Do not touch file X. Focus only on function Y.
• Pida a Claude que explique su plan antes de actuar: Describe your approach in one paragraph, then wait.

Recuperarse de una edición incorrecta

Claude Code edita los archivos directamente en el disco. Si un cambio rompe algo, hay que actuar rápido antes de que el contexto crezca y el estado original sea más difícil de rastrear. Las dos principales vías de recuperación son el revertido con git (cuando el proyecto usa git, un sistema de control de versiones que registra cada cambio en los archivos) y la restauración manual (cuando no lo usa).

Cuando git está disponible, estos comandos cubren la mayoría de las situaciones:

• Ver qué cambió: /git diff dentro de Claude Code, o git diff en una terminal. Muestra cada línea agregada o eliminada desde el último punto guardado (llamado commit).
• Descartar todos los cambios sin confirmar: git checkout -- . (el punto significa "todos los archivos") restablece cada archivo rastreado al último commit. Los archivos nuevos sin rastrear no se tocan.
• Revertir solo un archivo: git checkout -- path/to/file.js restaura únicamente ese archivo.
• Deshacer el último commit pero conservar los cambios en espera: git reset --soft HEAD~1. Úsese cuando el commit ocurrió pero el código sigue siendo incorrecto.
• Deshacer el último commit y descartar los cambios por completo: git reset --hard HEAD~1. Esta operación es destructiva: los cambios se pierden.

Si no hay historial de git, las opciones son más limitadas. Claude Code conserva una transcripción de la sesión, por lo que puedes pedirle que reimprima el contenido original de un archivo que editó y luego pegarlo de nuevo. Para archivos críticos, el hábito más seguro es ejecutar cp important.js important.js.bak antes de comenzar una sesión de edición larga.

También puedes pedirle directamente a Claude Code: "Deshaz la última edición de config.js" o "Revierte todos tus cambios en esta sesión." Claude Code usará git internamente cuando esté disponible, o intentará reconstruir el contenido anterior desde su ventana de contexto (la memoria activa de la conversación).

El contexto se contaminó

Cada conversación con Claude transcurre dentro de una ventana de contexto (el bloque de texto que el modelo puede ver de una vez). Cuando una sesión larga acumula intentos fallidos, instrucciones contradictorias o resultados de herramientas ruidosos, el modelo empieza a dar peso a ese historial deficiente y ofrece peores respuestas. A esto se le llama contaminación de contexto.

Claude Code le ofrece tres niveles de intervención, de menor a mayor impacto:

• Compact (/compact): resume la conversación hasta ese momento en un breve extracto, conserva ese resumen en el contexto y libera espacio. Úselo cuando la sesión sigue siendo productiva pero se está alargando.
• Clear (/clear): borra todo el historial de conversación pero conserva sus archivos de trabajo y la sesión de Claude Code abierta. Úselo cuando el contexto está induciendo activamente a Claude a error, pero quiere permanecer en el mismo proyecto.
• Inicio nuevo (cerrar y volver a abrir Claude Code, o iniciar un nuevo chat): elimina todo el estado de la sesión. Úselo cuando incluso un contexto limpio arrastra suposiciones incorrectas provenientes de los archivos abiertos o del estado de las herramientas.

Una buena regla general: si se encuentra re-explicando algo que ya dijo tres mensajes atrás, primero compacte. Si Claude se contradice o ignora una restricción que usted definió, use clear. Si el modelo parece estar alucinando el contenido de archivos o resultados de herramientas, empiece de nuevo y vuelva a leer explícitamente los archivos relevantes.

Una API incorrecta u obsoleta

Claude se entrena con una instantánea fija del mundo. Cuando le pides que llame a una API (una Interfaz de Programación de Aplicaciones, el contrato que define cómo dos programas se comunican), puede generar código que corresponde a una versión anterior de esa API. Esto se llama una llamada alucinada u obsoleta: el código parece plausible pero fallará en tiempo de ejecución porque el endpoint, el nombre del parámetro o el encabezado requerido ya no existe.

El patrón de fallo suele ser uno de estos:

• Un estado HTTP 404 (no encontrado) o 410 (eliminado), lo que indica que la ruta URL fue retirada.
• Un 422 o 400 (no procesable / solicitud incorrecta), lo que indica que un campo obligatorio cambió de nombre o que un campo obsoleto fue rechazado.
• Un error de autenticación (401/403) porque el formato del token o la clave del encabezado cambió (por ejemplo, algunas API pasaron de Authorization: Token ... a Authorization: Bearer ...).
• Un resultado incorrecto silencioso cuando un campo opcional antiguo ahora se ignora y un nuevo campo obligatorio nunca fue enviado.

La solución es siempre la misma: anclar a Claude en la especificación real y actual antes de pedirle que escriba o depure la llamada. Puedes pegar la sección relevante de la documentación oficial directamente en tu prompt, o apuntar a Claude Code hacia el archivo OpenAPI (descripción de la API legible por máquina) en vivo con /fetch. Nunca confíes en que Claude conozca una API de terceros sin una fuente.

En Claude Code (el agente de codificación por línea de comandos e IDE), el flujo de trabajo es: reproducir el error, recopilar la respuesta HTTP sin procesar, obtener la documentación actual y luego pedirle a Claude que compare su código generado con la especificación real y parchee solo lo que cambió. Mantené la corrección quirúrgica para evitar introducir nuevos errores.

Recibes un error 429

Un error 429 significa "Demasiadas solicitudes." La API (Application Programming Interface, la puerta de enlace que Claude Code usa para conectarse con Claude) tiene un límite de tasa: un techo sobre cuántos tokens (fragmentos de texto) puedes enviar o recibir en una ventana de tiempo determinada. Al alcanzar ese techo, cada solicitud rebota con un 429 hasta que la ventana se reinicia.

Claude Code reporta los errores 429 como un mensaje de error rojo en la terminal. El mensaje generalmente incluye un valor de encabezado Retry-After, que indica exactamente cuántos segundos debes esperar. Si estás en un plan gratuito o de nivel 1, la ventana suele ser de un minuto; en niveles superiores los límites también aplican por hora y por día.

Causas comunes de errores 429 en una sesión de Claude Code:

• Ejecutar un flujo de trabajo multiagente o paralelo que genera muchas llamadas simultáneas
• Usar el pensamiento extendido (valor alto de budget_tokens) en prompts repetidos, lo que consume tokens rápidamente
• Scripts en bucle (como /loop o automatización personalizada) sin pausa entre iteraciones
• Un contexto de base de código grande leído completamente en cada turno en lugar de hacerlo de forma incremental

Para evitar errores 429: lee los archivos de forma incremental con offset y limit, usa el prompt caching (prefija las partes estables de tu contexto para que no se recarguen en cada turno), reduce max_tokens cuando no necesitas respuestas largas, y agrega una breve pausa entre llamadas automatizadas. Para trabajos en lote intensivos, cambia a la Batch API, que tiene un límite de tasa separado y mucho mayor, además de un descuento del 50 % en costos.

Un comando bloqueado

Un proceso bloqueado es aquel que ha dejado de avanzar pero no ha terminado. En Claude Code, esto suele ocurrir cuando un comando shell espera indefinidamente una entrada, una solicitud de red expira en silencio, o una tarea en segundo plano llena un buffer. Saber distinguir entre "lento" y "realmente atascado" evita que interrumpas un trabajo que simplemente necesita más tiempo.

La salida más rápida es Ctrl+C, que envía una señal de interrupción al proceso en primer plano. Si el terminal mismo está congelado, pulsa Ctrl+C dos veces rápidamente. Claude Code cancelará la llamada a herramienta activa y te devolverá el control sin perder el contexto de la conversación.

Para comandos que sabes pueden tardar mucho, ejecútalos como tareas en segundo plano incluyendo run_in_background: true en los parámetros de la herramienta, o sufija el comando shell con &. Recibirás una notificación cuando la tarea finalice en lugar de esperar de forma bloqueante.

• Ctrl+C: interrumpe y cancela la llamada a herramienta activa.
• prefijo timeout: envuelve los comandos arriesgados con timeout 30 <comando> para detenerlos automáticamente tras N segundos.
• indicador background: usa run_in_background para compilaciones largas, servidores o suites de pruebas.
• /stop: el comando slash de Claude Code (los comandos slash empiezan con /) que detiene un bucle de agente en curso sin cerrar la sesión.

Deshacer cambios de forma segura

Git ofrece varios niveles de deshacer, cada uno adecuado para una situación diferente. La clave está en saber cuál elegir para recuperar lo que necesitas sin perder nada más.

git restore descarta las ediciones no confirmadas en tu directorio de trabajo. Ejecuta git restore path/to/file.js para eliminar los cambios no guardados en ese archivo y devolverlo al último estado confirmado. Agrega la opción --staged para quitar un archivo del área de preparación sin tocar las ediciones en disco: git restore --staged path/to/file.js.

git checkout (sintaxis más antigua, todavía muy utilizada) puede hacer lo mismo con un archivo individual: git checkout -- path/to/file.js. También permite saltar a un commit o rama específica, lo cual es útil cuando quieres inspeccionar un estado anterior sin borrar tu trabajo actual.

Cuando creas que has perdido un commit, git reflog es tu red de seguridad. El reflog (abreviación de "registro de referencias") registra cada posición a la que HEAD ha apuntado alguna vez, incluidos los commits "eliminados" por un reset o rebase. Flujo de recuperación habitual:

• Ejecuta git reflog para listar las posiciones recientes de HEAD con sus hashes cortos.
• Encuentra el hash justo antes de que algo saliera mal.
• Crea una nueva rama a partir de él: git checkout -b recovery abc1234.
• Fusiona o haz cherry-pick de lo que necesites de vuelta en tu rama principal.

Cuando empezar de cero

Una sesión de Claude Code acumula contexto (el historial completo de mensajes, llamadas a herramientas y lecturas de archivos que se mantienen en memoria). Cuando ese contexto se vuelve obsoleto, contradictorio o simplemente demasiado grande, continuar la sesión consume más tokens y produce peores resultados que abrir una nueva.

Preste atención a estas señales de que intentar salvar la sesión es la decisión equivocada:

• Bucles repetitivos: Claude sigue sugiriendo la misma corrección defectuosa después de que ya la ha rechazado.
• Confusión de contexto: Claude hace referencia a una ruta de archivo antigua, a una variable eliminada o a un plan que usted canceló explícitamente.
• Presión de tokens: las respuestas se vuelven escuetas, omiten pasos o le advierten que la ventana de contexto está casi llena.
• Fallos de herramientas en cascada: tres o más llamadas consecutivas a herramientas fallan por razones no relacionadas, lo que indica que el estado de la sesión está corrompido y no el código en sí.

Empezar de cero no significa perder su trabajo. Los resúmenes compactos le permiten llevar las decisiones esenciales a la nueva sesión sin el ruido innecesario. Use /compact antes de salir para comprimir la conversación y luego copie el resumen al inicio de su próxima sesión.

La regla práctica: si ha pasado más tiempo discutiendo con la sesión que escribiendo código, reinicie. Una sesión limpia con un prompt de traspaso bien redactado (un párrafo breve que describa lo que se hizo y lo que viene a continuación) es más rápida que mantener viva una sesión defectuosa.