Cómo demostrar que una corrección funciona

El cálculo de puntos ya está corregido. En la respuesta hay salida de terminal, una captura del marcador y un breve "listo". Muchos archivos, y una pregunta sencilla: ¿cuál de ellos responde de verdad al requisito de la tarea?

Una evidencia no es cualquier archivo que haya quedado junto a la corrección. Es el resultado de una comprobación concreta, en el que se ve qué se comprobó, sobre qué estado del código y qué salió. Cada material responde a preguntas distintas, y ninguno responde a todas a la vez.

Veremos cómo convertir un requisito en una afirmación comprobable, qué anotar sobre la ejecución de un comando y qué confirma un log, un diff y una captura de pantalla. Después reuniremos todo en un registro breve, EVIDENCE_LOG, de seis campos, y analizaremos si un conjunto de materiales ya preparado es suficiente.

El criterio define la comprobación

El ejemplo que recorre todo el artículo es un pequeño juego de bonificación con la puntuación en un marcador. Al empezar la puntuación es 0; tres coincidencias deben sumar 3 puntos, pero antes de la corrección sumaban 30. La regla de puntuación está inventada para este juego: en otro proyecto puede ser cualquier otra, así que no conviene trasladarla.

La frase "la puntuación está corregida" no se puede comprobar: no queda claro qué ejecutar ni qué mirar. Una afirmación comprobable se compone de tres partes: estado inicial, acción y observación esperada. El resultado es "con la puntuación en 0, tres coincidencias suman 3 puntos y en el marcador se ve 3". Ahora la afirmación sí tiene una comprobación.

A continuación esa afirmación se divide en observaciones separadas. El cálculo y lo que ve el jugador son cosas distintas, y se confirman con cosas distintas. La tercera fila de la tabla trata de guardar el resultado en la tabla de clasificación: puede que la tarea ni siquiera lo pida, pero si lo pide, necesita su propia observación.

La tercera columna es la más útil. Una evidencia casi siempre confirma menos de lo que uno quisiera, y el límite está donde termina la acción que realmente se ejecutó. En nuestro ejemplo, el test del cálculo no comprueba el marcador, y la captura del marcador no muestra la línea de código modificada.

Y mantenga separadas dos cosas: el requisito es lo que debe ser cierto al final, y el resultado es lo que usted obtuvo de hecho. Cuando se mezclan en un mismo párrafo, "debe sumar 3" se convierte sin que nadie lo note en "suma 3", aunque nadie haya ejecutado nada.

El comando y su resultado

Una ejecución de la comprobación se describe con cinco cosas. Ninguna es obvia para quien vaya a repetir la comprobación una semana después:

• la carpeta desde la que se ejecutó el comando;
• el propio comando, literal;
• el estado del código: antes de la corrección, después, con qué cambios sin commit;
• cómo terminó: el código de salida y los contadores finales;
• qué comprobaciones participaron de verdad y cuáles no.

Además, conviene distinguir entre "hay que ejecutar npm test" y "he ejecutado npm test, aquí está la salida". Lo primero es una instrucción, un plan para el futuro. Lo segundo es un hecho. Justo aquí es fácil hacer pasar una intención por un resultado, sobre todo cuando la respuesta detalla con esmero lo que habría que comprobar.

npm test no ejecuta "todos los tests en general". Ejecuta lo que está escrito en el campo test de la sección scripts de un package.json concreto, el del proyecto que npm haya elegido. Para no adivinar qué proyecto se eligió, ejecute el comando desde su raíz y anote esa carpeta en el registro. En otro proyecto, detrás del mismo nombre puede haber otra herramienta, otro conjunto de pasos o nada.

El comando termina con un código de salida: 0 suele significar "la herramienta considera que la ejecución fue exitosa". En bash lo muestra echo $? justo después del comando; en PowerShell, para un programa externo como npm, es $LASTEXITCODE. Pero un cero no dice que el test que le interesa haya participado: pueden haberlo omitido o filtrado por nombre, o puede que nunca se escribiera. Por eso, junto al código de salida siempre hacen falta los contadores y el nombre del test que le interesa.

Qué conservar del log

La salida de una ejecución puede ser larga, y nadie la copia entera al registro. En un fragmento breve entran cuatro cosas: el nombre del test que falló, el valor esperado y el real, la causa del fallo y los contadores finales. El resto se queda en un archivo al que usted pondrá un enlace. Abajo hay un ejemplo didáctico y abreviado de salida, no el registro de una ejecución real.

