Depuración de problemas de producción desde tu teléfono

Son las 7 PM de un viernes. Estás cenando con amigos cuando tu teléfono vibra con una alerta de PagerDuty: la tasa de errores en tu servicio de pagos ha subido al 15%. Tu portátil está en casa. Tus compañeros están desconectados. El incidente es tuyo.

Este escenario es la razón por la que Tactic Remote existe. Este tutorial recorre un flujo de trabajo realista de depuración en producción usando solo tu iPhone, demostrando cómo investigar, diagnosticar y corregir problemas de producción de forma remota.

Configuración del escenario

Para este tutorial, trabajaremos con un escenario realista:

• Servicio: API de procesamiento de pagos en Node.js
• Síntoma: Errores 500 en el endpoint /api/payments/process
• Impacto: 15% de los intentos de pago fallando
• Entorno: Logs de producción disponibles vía SSH, código fuente en tu Mac

Tu Mac está encendido en casa, ejecutando la app complementaria de Tactic Remote. Te conectas desde tu iPhone y comienzas la investigación.

Fase 1: Triaje (5 minutos)

El primer objetivo es entender el alcance y la urgencia. Inicia una sesión de Claude Code apuntando a tu directorio de proyecto:

We have a production incident. The /api/payments/process endpoint
is returning 500 errors for ~15% of requests. This started approximately
30 minutes ago.

Help me investigate:
1. Check the git log for any recent deployments (last 24 hours)
2. Look at the payment processing code in src/api/payments/
3. Check if there were any dependency updates recently

Claude Code examinará el código y los cambios recientes. Mientras trabaja, abre tu dashboard de monitoreo en el navegador del teléfono para verificar:

• ¿La tasa de error es estable, creciente o decreciente?
• ¿Están afectadas todas las instancias o solo algunas?
• ¿Hay un patrón en las solicitudes fallidas?

Lo que Claude Code podría encontrar: Un commit de hace 3 horas actualizó la dependencia del SDK de Stripe de v12.1.0 a v13.0.0, que incluía cambios de API incompatibles.

Fase 2: Diagnóstico (10 minutos)

Con una hipótesis (la actualización del SDK de Stripe), profundiza:

Compare the Stripe SDK v12 and v13 changelog.
Check our payment processing code for any API calls that changed
between versions. Focus on the payment intent creation and
confirmation flow in src/api/payments/processor.ts.

Claude Code analizará el código e identificará incompatibilidades específicas. Un hallazgo típico:

Found the issue. In Stripe SDK v13, the `payment_intents.create()` method
changed its error handling behavior:

- v12: Returns { error: { type, message } } for card declines
- v13: Throws StripeCardError exception for card declines

Our code in processor.ts:45-52 checks for `result.error` but doesn't
catch the new exception type. When a card is declined, the uncaught
exception propagates as a 500 error.

This explains the 15% error rate — approximately 15% of payment
attempts involve card declines (expired cards, insufficient funds, etc.)
that now throw uncaught exceptions.

Este diagnóstico es específico, verificable y explica el comportamiento observado. Desde tu teléfono, puedes verificar que tiene sentido antes de proceder.

Fase 3: Corrección (10 minutos)

Ahora implementa la corrección. Tienes dos opciones:

Opción A: Rollback rápido

Si la situación es urgente y la versión anterior era estable:

Revert the Stripe SDK update. Change package.json to pin
stripe at v12.1.0. Create a commit with message:
"hotfix: revert Stripe SDK to v12 (fixes payment 500 errors)"

Paso de aprobación: Claude Code solicitará aprobación para modificar package.json y ejecutar npm install. Revisa los cambios en la tarjeta de aprobación y aprueba.

Opción B: Corrección hacia adelante

Si quieres corregir el código para que funcione con v13 (evitando un revert que pierde otras mejoras):

Fix the payment processing code to handle both the legacy error
response format and the new exception-based error handling in
Stripe SDK v13.

Specifically:
1. Wrap the payment_intents.create() call in a try/catch
2. Catch StripeCardError and convert it to our standard error format
3. Keep the existing result.error check as a fallback
4. Add a test case for the card decline scenario

Commit with: "hotfix: handle Stripe v13 exception-based card decline errors"

