Capa de Verificación: Hecho Significa que Hay Evidencia
Demuestras que un cambio funciona antes de que se confirme, y construyes las comprobaciones que hacen que la siguiente prueba sea más económica. El trabajo del humano pasa de leer cada diff a definir "hecho" y leer la evidencia. Tu trabajo es producir esa evidencia de manera honesta.
Los principios provienen de Cómo piensa el equipo de Claude Code sobre la verificación (Addy Osmani, Nov 2026). Los formatos de archivo en references/templates.md son propios de esta habilidad; el artículo describe las prácticas pero no muestra formatos.
Cuándo Usar
- Terminaste un cambio y estás a punto de decir "hecho" o confirmar
- El usuario pregunta "¿esto funciona?", "pruébalo" o "verifica esto"
- Un repositorio no tiene una forma repetible de iniciar y hacer una prueba rápida de la aplicación
- El usuario pregunta qué pruebas vale la pena escribir para una característica, una reescritura o una migración
- Una revisión o un conjunto de pruebas pasó por alto un error que llegó a los usuarios, y el usuario quiere que se detecte la próxima vez
- Una prueba es inestable y alguien quiere reintentarla o saltarla
- El usuario quiere ejecutar varios agentes a la vez y no puede leer todos los diffs
No usar para: revisar el diff de otra persona línea por línea (eso es una revisión, no una verificación), un cambio de una línea en documentación o comentarios donde no se pueda ejecutar nada, o agregar pruebas para aumentar un número de cobertura.
Principio Fundamental
Un cambio está hecho cuando la evidencia lo dice, y un cambio nunca puede editar su propio juez. "Las pruebas pasan" es una evidencia débil cuando el mismo cambio escribió las pruebas. Una evidencia sólida es la aplicación en ejecución haciendo lo que el usuario pidió, verificado por algo que el cambio no pudo tocar.
Reglas
- Ejecuta el cambio. Inicia la aplicación real y ejercita el comportamiento modificado. Esto importa más que las pruebas unitarias. Un conjunto de pruebas unitarias que pasan con una aplicación que no arranca es una verificación fallida.
- Tres rondas, luego un humano. Ejecuta las comprobaciones, corrige lo que falla, vuelve a ejecutar. Si una comprobación sigue fallando después de tres rondas, detente y entrega el control con la evidencia. No comiences una cuarta.
- Nunca debilites un juez para que pase. No editar, saltar ni eliminar una prueba, una regla de lint, un elemento de lista de verificación o una regla de REVIEW.md en el mismo cambio que juzgaría. Si un juez está equivocado, dilo y cámbialo en una confirmación separada que el usuario apruebe.
- Lee los jueces desde la rama base. Las reglas de revisión, las listas de verificación y la configuración de la puerta provienen de la rama predeterminada, nunca de la rama bajo prueba.
- La evidencia pertenece a una confirmación. Una verificación de una confirmación anterior no dice nada sobre una más reciente. Después de cualquier nueva edición, verifica de nuevo o informa que la evidencia está desactualizada.
- Comprobaciones baratas primero, y localmente. Las pruebas, la compilación y el lint se ejecutan antes de abrir un PR, no en el tiempo de un revisor.
- Ejecuta solo los elementos de la lista de verificación que activa el diff. Por lo general, de 3 a 10 elementos coinciden. Ejecutar todos cada vez enseña a todos a ignorar la lista.
- Sella cada confirmación con cómo se verificó, incluyendo
ninguno. Unningunohonesto se puede buscar más tarde. Un sello faltante no se puede buscar. - Una prueba inestable es un error. No la saltes, agregues un
sleepo reintentes hasta que esté verde. Encuentra la causa raíz. Si no puedes, elimina la prueba y escribe por qué. - Una comprobación que requiere un humano debe decir por qué. "Necesita revisión" no es una razón. "Cambia el formato del archivo de sesión; las transcripciones antiguas pueden no cargarse" sí lo es.
- Cada fallo se convierte en una regla, y las reglas se podan. Un error que se escapó es una brecha en la capa. Ciérrala con una comprobación y elimina las comprobaciones que ya no merecen su lugar.
Qué prueba escribir
| Situación | Prueba | Lo que demuestra |
|---|---|---|
| Un flujo visible para el usuario (si escribes solo una prueba, escribe esta) | Integral | Una ruta de usuario real funciona de principio a fin. Un fallo muestra el paso, un seguimiento y una captura de pantalla, no solo "tiempo de espera agotado". |
| Analizadores, codificadores, dinero, máquinas de estado, cualquier cosa con casos límite | De propiedades (fast-check, Hypothesis, proptest) | Una declaración se cumple para miles de entradas generadas que no se te ocurrieron. |
| Una reescritura, migración u optimización de algo que ya funciona | Diferencial | Lo antiguo y lo nuevo dan la misma salida con las mismas entradas. |
Propiedades que vale la pena verificar:
| Propiedad | Declaración |
|---|---|
| Ida y vuelta | Codificar, luego decodificar, devuelve el original |
| Invariante | Algo siempre se cumple (un saldo nunca es negativo) |
| Idempotencia | Hacerlo dos veces equivale a hacerlo una vez |
| Equivalencia | La versión rápida coincide con una versión lenta y obviamente correcta |
Para pruebas diferenciales: usa entradas reales aleatorias o muestreadas, normaliza las diferencias que no importan (espacios en blanco, orden de claves, marcas de tiempo) y mantén una lista escrita de las diferencias que aprobaste.
Un conjunto de pruebas lento se ejecuta con menos frecuencia, por lo que la cobertura baja. Mantén el bucle por edición rápido y mueve las pruebas pesadas justo antes de la confirmación.
Qué Mantener (Intocables)
- Pruebas existentes, reglas de lint, elementos de lista de verificación, REVIEW.md y configuración de puerta: nunca se cambian en la confirmación que juzgan.
- Salida de comandos, códigos de salida, nombres y recuentos de pasos fallidos: se informan exactamente como se imprimieron.
- El sello: dice lo que realmente ejecutaste. Nunca escribas
e2epara una ejecución que no hiciste. - Capturas de pantalla y seguimientos: se adjuntan o enlazan tal cual, no se describen de memoria.
Método
A. Verificar un cambio (cada vez)
-
Di qué significa "hecho". Escribe una o dos frases desde el lado del usuario: qué hace, qué ve. Si el repositorio tiene un mapa de características, busca la entrada y usa su resultado esperado como rúbrica. Si no puedes indicar "hecho", pregunta antes de verificar.
-
Ejecuta las comprobaciones baratas. Compilación, lint, verificación de tipos, las pruebas rápidas. Corrige los fallos. Esta es la ronda uno.
-
Ejecuta el cambio. Usa la habilidad
verifydel repositorio si existe (búscala en.claude/skills/cerca del código que cambiaste). Si no hay ninguna, inicia la aplicación tú mismo:- Web: maneja un navegador (extensión de Chrome, MCP de DevTools, Playwright).
- Móvil: un simulador a través de un MCP móvil.
- Escritorio: uso de computadora.
- Backend o CLI: ejecuta el servicio o comando localmente y llámalo.
Ejercita la ruta modificada y una ruta adyacente que no debería haber cambiado. Captura una captura de pantalla, un seguimiento o la salida.
-
Ejecuta los elementos de la lista de verificación activados. Lee la lista de verificación de fiabilidad desde la rama base. Para cada elemento, prueba su activador contra tu diff. Ejecuta la comprobación para cada coincidencia y registra el resultado. Enumera los elementos coincidentes por nombre en tu informe.
-
Agrega la prueba faltante. Usa la tabla anterior. Confirma que la nueva prueba falla sin tu cambio y pasa con él.
-
Cuenta las rondas. Cada "ejecutar comprobaciones, corregir, volver a ejecutar" es una ronda. Después de la tercera ronda con una comprobación aún fallando, detente. Informa qué falla, qué intentaste en cada ronda y tu mejor suposición de la causa.
-
Sella e informa. Agrega el sello al mensaje de confirmación (formato en
references/templates.md). En tu informe proporciona: la definición de hecho, lo que ejecutaste, la evidencia, los elementos de la lista de verificación coincidentes y cualquier cosa no verificada con el motivo.
B. Construir la capa (una vez por repositorio, luego ajustar)
Hazlo en orden. Cada uno es útil por sí solo, así que detente donde el usuario quiera.
-
Una habilidad
verify. Colócala en.claude/skills/verify/, lo más cerca posible del código que cubre (un monorepo puede tener una por aplicación). Registra cómo iniciar la aplicación y hacer una prueba rápida. Ejecútala varias veces seguidas antes de confiar en ella: debe ser rápida y dar el mismo resultado cada vez. -
Un mapa de características. Enumera las características desde el punto de vista del usuario. Para cada una: la ruta, los atajos de teclado, los selectores y el resultado esperado. Los agentes lo usan como guía y como rúbrica de calificación.
-
Una prueba integral para el flujo más importante. Luego pruebas de propiedades y diferenciales donde la tabla dice que encajan.
-
Una lista de verificación de fiabilidad. Cada elemento tiene tres partes: un activador que se puede leer de un diff, una comprobación y el incidente o PR que lo causó. Sin incidente, no hay elemento. Ejemplo: activador "cambios en el almacenamiento de sesión o tipos de mensaje", comprobación "¿un nuevo campo se carga de manera segura desde una transcripción antigua que no lo tiene?".
-
Un REVIEW.md. Le dice al revisor a qué prestar atención en esta base de código. Ajusta esto con un revisor durante varias rondas, donde cada ronda se basa en lo que encontró la anterior. No acumules más revisores encima. El propietario del código lo refina hasta que marca lo que él marcaría.
-
Aplicación local. Un hook que ejecuta las pruebas cuando el agente termina, o un objetivo que requiere un conjunto de pruebas que pase.
-
Una puerta de confirmación. Bloquea una confirmación cuando la sesión no ejecutó ningún paso de revisión ni de verificación. Implántala en tres modos:
Modo Comportamiento offNada observarRegistra lo que habría bloqueado. Ejecuta esto primero para encontrar falsos positivos. aplicarBloquea la confirmación. Una confirmación puede llevar un motivo escrito para saltarla. Después de dos bloqueos en una sesión, la siguiente confirmación pasa para que el agente no se atasque.
Pregunta al usuario antes de agregar hooks, puertas o cambios en CI. Cambian la forma en que todos confirman.
C. Convertir un fallo en una regla
Usa esto cuando un error superó las pruebas o la revisión.
- Encuentra el patrón, no el error. Mira los comentarios de revisión humana y las reversiones. Una regla candidata debe aparecer en al menos dos PRs y ser visible solo con un diff.
- Intenta refutarla. Realiza tres intentos independientes para demostrar que la regla es incorrecta, demasiado amplia o ya está cubierta. Si hay subagentes disponibles, usa tres. Conserva la regla solo si sobrevive.
- Verifica que se podía detectar. Reproduce el PR que causó el incidente a través de tres buscadores de errores independientes. Si dos o más encuentran el error, era detectable, y un fallo en un diff pequeño debería convertirse en una regla de REVIEW.md o un elemento de la lista de verificación.
- Consigue que un humano lo apruebe. El propietario del código decide si la regla se incluye. Tú propones; ellos aprueban.
- Califica al revisor. Mantén un conjunto pequeño de casos de incidentes, cada uno con una clave de respuesta de una oración, más cambios limpios fusionados de tamaño similar como controles contra el exceso de señalamientos. Mantén un conjunto de ajuste y un conjunto de prueba separado. Etiqueta los hallazgos como
Importante,NitoPreexistente. Deja de ajustar cuando más recuperación solo ajuste la evaluación. - Poda. Los conjuntos de pruebas, las listas de verificación y los archivos de reglas
.mdsolo crecen a menos que alguien los recorte. De forma rutinaria, elimina las reglas que nunca se activan, duplican otra regla o protegen código que ya no existe.
Ejemplo Práctico
Solicitud: "Agrega un indicador pinned a las sesiones de chat para que las ancladas se ordenen primero."
Sin la habilidad:
Se agregó
pinnedal tipo de sesión y se actualizó la ordenación. Las pruebas unitarias pasan. Hecho.
Con la habilidad:
Hecho significa: un usuario ancla una sesión en la barra lateral y se mueve al principio; después de un reinicio sigue estando arriba.
Ejecutó: compilación, lint, 148 pruebas unitarias (ronda 1: 2 fallaron en el comparador de ordenación, corregido; ronda 2: todas pasan). Inició la aplicación con la habilidad
verifydel repositorio, ancló una sesión, reinició, confirmó el orden. Captura de pantalla adjunta.Elementos de la lista de verificación coincidentes (2 de 31):
- Los cambios de formato de sesión cargan datos antiguos: abrió un archivo de sesión guardado antes de este cambio. Falló:
pinnederaundefinedy el comparador lanzó una excepción. Corregido estableciendo por defectofalseal cargar. Ronda 3: pasa.- Los cambios de ordenación mantienen un orden estable: las sesiones no ancladas mantienen su orden anterior. Pasa.
Agregó: una prueba de propiedades, "ordenar dos veces equivale a ordenar una vez", y un paso integral para anclar, reiniciar, verificar orden. Ambas fallan sin la corrección.
No verificado: el diseño móvil. No hay simulador en esta máquina.
Sello:
Verified-By: run, e2e, property, checklist(2)
Las pruebas unitarias pasaban mientras la aplicación fallaba con los datos de todos los usuarios existentes. Ejecutar el cambio contra un archivo antiguo fue lo que lo encontró, y el elemento de la lista de verificación fue lo que dijo que lo intentara.
Autocomprobación Antes de Entregar
- Tu informe tiene una línea "hecho significa" escrita desde el lado del usuario.
- La aplicación se inició y la ruta modificada se ejercitó, o el informe dice "no ejecutado" con el motivo.
git diff <base>no muestra ninguna edición a una prueba existente, configuración de lint, lista de verificación, REVIEW.md o configuración de puerta. Si lo hace, esa edición se señala y está en su propia confirmación.- No se agregó
.skip,.only,xit,sleep,retryo un tiempo de espera elevado para hacer que una prueba pase (busca en el diff cada uno). - Los elementos de la lista de verificación que coincidiste se enumeran por nombre, con un resultado para cada uno.
- Se vio que cada nueva prueba fallaba sin el cambio.
- El recuento de rondas es tres o menos. Si la tercera ronda aún fallaba, el informe entrega el control a un humano y no confirmaste.
- El mensaje de confirmación tiene un sello
Verified-By:, y cada palabra en él coincide con algo que realmente ejecutaste. - La evidencia se recopiló en el
HEADactual, no en una confirmación anterior. - Cada nuevo elemento de lista de verificación o regla nombra el incidente o PR detrás de él.