Prompt engineering en producción: criterios, few-shot y JSON Schema

Escenario Structured Data Extraction. Tu equipo extrae datos de facturas de proveedores: PDF escaneados, correos con el importe en el cuerpo, hojas con formatos que nadie ha vuelto a mirar. Usas tool use con un JSON Schema y el JSON que llega es siempre válido. Todo bien, hasta que contabilidad avisa: en un 6 % de las facturas, la suma de las líneas no coincide con el total. Y en otras, el campo «número de pedido» trae un valor que no aparece en el documento.

El JSON es perfecto en sintaxis y falso en contenido. Distinguir qué arregla un esquema, qué arregla un prompt y qué arregla una validación es el corazón del dominio 4, Prompt Engineering & Structured Output (20 %, unas 12 preguntas). Lo verás sobre todo en el escenario de extracción y en Claude Code for Continuous Integration, donde el problema es otro: demasiados falsos positivos en la revisión de código.

Aquí no se evalúa «escribir prompts bonitos». Se evalúa elegir la técnica correcta para el síntoma que describe el enunciado.

Criterios explícitos y few-shot (4.1 y 4.2)

Empezamos por CI. Tu revisor automático comenta cada PR. Los desarrolladores han empezado a ignorarlo porque la mitad de los comentarios son ruido. ¿Qué haces?

La tentación es escribir en el prompt «sé conservador» o «informa solo si tienes alta confianza». La guía las considera instrucciones vagas: el modelo no tiene un umbral calibrado detrás de esas palabras. Lo que funciona son criterios categóricos concretos: «marca un comentario solo si contradice lo que hace realmente el código», «señala un bug solo si puedes describir la entrada que lo dispara», «no comentes estilo si hay un linter».

Dos ideas más que caen en el examen:

• Los falsos positivos de una categoría hunden la confianza en todas. Si los comentarios de estilo son ruido, el equipo dejará de leer también los de seguridad. Una medida válida es desactivar temporalmente esa categoría mientras la afinas.
• La severidad necesita ejemplos de código por nivel. «Alta» y «media» sin ejemplos se interpretan distinto en cada ejecución.

Few-shot: cuando las instrucciones no bastan

Para conseguir un formato consistente o decisiones correctas en casos ambiguos, la técnica más eficaz según la guía es el few-shot: de 2 a 4 ejemplos bien elegidos.

Lo que los hace buenos:

• Apuntan a los casos ambiguos, no a los obvios. Un ejemplo trivial no enseña nada.
• Muestran por qué se eligió una opción frente a otra. El razonamiento breve generaliza mejor que la respuesta sola.
• Fijan el formato: ubicación, problema, severidad y arreglo sugerido, siempre en el mismo orden.
• Distinguen lo aceptable de lo real: un ejemplo de código que parece sospechoso y no lo es, junto a uno que sí es un problema.
• En extracción, incluyen estructuras de documento variadas (factura con tabla, factura en prosa, factura sin número de pedido) para que el modelo no rellene campos vacíos con inventos.

Revisa este diff y comenta los problemas.
Sé conservador: informa solo si tienes alta confianza.

Salida estructurada con JSON Schema (4.3)

Volvamos a las facturas. Usar tool use con un JSON Schema para forzar la salida elimina los errores de sintaxis: nada de llaves sin cerrar ni comas de más. Pero no evita los errores semánticos: líneas que no suman el total, un importe puesto en el campo del IVA, un dato inventado porque el campo era obligatorio.

Por eso el diseño del esquema importa:

• Campos opcionales o nullable para lo que puede no estar en el documento. Si el campo es obligatorio y el dato no existe, el modelo tiende a fabricarlo.
• Enums con unclear para cuando ni el documento ni el modelo pueden decidir.
• Patrón other + campo de detalle para categorías que no previste: el enum no se rompe y tú recoges el caso nuevo.
• Reglas de normalización en el prompt: fechas en un formato, importes sin símbolo de moneda, mayúsculas del código de material.

Validación, reintentos y revisión (4.4 y 4.6)

Como el esquema no te protege de lo semántico, añade una capa de validación y diseña bien los reintentos.

Reintento con feedback. Si una extracción falla una validación, vuelve a pedirla incluyendo tres cosas: el documento original, la extracción fallida y el error concreto («la suma de las líneas es 1.180, el total declarado es 1.200»). Con eso Claude puede corregir.

Cuándo no sirve reintentar. Si el dato no está en el documento, ningún reintento lo hará aparecer. Insistir solo produce invención. Esos casos van a null y a revisión, no a un bucle.

Validaciones de diseño que menciona la guía:

• calculated_total frente a stated_total: pide al modelo ambos y compara. Si difieren, algo falla.
• conflict_detected: un booleano para que el modelo señale que el documento se contradice a sí mismo.
• detected_pattern: un campo que registra qué patrón activó cada hallazgo. Cuando los desarrolladores descartan comentarios, puedes analizar qué patrones generan más rechazo y afinarlos.
• Pydantic (u otra librería de validación) para aplicar estas reglas en tu código.

Revisión multi-instancia y multipasada (4.6)

Retomamos lo visto en la lección anterior: la autorrevisión en la misma sesión es débil porque conserva el razonamiento que produjo el resultado. Aquí la guía añade dos patrones:

• Pasadas por archivo + pasada de integración. Revisar una PR enorme de una sola vez dispersa la atención: se examina cada archivo por separado y una última pasada mira cómo interactúan.
• Confianza por hallazgo para enrutar: que el modelo indique su confianza en cada hallazgo permite mandar los dudosos a un humano. Cuidado: es una señal de enrutado, no una prueba de corrección. Cómo calibrarla lo vemos en la próxima lección.

Batch API: coste frente a latencia (4.5)

Contabilidad quiere procesar el archivo histórico de 200.000 facturas. No hay prisa. ¿Llamadas síncronas o Message Batches API?

La Batch API es un 50 % más barata, puede tardar hasta 24 horas y no ofrece SLA de latencia. Además, no admite tool calling multiturno dentro de una petición: cada petición es de una sola vuelta. Cada una lleva un custom_id que te permite correlacionar resultados con entradas.

Prácticas que la guía espera que conozcas:

• Calcula la frecuencia de envío según tu SLA. Si debes entregar en 30 horas y el lote puede tardar 24, no puedes enviarlo con menos de 6 horas de margen. Planifica con eso en mente.
• Reenvía solo los fallidos, identificados por custom_id. Si fallaron por documentos demasiado largos, trocéalos antes de reenviarlos.
• Afina el prompt con una muestra antes de lanzar el lote entero: un error de prompt multiplicado por 200.000 documentos sale caro.

El guion de esta lección mencionaba el prompt caching y la inyección de prompts. La Exam Guide solo pide saber que el prompt caching existe y no incluye la inyección de prompts entre los task statements del dominio. Si quieres profundizar, la documentación de la plataforma es el sitio.

Para el examen