Cuando un equipo dice que "ya reviso el prompt", casi nunca significa lo mismo para todos. Una persona mira tono. Otra mira si llama bien a las tools. Otra intenta imaginar riesgos de datos. El resultado suele ser un review un poco borroso, y el sistema queda aceptable pero dificil de operar cuando crece.
En varios flujos con LLMs me ha funcionado mejor tratar cada prompt importante como un contrato minimo. No es un paper, no es un framework pesado. Es una ficha corta que define entrada, salida, limites y señales de fallo. La ventaja no es solo calidad del prompt; tambien mejora handoff entre producto, plataforma y QA. Algo parecido pasa en cualquier checklist de emails antes de lanzar: el valor real esta en reducir ambiguedad antes del envio.
Anthropic y OpenAI insisten, cada uno a su manera, en separar instrucciones, herramientas y criterios de exito. No hace falta copiar sus patrones enteros. Pero si conviene bajar esa idea a algo que el equipo pueda revisar en diez minutos, aveces incluso menos.
Por que un contrato minimo mejora la revision de prompts
Yo pienso el contrato como un diagrama en palabras:
- que contexto recibe el modelo
- que decision puede tomar
- que herramienta puede tocar
- que salida debe dejar lista para el siguiente sistema
Sin esa vista, los bugs se esconden en los huecos entre equipos. El prompt parece bueno en local, pero nadie sabe que hacer cuando una tool responde vacio, cuando el modelo mezcla idiomas o cuando resume demasiado. Ahi es donde la revision deja de ser tecnica y pasa a ser casi intuicion, lo cual no escala muy bien.
Tambien ayuda a discutir tradeoffs de forma mas honesta. Si le das libertad amplia al modelo, iteras mas rapido. Si cierras demasiado el contrato, sube la trazabilidad pero baja flexibilidad. Esa tension es normal, no hay que fingir que no existe. Lo util es dejarla escrita para que luego no aparezca una sorpresa rara en produccion.
Que campos meto en el contrato y por que
Mi version minima tiene seis campos:
- objetivo de la tarea
- datos de entrada permitidos
- tools disponibles y reglas de uso
- formato de salida
- errores esperados y fallback
- limites de privacidad o seguridad
Eso ya permite revisar bastante. Si el prompt toca registros, bandejas de prueba o cuentas temporales, tambien agrego una nota corta sobre proveniencia del dato. En pruebas de onboarding, por ejemplo, a veces usamos un correo de usar y tirar para aislar escenarios de bajo riesgo. No lo convierto en el tema central del post ni del sistema, pero si lo nombro en el contrato para que nadie confunda trafico real con muestras de QA.
La parte importante es que cada campo tenga una pregunta asociada. Por ejemplo:
- objetivo: que decision concreta esperamos
- entrada: que dato sobra y deberia quedar fuera
- tools: cuando no debe llamar nada
- salida: quien consume esto despues
- fallback: que hacemos si la respuesta llega incompleta
- privacidad: que dato seria un exceso
Si el contrato no deja responder esas preguntas, todavia esta verde. No pasa nada, pero mejor verlo antes de desplegar.
Un ejemplo corto para tool use y datos sensibles
Este patron pequeño me gusta porque obliga a revisar el flujo y no solo la redaccion:
{
"task": "Clasificar un incidente de soporte y sugerir siguiente accion",
"allowed_inputs": ["resumen del ticket", "categoria", "prioridad"],
"tools": [
{
"name": "search_runbook",
"when": "solo si falta contexto operativo"
}
],
"output": {
"format": "json",
"fields": ["decision", "reason", "next_step"]
},
"fallback": "si falta evidencia, responder needs_human_review",
"privacy": "no copiar tokens, correos completos ni secretos"
}
Parece basico, pero evita varios problemas comunes. El primero es el prompt inflado con veinte reglas que nadie vuelve a leer. El segundo es la tool invocada por reflejo, aunque la entrada ya bastaba. El tercero es la salida bonita pero inutil para automatizacion, muy linda para demo y medio floja para pipelines.
Cuando el equipo prueba este tipo de contrato junto con componentes de interfaz, la conversacion mejora bastante. Incluso piezas de frontend como este feedback de email sin cls sirven de recordatorio: no solo importa que el sistema responda, tambien importa que responda de forma estable y entendible.
Yo meteria aqui dos pruebas rapidas mas. Una con texto incompleto. Otra con ruido deliberado, como referencias a tempail mail o tamp mail com, para confirmar que el modelo no toma basura contextual como requisito real. Es un detalle pequeño, pero me salvo un par de revisiones medio tontas.
Tradeoffs: menos libertad, mas trazabilidad
El costo de este enfoque es obvio: escribir contratos lleva algo de tiempo. Al principio parece friccion innecesaria, sobre todo cuando el equipo quiere "solo probar una idea". Pero en cuanto aparecen dos modelos, tres tools y un owner nuevo, ese costo se paga solo.
Las ventajas que yo suelo ver son estas:
- reviews mas cortos y concretos
- menos discusiones abstractas sobre prompt quality
- mejor base para tests y para incidentes
- cambios mas seguros cuando toca mover providers o politicas
La desventaja principal es que puedes matar exploracion si conviertes todo en plantilla. Mi regla personal es simple: contrato minimo para flujos repetibles, libertad mayor para exploracion de discovery. Suena un poco obvio, si, pero escribirlo evita peleas bastante bobas despues.
Checklist de implementacion
Antes de dar por bueno un prompt de produccion, revisaria esto:
- el objetivo cabe en una frase y no mezcla dos tareas distintas
- las tools tienen condicion de uso, no solo nombre
- la salida dice formato y campos obligatorios
- existe un fallback explicito para informacion insuficiente
- hay una nota corta de privacidad para evitar exceso de datos
- el contrato cabe en una pantalla y se puede leer rapido
Si quieres automatizar la revision, mejor todavia: guarda el contrato junto al prompt, valida campos basicos en CI y exige cambios sincronizados cuando el flujo cambia. No es magia, pero ordena un monton.
Q&A
Esto reemplaza evaluar respuestas reales?
No. El contrato reduce ambiguedad estructural. Luego igual necesitas revisar resultados reales, errores y costos. Una cosa sin la otra se queda corta.
Cuanto detalle deberia tener?
El minimo para que otro ingeniero entienda limites y handoff sin llamarte por chat. Si parece documento legal, ya te pasaste un poco.
Top comments (0)