# Búsqueda y resolución de bugs con Claude Code: guía práctica

> Guía práctica completa sobre depuración de código con Claude Code: análisis de stack traces, revisión de logs de servidor, resolución de errores de TypeScript, reparación de tests y optimización del rendimiento.

## 1. Por qué la depuración con Claude Code supera los métodos manuales

El proceso tradicional de localización de errores suele ser una rutina agotadora: el desarrollador pasa horas examinando densos volcados de stack trace en la terminal, insertando manualmente decenas de `console.log` o puntos de interrupción y tratando de reconstruir el estado mental de múltiples módulos a la vez.

Claude Code transforma este enfoque de forma radical: con acceso directo al sistema de archivos local, el agente puede seguir el hilo de ejecución desde los componentes de la interfaz de usuario hasta los endpoints del backend y las consultas a la base de datos en cuestión de segundos.

```mermaid
flowchart TD
    A["Síntoma: Error en tiempo de ejecución o log de fallo"] --> B["Claude Code CLI"]
    B --> C["Análisis del Stack Trace e identificación de archivos"]
    C --> D["Read & Grep sobre la base de código"]
    D --> E["Localización del origen del problema"]
    E --> F["Formulación de hipótesis y propuesta de parche"]
    F --> G["Ejecución automatizada de pruebas / build"]
    G -->|Éxito| H["Commit limpio de la solución"]
    G -->|Fallo| E
```

### Comparativa entre depuración manual y Claude Code

| Criterio | Depuración manual tradicional | Depuración con Claude Code |
| :--- | :--- | :--- |
| **Localización del fallo** | Navegación manual por cada línea del stack en el IDE | Correlación autónoma del error con la arquitectura del proyecto |
| **Revisión de logs** | Lectura visual de miles de líneas de texto plano | Análisis automático de logs estructurados mediante tuberías CLI |
| **Trazabilidad cruzada** | Mantener en mente el grafo de llamadas de 5 a 10 archivos | Rastreo semántico paso a paso de los flujos de datos |
| **Errores de TypeScript** | Tentación de forzar soluciones con `as any` | Estrechamiento de tipos seguro (Type Narrowing) y defensivo |
| **Verificación** | Reinicios manuales continuos del servidor o de los tests | Ejecución cíclica autónoma de pruebas hasta el 100% de éxito |

> [!NOTE]
> Claude Code no sustituye el criterio del desarrollador, pero reduce el intervalo entre la aparición del problema y la identificación de la causa raíz entre 3 y 5 veces.

---

## 2. Anatomía de un informe de error óptimo para un asistente de IA

La rapidez y precisión con la que Claude resuelva una incidencia dependen de la calidad de la información facilitada en el prompt inicial.

### Petición imprecisa frente a informe de ingeniería estructurado

> [!WARNING]
> **Petición ineficaz:**
> *«La aplicación no funciona, el formulario de registro falla, mira qué pasa.»*
> 
> Con esta descripción, el agente se ve obligado a conjeturar a ciegas a través de decenas de archivos, consumiendo el contexto en suposiciones.

> [!TIP]
> **Informe de ingeniería profesional:**
> *«Al enviar el formulario en `/register`, el cliente recibe un error HTTP 500. La consola del navegador muestra: `TypeError: Cannot read properties of undefined (reading 'email')`. El cuerpo de la petición envía un JSON con los campos `username` y `mailAddress`. Revisa el esquema de validación en `src/api/auth.ts` y alinea los nombres de las propiedades.»*

### Cuatro elementos esenciales de un informe de error eficaz

1. **Comportamiento esperado (Expected Behavior):** Qué debía ocurrir en condiciones normales de funcionamiento.
2. **Comportamiento real (Actual Behavior):** El mensaje de error exacto, el código HTTP devuelto o el valor erróneo obtenido.
3. **Pasos para reproducir (Reproduction Steps):** Qué botones se pulsaron, qué parámetros URL se enviaron o qué payload se transmitió.
4. **Contexto y rutas de archivos (Context & File Paths):** En qué página, componente o servicio del backend se manifiesta la anomalía.