✖ three matches give 3 points (2.4108ms)
  AssertionError [ERR_ASSERTION]: Expected values to be strictly equal:
  30 !== 3
      at TestContext.<anonymous> (src/bonus-game/score.test.js:8:10)
ℹ tests 1
ℹ pass 0
ℹ fail 1
ℹ skipped 0

Esto es un fragmento; la salida completa está guardada en un archivo, por ejemplo logs/test-fail.txt. Con este fragmento ya se ve lo principal: falló justo el test de las tres coincidencias, se esperaba 3, se obtuvo 30 y no hay comprobaciones omitidas.

La salida original entra en el registro tal cual. Un resumen con sus propias palabras ("el test falló por un multiplicador incorrecto") parece más claro, pero ya es una conclusión, no una observación, y no se puede verificar con el registro. Mantenga una cosa junto a la otra: primero las líneas de la herramienta, después su explicación.

La ubicación en la línea del stack trace es el lugar donde saltó la aserción, el archivo del test. La causa se busca en el código del juego, y el multiplicador que se encuentra allí es resultado de leer el código, no una línea del log. En el registro, estas dos fuentes se etiquetan de forma distinta; si no, luego no hay manera de saber de dónde salió el número 10.

Qué confirma un diff

Un diff muestra la diferencia entre dos estados de un archivo. No dice que el código se haya ejecutado ni una sola vez después de la corrección, y mucho menos que el comportamiento haya cambiado como usted esperaba.

--- a/src/bonus-game/score.js
+++ b/src/bonus-game/score.js
@@ -1,5 +1,5 @@
-const POINTS_PER_MATCH = 10;
+const POINTS_PER_MATCH = 1;

 function calcScore(matches) {
   return matches * POINTS_PER_MATCH;
 }

Debajo de un fragmento así hace falta una línea explicativa: qué estados se compararon. Por ejemplo, "árbol de trabajo frente al commit a1b2c3d anterior a la corrección, comando git diff HEAD"; aquí el identificador es didáctico, en el registro necesita el suyo real. Este comando compara los archivos rastreados actuales con HEAD, incluidos los cambios preparados para el commit. Un git diff normal, sin HEAD, muestra solo la diferencia con el estado preparado y puede salir vacío justo después de git add. Sin esa línea, el diff se lee como "algo comparado con algo", y no habrá forma de repetir la comparación.

Compruebe también por separado que la expectativa del test siguió siendo la misma: 3. Si junto con el código cambió también el número esperado, eso ya es otra historia: la comprobación se adaptó al comportamiento, y no el comportamiento al requisito.

Ahora, un detalle técnico en el que es fácil equivocarse. Mientras la corrección no esté en un commit, se ve al comparar el árbol de trabajo con el último commit. Después del commit, esa misma comparación saldrá vacía, y eso no significa que en la tarea no haya cambiado nada: simplemente el cambio pasó al historial, y hay que comparar el commit con el estado anterior. Un diff vacío por sí solo no demuestra nada; lo que importa es qué dos estados está comparando.

Qué se ve en una captura de pantalla

Estado y acción

Una captura con el número 3 en el marcador confirma exactamente una cosa: en el momento de la captura el marcador mostraba 3. No es lo mismo que "tres coincidencias sumaron 3 puntos". Entre esas dos afirmaciones está todo lo que no sale en la imagen: con qué puntuación se empezó y qué se hizo en realidad.

Para que la captura se convierta en evidencia, junto a ella se anota el escenario:

1. qué se abrió: la dirección de la página o la forma de arranque, y qué versión es, con la corrección o sin ella;
2. el estado inicial: puntuación de partida 0, sin datos antiguos cargados;
3. la acción: se consiguieron tres coincidencias;
4. la observación: el marcador muestra 3, capturado justo después de la acción.

Sin ese registro, cualquier captura se puede obtener de diez maneras distintas. Una pestaña abierta desde ayer con la versión antigua, otra ejecución, una puntuación que ya no era cero: todo eso da una imagen que parece convincente y no significa nada.

En este artículo no hay captura del marcador a propósito. La captura para una comprobación se toma después de reproducir el escenario en la versión correcta, a mano o con herramientas de automatización; un marcador dibujado o montado para ilustrar no se convierte en evidencia, aunque sea idéntico. Cuando tome su propia captura, incluya el marcador entero, indique la dirección de la página en el registro del escenario y guarde la captura junto a ese registro; si no, dentro de una semana ya no recordará de qué ejecución era.