Claude Code hará los cambios y ejecutará los tests. Observa la vista del terminal para los resultados.

Flujo de aprobación: Probablemente verás múltiples solicitudes de aprobación:

1. Modificar src/api/payments/processor.ts — Aprobar (esta es la corrección)
2. Modificar src/api/payments/__tests__/processor.test.ts — Aprobar (añadir test)
3. Ejecutar npm test — Aprobar (verificar la corrección)

Fase 4: Despliegue (5 minutos)

Con la corrección commiteada y probada:

Push this commit to the main branch.
Then trigger the deployment pipeline by running our deploy script:
./scripts/deploy.sh production

Aprobación crítica: Claude Code solicitará aprobación para el comando de despliegue. Esta es la acción de mayor riesgo en el flujo de trabajo. Revisa cuidadosamente:

• Verifica que el mensaje del commit corresponde a tu corrección
• Confirma que el destino de despliegue es correcto (production)
• Asegúrate de que los tests pasaron en el paso anterior

Después de la aprobación, Claude Code ejecuta el despliegue. Monitorea la salida del terminal para el progreso del despliegue.

Fase 5: Verificación (5 minutos)

Después de que el despliegue se complete:

Check the deployment status. Then help me verify:
1. Run a test request against the production payment endpoint
2. Check if the error rate has started decreasing
3. Look for any new error patterns in the last 5 minutes

Simultáneamente, verifica tu dashboard de monitoreo en el teléfono. La tasa de errores debería empezar a disminuir a los pocos minutos de completarse el despliegue.

Post-incidente: Escribir el reporte

Mientras el incidente está fresco en tu memoria (aún en la cena, entre platos):

Write a post-incident report based on our investigation:

Include:
- Timeline of events
- Root cause (Stripe SDK v13 breaking change)
- Impact (15% payment failure rate for ~1 hour)
- Resolution (code fix to handle new exception type)
- Action items to prevent recurrence

Format as a markdown document in docs/incidents/

Esto le da a tu equipo un reporte completo del incidente antes del lunes por la mañana. Tus compañeros de cena apenas notaron la interrupción.

Consejos para una depuración remota efectiva

Empieza amplio, luego acota. No saltes a hipótesis inmediatamente. Deja que Claude Code explore el panorama (cambios recientes, patrones de error, estado del sistema) antes de enfocarte en una causa específica.

Usa las puertas de aprobación como puntos de control. Cada solicitud de aprobación es un punto de control natural donde revisas lo que Claude Code está haciendo. Úsalos para verificar que la investigación va por buen camino.

Separa diagnóstico de corrección. Obtén un diagnóstico claro y confirma que tiene sentido antes de implementar cualquier cambio. Esto previene la "caza de correcciones" donde haces cambios sin entender la causa raíz.

Comunica mientras depuras. Si tu equipo tiene un canal de incidentes, publica actualizaciones desde tu teléfono:

• "Investigando errores 500 en pagos. Sospecho actualización del SDK de Stripe."
• "Confirmado: SDK v13 cambió el manejo de errores para rechazos de tarjeta. Desplegando corrección."
• "Corrección desplegada. Tasa de error volviendo a la normalidad."

Esto mantiene a los interesados informados y previene investigaciones duplicadas.

Conoce tus límites. Algunos problemas de producción requieren acceso a infraestructura, consultas de base de datos o depuración a nivel de sistema que no se puede hacer a través de Claude Code. Si llegas a un punto muerto, escala — no pases una hora desde tu teléfono en algo que necesita 5 minutos en una estación de trabajo.

Construyendo tu kit de herramientas para incidentes

Prepárate para los incidentes antes de que ocurran:

1. Pre-configura una sesión de depuración de producción con acceso a tus scripts de despliegue y herramientas de monitoreo.
2. Crea prompts de respuesta a incidentes en tu biblioteca de prompts que Claude Code pueda seguir.
3. Prueba el flujo de trabajo durante una situación no crítica para familiarizarte con el proceso cuando la presión sea real.
4. Asegura el acceso por Cloudflare Tunnel para poder depurar desde cualquier lugar, no solo desde tu red doméstica.

Los incidentes de producción no esperan un momento conveniente. Tactic Remote asegura que, estés donde estés, tengas las herramientas para responder efectivamente.