---

## 3. Análisis de Stack Traces y mensajes de error en tiempo de ejecución

Puedes proporcionar los stack traces y mensajes de error en bruto directamente a Claude Code. El agente descartará el ruido de dependencias externas (`node_modules`) y se centrará en el código de tu repositorio.

### Paso de un volcado de error en crudo

```text
I am getting this runtime error when rendering the user table:

TypeError: Cannot read properties of undefined (reading 'map')
    at UserTable (src/components/UserTable.tsx:34:22)
    at renderWithHooks (node_modules/react-dom/cjs/react-dom.development.js:15486:18)
    at mountIndeterminateComponent (node_modules/react-dom/cjs/react-dom.development.js:20103:13)

What is causing this, and how should we properly handle loading and empty states?
```

### Cómo aborda Claude esta incidencia

1. **Lectura focalizada:** abre `src/components/UserTable.tsx` en la línea 34 mediante la herramienta `Read`.
2. **Auditoría del origen de datos:** examina las props y hooks de estado (`useState`, `useQuery`) para descubrir por qué el array de usuarios se evalúa como `undefined` al renderizar.
3. **Corrección defensiva:** implementa encadenamiento opcional (`users?.map(...)`), un estado de carga visual (Skeleton/Spinner) o valores de respaldo seguros (`users = []`).

---

## 4. Análisis de logs de servidor mediante tuberías de consola (CLI)

Para diagnosticar caídas del backend en entornos de desarrollo o servidores de staging, Claude Code se conecta con naturalidad a los flujos estándar de Unix.

### Canalización de logs hacia Claude Code

```bash
# Enviar las últimas 100 líneas del log de Nginx a Claude para un diagnóstico instantáneo
tail -n 100 /var/log/nginx/error.log | claude -p "Find critical errors and explain their root cause. Provide actionable fix instructions."

# Diagnosticar caídas de contenedores directamente desde Docker
docker logs --tail 200 api-service 2>&1 | claude -p "Analyze database connection failures and timeout exceptions."
```

### Auditorías interactivas de archivos de log

En una sesión interactiva, puedes dirigir al asistente hacia un archivo guardado:

```text
Read logs/production-error.log and focus on entries with status 500 from the last two hours. Group related exceptions and trace which external service call failed.
```

Claude agrupará los patrones repetitivos de fallo, detectará pérdidas de autenticación con APIs externas o identificará el agotamiento del pool de conexiones a la base de datos.

---

## 5. Instrumentación estratégica: registro diagnóstico y trazabilidad

Los defectos más complejos son los silenciosos (Silent Bugs): la aplicación no arroja excepciones, pero los datos calculados son erróneos (por ejemplo, el total del carrito muestra `$0.00` en vez de `$42.50`).

Para estos escenarios se aplica la instrumentación estratégica.

### Secuencia metodológica de investigación

1. **Instruir a Claude para colocar logs diagnósticos:**
   ```text
   The order total calculation is returning 0 for items with promo codes. Add targeted diagnostic logging to calculateOrderTotal and its call sites to log input arguments, discount factors, and return values.
   ```
2. **Reproducir el error en el entorno de pruebas:** ejecuta el proceso de compra aplicando un cupón.
3. **Facilitar los logs diagnósticos resultantes a Claude:**
   ```text
   Here is the diagnostic log from the checkout attempt:
   [DEBUG] Item subtotal: 42.50
   [DEBUG] Promo code applied: 'SPRING20' -> parsed discount: '0.2' (string)
   [DEBUG] Applying formula: 42.50 * (1 - '0.2') -> NaN -> coerced to 0

   What went wrong?
   ```
4. **Resolución y limpieza:**
   Claude identificará inmediatamente la discordancia de tipos (cadena en lugar de número), corregirá la función de parseo y **eliminará de forma autónoma todos los logs temporales**.

---

## 6. Resolución rigurosa de errores de tipos en TypeScript

