Claude Code entregó un bug. Lo hice imposible en 4 arreglos

Claude Code entregó un bug de numeración en un repo real, y cuatro cambios aprobados a mano hicieron imposible volver a entregarlo. La sesión escribió notas de crédito para una API de facturación pequeña, la suite de tests salió en verde, y una comprobación hecha después a mano mostró que una petición rechazada había quemado un número de factura. Entonces ejecutamos una retro sobre esa sesión, aprobamos los arreglos uno por uno y repetimos la misma tarea: salió limpia.

Una retro es la revisión que un equipo hace después de un incidente, aquí aplicada al log de sesión del propio Claude Code. Nuestra primera retro empezó con "This session was smooth", y ninguno de sus hallazgos era el bug. La solución son siete gestos, en orden: instalar, ejecutar la tarea, ejecutar la retro y decirle qué falló, rastrear cada candidato, aprobar cada superviviente en un soporte, hacer commit y auditar, y repetir la tarea.

/retro es un skill de Matt Pocock que revisa una sesión de código en lugar de tu código. Lee el log de sesión, el archivo donde Claude Code guarda cada prompt y cada llamada a una herramienta, y busca candidatos en siete categorías, por ejemplo una comprobación que podría haber atrapado un error. Los presenta por gravedad y, según su doc, solo propone: nada cambia hasta que eliges un candidato.

Instalarlo es el primer gesto: en tu repo, actualiza el marketplace oficial y luego instala el pack de skills a nivel de proyecto, para que viva solo en ese repo. Nuestro marketplace estaba fijado a una versión anterior sin la retro, así que la actualización fue lo primero. En una sesión nueva, escribe una barra y el comando de la retro aparece en la lista.

Un límite: una sesión en la nube no puede leer los logs de tu máquina, así que ejecuta la retro donde ocurrió la sesión.

El segundo gesto es el que ya haces cada día: escribe tu tarea real en una sesión normal, deja que termine y mantén la sesión abierta, porque es lo que la retro va a leer.

Usamos una API de facturación pequeña en Node y TypeScript, con su propia suite de tests y sin archivo de instrucciones, sin pipeline ni hook de commit en ningún sitio. La tarea era corta, como la escribirías tú: añadir notas de crédito a las facturas pagadas, numeradas en secuencia, y permitir anular una factura pagada acreditando lo que queda.

La sesión escribió la ruta, una migración y sus propios tests, y ejecutó la suite antes de parar. Luego ejecutamos la comprobación que haría finanzas a mano, un test oculto escrito de antemano, y falló un requisito.

Señal	Resultado
Suite de tests	42 tests pasando
Type check	limpio
Comprobación oculta de finanzas	falló: número de nota de crédito posterior al esperado

La causa: el handler toma el siguiente número del contador antes de validar la petición, y el contador se guarda en el momento en que se lee. Una nota de crédito demasiado grande se rechaza, lo cual es correcto, y el número se pierde de todos modos, lo cual no lo es. La sesión copió ese orden de la ruta de emisión existente, que filtra números de factura de la misma manera.

Ejecutamos la tarea dos veces y la otra ejecución salió limpia, así que esto es lo que hace una sesión normal una parte de las veces.

El tercer gesto es escribir el comando de la retro en esa misma sesión y luego ejecutarlo otra vez con el fallo escrito detrás. La nuestra empezó con: "This session was smooth."

Clasificó un puñado de elementos, ninguno el bug: una barrera que faltaba, una regla de migración que nadie comprueba, y nada que un revisor pueda hacer cumplir. La retro lee el log de sesión, y la sesión nunca supo que había fallado.

Así que se lo dices: ejecuta el comando otra vez con el fallo como argumento, el texto después del comando. El nuestro decía que finanzas había probado el build, que una nota de crédito demasiado grande se rechazaba, que la siguiente nota válida salía tarde, y que la retro no debía arreglar nada.

Esta vez encontró la causa en su propio código: toma el número primero y valida después, y dijo que copió ese orden del handler de emisión existente. Siguieron candidatos nuevos: un test que había escrito, que ejecutaba la secuencia que falla pero solo comprobaba códigos de estado, una función de contador que parece pura y no lo es, y una convención que nadie escribió.

Todo lo que descubras después de la sesión, escríbelo en el argumento, o la retro audita una sesión que cree que fue bien.

El cuarto gesto es el que el skill no hace por sí solo: pide a la retro que cite el momento del transcript detrás de cada candidato, y descarta todo candidato que no pueda mostrar.

La doc explica por qué una lista ordenada no basta: una vez terminado el trabajo, el modelo olvida las dificultades de la sesión e inventa consejos genéricos. Así que descarta cualquier candidato que no puedas rastrear hasta un momento concreto: una frase que pida a la retro citar el transcript para cada uno.

En nuestra primera retro la respuesta fue directa: la mayoría de los candidatos no tenían apoyo en el transcript. Mantuvo la barrera que faltaba, porque su propio listado de la carpeta de hooks no había impreso nada, y descartó la comprobación de migración por hipotética.

En la segunda retro, la que conocía el bug, el rastreo mantuvo cuatro candidatos y descartó uno.

Candidato	Tras el rastreo
El test que escribió (aceptada, rechazada, aceptada, número nunca comprobado)	mantenido, firme
La función de contador sin aviso	mantenido, firme
La convención no escrita	mantenido, más débil
La barrera que faltaba	mantenido, aunque dijo que una barrera no habría atrapado este bug
El último candidato	descartado: contaba el mismo momento dos veces