Qué puede leer el modelo

Puede pasar la imagen a la sesión y pedir que la lea. Aquí la formulación lo decide todo: pida que nombre el número visible y que enumere sus dudas ("¿se ve el estado inicial?", "¿está claro qué versión es?"), no que confirme una conclusión fijada de antemano. Si pide "confirma que el bug está corregido", es fácil recibir un asentimiento cortés que no comprueba nada.

La posibilidad de pasar una imagen depende del modelo y del entorno en el que trabaje. En Claude Code puede indicar la ruta de una imagen guardada y pedir que la lea. Si la imagen no se cargó, compruebe primero la ruta y que el archivo sea accesible; cambiar de modelo, sin más, no garantiza que el problema se resuelva.

Un mismo escenario antes y después

Un par útil se ve así: la misma comprobación falla con la implementación rota y pasa con la corregida. El fallo demuestra que la comprobación detecta este defecto; el resultado en verde, que después de la corrección el defecto ya no está en el escenario comprobado.

Esto funciona con una condición: se comparan los mismos datos de entrada y las mismas expectativas. La misma puntuación inicial, el mismo número de coincidencias, el mismo valor esperado, 3. Este es el resultado en verde del mismo test después de la corrección:

✔ three matches give 3 points (1.3983ms)
ℹ tests 1
ℹ pass 1
ℹ fail 0
ℹ skipped 0

Entre una ejecución y otra cambia la implementación, mientras que el test, los datos de entrada, la expectativa y las condiciones de ejecución se mantienen. Si tuvo que cambiar el requisito o corregir la expectativa del test, obtenga un nuevo par de ejecuciones con esa comprobación: una explicación con palabras no sustituye ejecutarla en ambos estados. En esa situación, un "antes estaba en rojo y ahora en verde" sin más explicación induce a error.

Y dos archivos llamados before.txt y after.txt no garantizan nada por sí mismos. El nombre de un archivo no es una evidencia. Hay que mirar dentro: si es el mismo comando, el mismo test, la misma expectativa. Restaurar a propósito el estado roto para comprobarlo (el conocido truco con git stash) es una comprobación aparte con sus propias reglas; aquí basta con saber que el rojo de antes de la corrección sale de una ejecución real, no de la memoria.

Un EVIDENCE_LOG breve

En este artículo, EVIDENCE_LOG es un registro de texto normal con seis campos en este orden: SÍNTOMA, PISTA EN EL LOG, FALLO EN LA VERSIÓN ROTA, CORRECCIÓN, VERDE HONESTO, CAPTURA. Así es más fácil relacionar el síntoma, la corrección y el resultado. El orden de los campos, por sí solo, no garantiza que las anotaciones sean fiables.

Todo lo que hemos reunido hasta ahora se reparte entre estos campos. El comando y la carpeta van al campo del fallo, los estados que se comparan van a la corrección, y los enlaces a los archivos completos, al campo del que proceden. No hace falta montar al lado otro paquete de documentos.

Abajo hay un esquema didáctico de cómo rellenarlo: muestra qué escribir en cada campo, no informa de comprobaciones realizadas. En su propio registro, sustituya el texto por los resultados reales.

SÍNTOMA: en el juego de bonificación, con una puntuación inicial de 0,
tres coincidencias dan 30 puntos en lugar de 3. Se repite siempre: abrir
el juego, conseguir tres coincidencias, mirar el marcador.

PISTA EN EL LOG: en la salida de la ejecución aparece "30 !== 3" en el test
"three matches give 3 points", salida completa en logs/test-fail.txt.
Aparte, por lectura del código: en src/bonus-game/score.js
el multiplicador POINTS_PER_MATCH vale 10. Esto sale de leer el código,
en la salida del test no aparece el número 10.

FALLO EN LA VERSIÓN ROTA: HEAD a1b2c3d (identificador didáctico),
árbol de trabajo limpio; en el commit están el cálculo roto y el test.
Carpeta - /project/bonus-game, comando - npm test.
En package.json scripts.test = node --test. Falla "three matches give 3 points",
causa "30 !== 3", tests 1, pass 0, fail 1, skipped 0, código de salida 1.
Fragmento de la salida arriba, completa - logs/test-fail.txt.