Los mensajes del compilador de TypeScript resultan a veces crípticos, en especial al manipular genéricos, uniones complejas o estructuras anidadas.

### El peligro de silenciar al compilador

Recurrir con prisas a aserciones de tipo forzadas (`as unknown as TargetType`) enmascara el fallo en fase de compilación, provocando caídas inesperadas en producción.

:::tabs
@tab Enfoque Inseguro (Type Assertion)
```typescript
// Mal: la aserción forzada oculta el fallo real
const userEmail = (response.data as any).user.email;
// Si user es null en producción, la aplicación fallará con un crash!
```
@tab Estrechamiento de Tipos Seguro (Type Narrowing)
```typescript
// Bien: guardas de tipo defensivas que garantizan seguridad total
if (!response.data || typeof response.data !== 'object' || !('user' in response.data)) {
  throw new Error('Invalid API response structure');
}
const userEmail = response.data.user?.email ?? 'anonymous';
```
:::

### Instrucción a Claude para una solución limpia

```text
I am encountering this TypeScript compiler error in src/services/payment.ts:48:

Type 'string | undefined' is not assignable to type 'string'.
Type 'undefined' is not assignable to type 'string'.

Fix this issue properly using strict type narrowing or safe fallback values. Do NOT use type assertions ('as') or 'any'.
```

Claude trazará el ciclo de vida de la variable e implementará las validaciones oportunas ante valores ausentes.

---

## 7. Reparación automatizada de pruebas y compilaciones en bucle

Una de las facultades más destacadas de Claude Code es su capacidad de operar en un bucle autónomo de «Ejecución → Diagnóstico → Parche → Verificación».

```mermaid
flowchart TD
    A["Comando: 'Fix all failing tests'"] --> B["Ejecución de npm test mediante Bash"]
    B --> C{"¿Pasaron todos los tests?"}
    C -->|Sí| D["Informe de ejecución exitosa"]
    C -->|No| E["Análisis de fallos en el informe del test runner"]
    E --> F{"¿Dónde está el error: en código o test?"}
    F -->|En código| G["Corrección de la lógica de negocio"]
    F -->|En test| H["Actualización de aserciones obsoletas del test"]
    G & H --> B
```

### Plantillas de comandos para auto-reparación

:::tabs
@tab Pruebas Unitarias (Jest / Vitest)
```text
Run the test suite with npm test. For each failing test:
1. Determine if the failure is caused by a real bug or an outdated test expectation.
2. Fix the underlying issue cleanly.
3. Re-run tests until all test suites pass.
```
@tab Fallos de Compilación
```text
Run npm run build. Inspect the compiler and bundler error output. Fix all type and syntax errors, then verify with a clean build.
```
@tab Linters y Estilo (ESLint)
```text
Run npx eslint src/ --max-warnings=0. Fix all reportable style and syntax errors without disabling ESLint rules.
```
:::

---

## 8. Detección de cuellos de botella de rendimiento y consumo de recursos

Un defecto no siempre se manifiesta como un crash. Tiempos de carga prolongados, saturación de la base de datos o bloqueos del hilo principal son bugs severos de rendimiento.

### Solicitud de auditoría de rendimiento

```text
The /dashboard page takes over 6 seconds to load. Analyze the server-side data fetching and client components:
1. Check for N+1 query patterns in our Prisma calls.
2. Identify missing database indices on frequently queried foreign keys.
3. Look for unnecessary client component re-renders caused by unstable object references.
```

### Qué audita Claude durante las revisiones de rendimiento

- **Consultas N+1:** sustituye bucles de peticiones a la base de datos por consultas por lotes (operador `IN` o cláusulas `include`).
- **Memorización en React:** detecta cómputos pesados sin `useMemo` o manejadores de eventos inestables sin `useCallback`.
- **Sobrecarga de datos (Payload Bloat):** añade paginación (`limit`/`offset`) o proyecciones selectivas (`select: { id: true, name: true }`) en vez de descargar tablas completas.

