Basado en especificaciones sin autoengaño: cobertura, contrato, evaluación y OpenAPI no son la misma prueba

Los equipos que adoptan la IA aprenden rápidamente a solicitar pruebas antes de aceptar un cambio. El problema comienza cuando evidencia dispar se comprime en una sola palabra: “verde”. La suite pasó, la cobertura aumentó, el contrato existe, el esquema es válido y la evaluación ha mejorado. Por tanto, se concluye que el sistema es correcto.

Esta conclusión no sigue las premisas. Cada mecanismo responde a una pregunta diferente. Cuando tratamos la proximidad en el proceso como una equivalencia semántica, construimos un hermoso tablero para una certeza que nunca se produjo.

Basado en especificaciones no significa escribir una especificación y confiar en ella. Significa mantener una cadena rastreable entre intención, propiedades, mecanismos de verificación, evidencia y decisión de aceptación.

Resumen ejecutivo

una descripción API abierta explica cómo los consumidores y las herramientas pueden entender una interfaz HTTP; un diff de compatibilidad busca cambios estructurales; una prueba ejecutada observa el comportamiento; una métrica de cobertura indica qué se ejerció; y una evaluación mide una propiedad de comportamiento bajo un conjunto de tareas y graders. Son capas complementarias, no sustitutas. [API31-C1]

Incluso dentro de una sola capa existen límites. oasdiff documenta la comparación de OpenAPI 3.1 y las reglas de cambio, pero un diff verde no certifica la compatibilidad empresarial. El porcentaje de cobertura, a su vez, no acredita la pertinencia de las pruebas, la corrección ni la cobertura de riesgos. [API31-C2] [API31-C4]

El diseño responsable comienza con una simple pregunta: ¿Qué propiedad este verde realmente autoriza a afirmar? La respuesta debe ser explícita antes de que se ejecute el proceso.

Cinco mecanismos, cinco preguntas

La tabla no crea una jerarquía fija. En una biblioteca pura, las pruebas unitarias y por contrato pueden ser el centro. En un agente que cambia datos, la política, el sandbox, la evaluación y la observabilidad pueden ser más importantes. La composición depende del riesgo.

Comience con la propiedad, no con la herramienta

"Agregar evaluación" no es un requisito verificable. “En cien escenarios representativos, el agente nunca envía un mensaje sin un consentimiento válido y cada intento bloqueado genera evidencia atribuible” es una propiedad candidata.

Para cada propiedad, registre:

1. subject — qué versión del sistema se está examinando;
2. estímulo — tarea, aportaciones y entorno;
3. oráculo — quién o qué decide el resultado;
4. límite — qué condición debe cumplirse;
5. evidencia — donde se pueda inspeccionar el resultado inmutable;
6. autoridad — qué decisión puede emitir el verde.

Sin subject, un informe puede pertenecer a un commit incorrecto. Sin un oráculo, el resultado se convierte en opinión. Sin límite, cualquier número puede considerarse una mejora. Sin autoridad, el verde existe pero nadie sabe qué desbloquea.

OpenAPI es descripción; la compatibilidad es una decisión más importante

La especificación OpenAPI define una descripción de interfaz independiente del idioma para que las personas y las computadoras comprendan las capacidades de un servicio. Esto reduce la ambigüedad en la integración, pero no incluye toda la semántica empresarial.

Considere un campo limite_aprovado que sigue siendo numérico y obligatorio. La API puede seguir siendo estructuralmente compatible mientras un cambio de unidad, política o redondeo interrumpe la operación. El diff estructural merece quedar verde; la prueba del invariant de negocio merece fallar. Son resultados coherentes porque examinan propiedades diferentes.

El error no está en la herramienta. Se trata de presentar “sin cambios importantes” como “sin impacto”.

La cobertura es un mapa, no un veredicto

La cobertura muestra las áreas visitadas durante la carrera. Ayuda a localizar el silencio: ramas nunca ejercidas, módulos olvidados, deltas no probados. Pero una línea ejecutada puede estar mal revisada; una prueba puede reproducir la implementación en lugar del requisito; un caso crítico puede representar una pequeña fracción del código.

En FORGE, la lectura útil separa al menos línea, rama, alcance, delta y umbral. Aún así, estos campos son señales de prueba, no de riesgo resuelto. [API31-C4]

Para no convertir el porcentaje en teatro:

• vincular escenarios críticos con las propiedades que protegen;
• utilizar la cobertura para descubrir lagunas, no para declarar corrección;
• tratar el código nuevo y el alto riesgo de manera diferente a como lo hacía históricamente;
• Exigir evidencia de la prueba que falla cuando se viola la propiedad.

Eval es un experimento versionado

Una evaluación necesita un banco de tareas, un entorno, una configuración del sistema, un evaluador, una regla de agregación y una línea de base. Cambiar cualquiera de estos elementos cambia el experimento.

Un número agregado puede ocultar clases de fracaso. Un agente puede mejorar la media y empeorar los casos irreversibles. Un evaluador modelo puede preferir el estilo y pasar por alto hechos. Un punto de referencia puede contener tareas rotas. Por tanto, eval no es una medalla; es una infraestructura de decisión.

El panel mínimo registra:

La prueba más importante: violar la propiedad.

Un gate sólo demuestra resistencia cuando la condición prohibida hace que falle. Antes de confiar en la tubería, realice un caso negativo deliberado:

• eliminar un campo obligatorio y confirmar el fracaso del contrato;
• introducir un cambio incompatible y confirmar el diff;
• eliminar la prueba de una rama crítica y observar la cobertura;
• hacer que el agente intente superar una autoridad y confirmar el bloqueo;
• cambiar el subject de la evidencia y confirmar que la vinculación falla.

El caso negativo distingue el mecanismo ejecutable de la documentación aspiracional.

Una matriz de evidencia para las relaciones públicas

No es necesario que la matriz cubra cada línea de productos. Debe cubrir las propiedades que respaldan la decisión que se está tomando.

Lo que este artículo prueba y lo que no prueba

FORGE fuentes y contratos admiten la separación de descripción, diff, ejecución, cobertura y evaluación. No definen una receta universal para herramientas, umbrales o número de pruebas. Un producto regulado y un prototipo interno necesitan perfiles diferentes.

Tampoco existe independencia automática porque un segundo modelo evaluó el primero. Si ambos comparten contexto, incentivo, error o autoridad, hay separación de llamadas, no necesariamente separación de control.

Conclusión

Basado en especificaciones es una disciplina de trazabilidad, no una etiqueta.

Una especificación declara intención. Un contrato estructura una interfaz. Una prueba analiza ejemplos. La cobertura revela áreas ejercitadas. Una evaluación mide el comportamiento en un experimento. Cuando cada verde mantiene su pregunta, su subject y su límite, el grupo puede apoyar una decisión defendible.

Cuando todos vieron "CI aprobado", el sistema pierde exactamente la precisión que se suponía que debía crear la ingeniería.

Lectura anterior: harness de ingeniería en la práctica.. Próxima lectura: *Autonomía proporcional al riesgo*, el 18/08 en Trustyu Forge.