CORRECCIÓN: POINTS_PER_MATCH cambiado de 10 a 1 en el archivo
src/bonus-game/score.js; no hay más cambios. HEAD sigue siendo a1b2c3d.
Diff: git diff HEAD, árbol de trabajo frente a ese commit;
guardado en diffs/score-fix.diff.
El valor esperado en el test sigue siendo el mismo - 3.

VERDE HONESTO: el mismo comando npm test desde la misma carpeta, sobre
el código después de la corrección descrita. El mismo test pasa: tests 1,
pass 1, fail 0, skipped 0, código de salida 0.
Salida completa - logs/test-pass.txt.
El escenario con cinco coincidencias no se ejecutó.

CAPTURA: screenshots/bonus-score-3.png. Juego abierto de nuevo
en http://localhost:3000 desde el mismo árbol de trabajo
después de la corrección. Puntuación inicial 0, tres coincidencias
conseguidas, el marcador muestra 3. El guardado del resultado
en la tabla de clasificación no se comprobó.

Las rutas del ejemplo son solo eso, un ejemplo. Los logs completos, los diffs y las imágenes se guardan donde el proyecto ya tenga algo parecido; no hace falta una estructura de carpetas obligatoria para ello.

Fíjese en las últimas líneas de los campos 5 y 6. Lo que no se hizo se marca directamente, con una frase: "no se ejecutó", "no se comprobó". no es una confesión de pereza, es el límite de la conclusión. Un registro sin esas líneas parece más completo, pero en realidad solo calla lo que nadie hizo.

Compruébelo usted mismo

La tarea tiene dos criterios: el cálculo da 3 puntos por tres coincidencias partiendo de cero, y la interfaz muestra 3 tras esas tres coincidencias. Tiene seis materiales a mano:

1. el mensaje del agente "listo, bug corregido";
2. una instrucción de ejecutar npm test;
3. ejecuciones reales de un mismo test: en rojo antes de la corrección y en verde después;
4. un diff con el cambio del multiplicador;
5. una captura suelta con el número 3, sin descripción de la ejecución;
6. el registro del escenario reproducido con una captura vinculada a él.

¿Cuáles bastan para los dos criterios y qué queda sin comprobar? Piense su respuesta antes de seguir leyendo.

Análisis. El primer criterio lo cubre el punto 3: un par real de ejecuciones sobre un mismo test. El diff del punto 4 explica qué cambió en el código, pero no sustituye a una ejecución: un cambio y una ejecución son cosas distintas. El segundo criterio lo cubre el punto 6: la captura junto con el registro del escenario, donde se ven el estado inicial y la acción. Los puntos 1 y 2 no confirman nada: el mensaje de "listo" no contiene ninguna confirmación verificable, y la instrucción describe una acción futura. El punto 5 muestra el número 3 y ahí se queda; con él no se puede establecer cómo se calculan los puntos. Y el guardado del resultado en la tabla de clasificación sigue sin comprobarse incluso con los seis materiales sobre la mesa: entre ellos no hay ningún escenario en el que se haya vuelto a leer el valor guardado.

Un registro así también se puede montar dentro de una sesión. Aquí tiene un prompt listo:

Arma un EVIDENCE_LOG con los seis campos. Para cada conclusión indica
la comprobación real, el estado del código y la fuente del resultado.
Marca aparte lo que no se ejecutó. En la captura, nombra solo
lo que se ve y no deduzcas de ella que el cálculo interno es correcto.

Cómo reunir pruebas con Claude Code

El orden de trabajo queda así:

1. el agente vincula cada criterio con una comprobación concreta: qué ejecutar, sobre qué estado del código y qué se considera el resultado;
2. ejecuta las comprobaciones que están disponibles en ese entorno y muestra el comando con su salida original;
3. adjunta las observaciones: fragmentos de la salida, enlaces a los archivos completos, la descripción del escenario reproducido;
4. marca explícitamente el límite: qué quedó sin ejecutar y qué no se puede afirmar con los materiales disponibles.

A usted le queda comprobar las propias evidencias: abrir los archivos adjuntos y ver qué hay dentro, contrastar el escenario con el que describe el criterio y hacer una pregunta incómoda sobre el punto del que no se ve ninguna comprobación. Normalmente con eso basta para distinguir unas pruebas reales de un resumen bien presentado.

Referencia técnica: git diff, git stash, Node.js test runner, npm test, imágenes en Claude Code.