---

## 9. Taller práctico: investigación y corrección de un bug de producción

Analicemos un caso habitual: los clientes notifican que al aplicar un cupón del 15% en un carrito con tres productos, el importe cobrado difiere del esperado.

### Paso 1. Localización del módulo de cálculo

Inicia Claude Code y encuentra el archivo responsable:

```text
Find where the cart discount calculation is implemented and inspect the file.
```

Claude utilizará `Grep` sobre la palabra `discount` y abrirá `src/domain/cart.ts`.

### Paso 2. Inspección del código defectuoso

```typescript
// Fragmento detectado en src/domain/cart.ts:
export function applyCoupon(total: number, discountPercent: number): number {
  return total - total * (discountPercent / 100);
}
```

A primera vista la fórmula parece adecuada. No obstante, la aritmética de punto flotante en JavaScript introduce imprecisiones: `100 - 100 * (15 / 100)` genera `85.00000000000001`, lo que provoca que pasarelas de pago como Stripe (que requieren importes en céntimos enteros) rechacen la operación.

### Paso 3. Solicitud de corrección y batería de pruebas

```text
In src/domain/cart.ts, the applyCoupon function causes floating-point precision issues that fail payment validation. Refactor it to calculate prices in integer cents, add rounding via Math.round, and create a comprehensive unit test in src/domain/cart.test.ts covering edge cases.
```

### Paso 4. Verificación de la solución

El asistente ajusta la función para operar en céntimos enteros:

```typescript
export function applyCouponInCents(totalCents: number, discountPercent: number): number {
  const discountAmount = Math.round(totalCents * (discountPercent / 100));
  return Math.max(0, totalCents - discountAmount);
}
```

A continuación, Claude ejecuta `npm test src/domain/cart.test.ts` con `Bash` y ratifica que todas las pruebas se superan con éxito.

---

## 10. Autoevaluación rápida y lista de verificación final de depuración

Comprueba los conocimientos asimilados a lo largo de esta guía.

### Preguntas de repaso

> **1. ¿Cuál es el procedimiento más ágil para diagnosticar una incidencia en un servidor de staging mediante Claude Code?**
>
> > [!TIP]
> > **Respuesta:** Enviar el final del log en bruto directamente al modo print de Claude Code mediante una tubería de consola: `tail -n 150 /var/log/app.log | claude -p "Find errors and diagnose causes"`.

> **2. ¿Por qué es fundamental prohibir el uso del operador `as` al encomendar a Claude la corrección de fallos de TypeScript?**
>
> > [!TIP]
> > **Respuesta:** Las aserciones con `as` únicamente acallan las alertas del compilador, pero no evitan que la aplicación se detenga por excepciones en tiempo de ejecución. Debe requerirse un estrechamiento de tipos riguroso (Type Narrowing) y valores por defecto.

> **3. ¿Cómo debe articularse la resolución de múltiples tests fallidos tras una refactorización amplia?**
>
> > [!TIP]
> > **Respuesta:** Lanzar Claude Code en modo bucle con la directriz de ejecutar los tests, distinguir entre aserciones desfasadas y errores reales de lógica, subsanar los fallos y reiterar la ejecución hasta alcanzar el 100% de éxito.

### Lista de verificación para la caza sistemática de bugs

- [ ] Proporcionar los 4 datos clave: Comportamiento esperado, Comportamiento real, Pasos de reproducción y Rutas de archivos.
- [ ] Entregar los stack traces íntegros sin recortes — Claude filtra automáticamente el ruido de paquetes externos.
- [ ] Aprovechar las tuberías Unix (`tail | claude -p`) para auditar logs de servidor de forma inmediata.
- [ ] Exigir estrechamiento de tipos seguro en TypeScript evitando el casteo forzado con `as any`.
- [ ] Solicitar la creación de pruebas unitarias de regresión por cada fallo solucionado.
- [ ] Purgar los logs diagnósticos temporales antes de realizar el commit definitivo en Git.