Agent-Verify

¿Qué hace Agent-Verify?

Haz que lo que construyes sea verificable por el mecanismo más barato que pueda falsificarlo. Verifica por CLI por defecto. El modelo debería leer ~20 tokens (PASS / FAIL: línea), nunca un volcado de DOM o una captura de pantalla.

La única regla

Usa el mecanismo más ligero que pueda demostrar que una funcionalidad está mal. Escala solo cuando no pueda hacerlo.

assert en proceso  →  CLI / curl + código de salida  →  prueba de BD (TAP)  →  navegador sin interfaz gráfica (solo visual, último)
   más barato                                                            más caro

El 90% de lo que construyen los agentes (lógica, datos, contratos de API, flujos) es verificable sin navegador. Reserva el navegador para los píxeles.

Bucle (por funcionalidad)

1. Detectar una vez. Ejecuta scripts/detect-stack.sh. Imprime el ejecutor de pruebas y el stack en unas pocas líneas. No impongas un nuevo framework — usa lo que ya existe.
2. Construir la funcionalidad.
3. Escribir UNA comprobación mínima en tokens usando la primitiva en proceso / CLI del stack (consulta reference/stacks/). La comprobación debe imprimir PASS o una sola línea FAIL: — nunca volcados.
4. Añadir una línea a VERIFICATION_MAP.md: funcionalidad | comando | señal de éxito. Este es el contrato que el agente leerá la próxima vez.
5. Ejecutar scripts/verify.sh [funcionalidad] y leer solo el resultado. Editar → verificar → repetir según el resultado, no según los registros.

Lo que NO debes hacer

• No uses Playwright/el navegador para comprobar lógica, datos o respuestas de API. Esa es la fuga de tokens que esta habilidad existe para detener.
• No prescribas un ritual TDD. Indica qué comprobación demuestra esta funcionalidad, no un procedimiento. (El procedimiento sin contexto objetivo empeora mediblemente — consulta reference/patterns.md).
• No devuelvas la salida sin procesar al contexto. Filtra en el entorno aislado, muestra el resultado. (console.log(resultado), no las 10k filas.)
• No permitas que las comprobaciones crezcan. Una funcionalidad, una comprobación rápida y determinista. Mantén VERIFICATION_MAP.md corto — los mapas cortos superan a los largos.

Contrato de salida (siempre)

PASS auth-login
FAIL create-invoice: esperado 201, obtenido 500

Salida 0 = todo correcto. Distinto de cero = algo falló. Eso es todo lo que el modelo necesita.

Cuando el navegador SÍ es inevitable

Solo para UI genuinamente visual (maquetación, estilo, regresión visual) y solo al final. Incluso entonces: una ejecución sin interfaz gráfica, devuelve PASS/FAIL o un veredicto de diferencias — nunca una captura de pantalla completa o DOM al contexto. Consulta reference/stacks/nextjs.md.

Archivos

• scripts/detect-stack.sh — imprime stack + ejecutor, mínimo en tokens.
• scripts/verify.sh — ejecuta las comprobaciones mapeadas, emite solo PASS/FAIL + línea fallida.
• VERIFICATION_MAP.md — el mapa corto funcionalidad→comando (el agente lo mantiene).
• reference/stacks/ — recetas de copiar y pegar: FastAPI (TestClient en proceso), Supabase (semilla + reinicio + pgTAP), Next.js (manejadores de rutas + último recurso visual).
• reference/patterns.md — patrones de verificación mínimos en tokens + la evidencia detrás de ellos.
• reference/anti-patterns.md — pruebas inestables, PASS falso, protecciones de sobreingeniería.
• templates/ — puntos de partida para el mapa, una prueba de FastAPI, una semilla de Supabase.