Convertir el brief en contratos y casos verificables

C04 parte del brief técnico construido en M02 o de una especificación equivalente. No vuelve a justificar desde cero qué es un LLM, por qué existen Structured Outputs o qué significa tool calling: convierte esas decisiones en contratos, módulos, validaciones y pruebas.

La primera decisión técnica de una aplicación LLM no es elegir modelo. Es definir qué promete el producto y convertir esa promesa en interfaces que puedan probarse. Si la lógica de negocio queda mezclada desde el inicio con el formato de un proveedor, cada cambio de API, modelo o patrón de tool calling se convierte en un cambio de producto.

El objetivo de esta lección es construir una frontera estable: la aplicación habla en términos de su dominio; el adaptador del proveedor traduce esos términos a la API vigente.

Del requisito empresarial al contrato

Un brief suele contener frases como «clasificar solicitudes», «preparar una respuesta», «consultar documentación» o «actualizar el CRM». Cada una debe convertirse en un resultado observable.

Para cada capacidad define:

• actor;
• autenticación;
• entrada;
• contexto necesario;
• salida;
• campos obligatorios;
• estados intermedios;
• errores recuperables;
• errores definitivos;
• efectos permitidos;
• efectos prohibidos;
• permisos;
• latencia y coste aceptables;
• evidencia necesaria para aceptar el resultado.

Por ejemplo, «clasificar solicitudes» es demasiado ambiguo. El contrato puede exigir categoria, prioridad, motivo, evidence_refs y un estado needs_review cuando falte información. La decisión de negocio deja entonces de depender de una frase libre del modelo.

Separa las fronteras

Una aplicación mantenible suele tener varios contratos distintos:

1. Contrato del cliente. Lo que recibe tu API.
2. Contrato de dominio. La representación que entiende la lógica de negocio.
3. Contrato de proveedor. El payload que exige la API del modelo.
4. Contrato de salida del modelo. Texto o estructura generada.
5. Contrato de herramientas. Nombre, argumentos y resultado.
6. Contrato de persistencia. Qué estado se guarda y durante cuánto tiempo.
7. Contrato de eventos. Qué se publica a colas, webhooks o auditoría.
8. Contrato de evaluación. Qué constituye éxito, fallo y regresión.

No tienen por qué ser iguales. De hecho, conviene que el formato del proveedor no llegue directamente al frontend. Si una API cambia output por otra estructura, el cliente no debería enterarse.

Define estados, no solo respuestas

Una llamada LLM puede terminar en más situaciones que «éxito» o «error»:

• salida válida;
• rechazo;
• timeout;
• rate limit;
• salida parcial;
• estructura inválida;
• estructura válida pero semánticamente incorrecta;
• herramienta solicitada;
• herramienta denegada;
• datos insuficientes;
• resultado pendiente de revisión.

Modela esos estados. Si todos se reducen a un 500, el sistema pierde la información necesaria para reintentar, pedir datos o escalar.

Escribe primero los casos que podrían romper el sistema

El camino feliz no suele descubrir las decisiones importantes. Construye una tabla de casos:

• usuario sin permiso;
• input vacío;
• input demasiado grande;
• documento malicioso;
• proveedor no disponible;
• respuesta truncada;
• JSON sintácticamente válido con una categoría inexistente;
• llamada de herramienta con ID de otro tenant;
• doble envío del cliente;
• resultado tardío después de timeout;
• cancelación;
• cambio de versión del modelo;
• salida que no contiene evidencia suficiente.

Para cada caso define resultado esperado y efectos que no pueden ocurrir.

Distingue tests y evals

Los tests deterministas sirven para contratos: esquema, permisos, idempotencia, códigos de error, estados, límites y efectos. Los evals sirven para calidad variable: exactitud semántica, completitud, utilidad, groundedness o elección correcta de herramienta.

No los mezcles en una única puntuación. Un sistema puede obtener una media alta de calidad y seguir siendo inaceptable si una prueba determinista demuestra que puede acceder a datos de otro tenant.

Diseña el conjunto inicial de evaluación

Empieza con casos reales o representativos, no con ejemplos escritos para que el modelo parezca bueno.

Para cada caso registra:

• input;
• contexto;
• output aceptable;
• elementos obligatorios;
• elementos prohibidos;
• evidencia esperada;
• riesgo;
• decisión humana si procede.

Versiona el conjunto. Cuando aparezca un fallo en producción o en piloto, añádelo como caso de regresión.

Ejemplo: clasificación de solicitudes

El producto recibe una solicitud y debe devolver una clasificación utilizable por un workflow.

Contrato de dominio:

request_id
category
priority
needs_review
reason
evidence_refs

El modelo puede proponer category="facturacion", pero el servidor comprueba que la categoría existe, que la solicitud pertenece al tenant del usuario y que evidence_refs apunta a contenido autorizado. Si la categoría es desconocida, el resultado no entra en dominio aunque el JSON sea perfecto.

Ejercicio

Toma una función de tu aplicación y crea:

1. contrato de cliente;
2. contrato de dominio;
3. contrato de proveedor;
4. salida estructurada;
5. estados de error;
6. permisos;
7. efectos prohibidos;
8. diez casos deterministas;
9. diez evals semánticos;
10. criterio de publicación.

Después sustituye mentalmente el proveedor. Si el contrato público cambia por completo, la frontera todavía está demasiado acoplada.

Resultado de la lección

Debes terminar con un brief convertido en interfaces y casos verificables. A partir de este punto ya puedes integrar una API sin permitir que sus detalles se conviertan en la arquitectura de toda la aplicación.