Un issue abierto en el repo del skill cuenta la mayoría de las ejecuciones de retro seguidas de un usuario que pide pruebas. Un candidato rastreado sigue siendo el modelo leyendo su propio log, así que una fila marcada como más débil es un juicio, y tú decides cuáles te llevas.

El quinto gesto es donde el bucle da fruto: aprueba un superviviente cada vez, cada uno en su soporte, el lugar donde vivirá la regla. El skill te da la escalera. Una violación mecánica recibe una comprobación determinista, punto: una regla en tu linter, un hook de commit o un job en tu pipeline. Un juicio va a un archivo de estándares de código que lee el revisor. Tu archivo de instrucciones se usa, en palabras de la doc, "incredibly sparingly" (con muchísima moderación), para punteros a otros archivos.

Aprobamos cuatro cambios:

• La barrera que faltaba se convirtió en un hook de commit versionado que ejecuta el type check y los tests y bloquea el commit si alguno falla. El harness se negó a hacer el archivo ejecutable, así que ejecutamos ese comando nosotros.
• El test se convirtió en un test de vitest que fija la regla: una nota de crédito aceptada, una rechazada, y la siguiente válida debe llevar el siguiente número. Falló en su primera ejecución, que es el objetivo: atrapó el bug que la sesión había entregado.
• El juicio se convirtió en una línea en un nuevo CODING_STANDARDS.md: toma un número de secuencia solo cuando todas las validaciones hayan pasado, para que una petición rechazada deje la secuencia sin huecos.
• El hueco de navegación se convirtió en un comentario sobre la función del contador: guarda el contador al instante, así que el número se gasta aunque el llamador falle después, por lo tanto llámala solo tras la validación.

Son cuatro archivos cambiados y cero líneas en CLAUDE.md, porque las dos retros se negaron a escribir una. La primera dijo que un puntero en un archivo de guía costaría contexto en cada turno y se quedaría obsoleto; la segunda dijo que lo dejáramos como comentario en la función. La doc las respalda: Claude trata esos archivos como contexto, no como configuración obligatoria, y para bloquear una acción se usa un hook.

Dos límites: un hook solo protege los commits, y el comentario es, en palabras de la propia retro, una apuesta por el próximo llamador, no un arreglo probado.

El sexto gesto es el commit, y el último es repetir la misma tarea, que es donde descubres si el bucle aguantó.

Cuando preparamos los archivos aprobados y hicimos commit, el hook se ejecutó primero y rechazó el commit. El type check pasó, luego falló el nuevo test de numeración, que recibió un número posterior al esperado. El hook comprueba los archivos tal como están en disco, y el disco aún tenía el código con el bug.

Así que vuelve a la sesión y pide solo el arreglo: tomar el número después de que pase la validación, ejecutar las comprobaciones, no hacer commit. Luego haz commit otra vez, el hook pasa en verde y obtienes dos commits: los cambios de la retro, y después la funcionalidad con su arreglo. La propia retro no hizo ningún commit, algo que un issue abierto en el repo describe palabra por palabra, así que el commit lo haces tú.

Después ejecuta /doctor prompt-audit, la comprobación propia de Claude Code de tus archivos de instrucciones en busca de líneas obsoletas. Aquí hay una trampa: sin ruta, audita tus archivos globales, no el repo. Con la ruta, declaró limpio el nuevo archivo de estándares y señaló que la ruta de emisión antigua viola la regla, un bug de código y no un problema de prompt.

El último gesto es una sesión nueva con la misma tarea. La nuestra leyó el archivo de estándares de código, el readme, el hook y el test de numeración en rojo antes de escribir código, y luego escribió en su propio resumen que el número se toma solo después de que pasen todas esas comprobaciones, de modo que una petición rechazada no deja ningún hueco en la secuencia.

	Primera sesión	Sesión nueva tras el bucle
Tests pasando	42	verde
Comprobación oculta de finanzas	falló	5 de 5
Números tras una petición rechazada	quemado, un hueco	sin huecos

Una salvedad honesta: a esta sesión nueva se le entregó la lección como un test en rojo y una línea de estándares, así que es una ejecución posterior al bucle, no un benchmark.

La retro lee la sesión, así que lo que la sesión no vio, lo escribes en el argumento. Es en lo que vas a tropezar.

Ejecuta una retro después de una sesión que salió mal, antes de vaciarla, o sobre el log de una sesión antigua. No la ejecutes en piloto automático ni la conectes a un hook: el autor del skill lo dice con sus palabras, no quieres automatizar esto. La doc añade un límite: no audita las comprobaciones que propuso el mes pasado, así que sigues podándolas tú.

La regla que debes recordar es la frase de la propia doc: trata tu archivo de instrucciones como código, revísalo cuando las cosas van mal, poda con regularidad y prueba los cambios observando si el comportamiento de Claude cambia de verdad. El bucle no hace que el agente acierte, hace que el mismo fallo se atrape más rápido, y las comprobaciones que añades son código que ahora mantienes.

El pack gratis de este vídeo trae el checklist de la retro con cada gesto, la pregunta de rastreo y los soportes, además del script del hook de commit y el test de numeración de nuestra prueba, para que puedas empezar desde el nuestro.