Gestión y versionado de prompts

Un prompt en producción forma parte del comportamiento de tu software. La gestión de prompts es la disciplina de tratarlo así: saber qué versión se está ejecutando, quién la cambió y por qué, si se probó y cómo volver atrás. A esta práctica se la llama a veces PromptOps.

Los problemas que resuelve

• Un prompt se edita en un panel de control y nadie sabe decir cómo era la semana pasada.
• El mismo prompt se copia en cuatro servicios y tres de ellos están desactualizados.
• Un pequeño cambio de redacción duplica el coste de tokens y se descubre en la factura.
• Una actualización del modelo cambia el comportamiento y no hay una prueba que muestre cómo.
• Una clave de API se pega en un archivo de prompt y se sube al repositorio.

Guarda los prompts como archivos

Mantén cada prompt en su propio archivo bajo control de versiones, junto al código que lo usa.

prompts/
  support-reply.md
  ticket-classify.md
  summarize-incident.md

Los archivos te dan historial, diferencias, revisión, autoría y reversión sin coste. Basta un archivo de texto plano o Markdown con variables con nombre:

## Task
Classify the support ticket as billing, bug, or feature request.

## Output format
Return only the label.

## Input
<ticket>
{{ticket}}
</ticket>

Evita construir prompts por concatenación de cadenas repartida entre funciones. Si nadie puede leer el prompt completo en un solo lugar, nadie puede revisarlo.

Separa la plantilla de los datos

Una plantilla de prompt tiene instrucciones fijas y variables con nombre. Mantenlas separadas:

• Las variables son explícitas. {{ticket}}, no un hueco de formato sin nombre.
• Cada variable está delimitada. Envuelta en etiquetas, para que el texto insertado no pueda leerse como instrucciones.
• El renderizado ocurre en un solo lugar. Una función rellena las plantillas, escapa la entrada y registra qué versión de plantilla se usó.

Versiona cada cambio

Usa los commits como versiones. Cada cambio tiene un autor, una fecha y un mensaje que explica por qué.

Registra el par que importa. El comportamiento depende del prompt y del modelo. Registra tanto la versión del prompt como el identificador del modelo en cada solicitud, para poder rastrear una salida hasta lo que la produjo.

Escribe un registro de cambios para los prompts importantes. Una línea por cambio: qué, por qué y el efecto en los resultados de las pruebas.

Etiqueta las versiones. Cuando se despliega un prompt, etiquétalo. Volver atrás pasa a ser una operación conocida.

Revisa los cambios de prompts como los cambios de código

Una diferencia en un prompt merece una revisión de verdad. Los revisores deberían preguntarse:

• ¿El cambio contradice una instrucción existente?
• ¿Se eliminó algo, como una restricción o el formato de salida?
• ¿Se movió el recuento de tokens y es aceptable?
• ¿Existe una prueba para el comportamiento que este cambio pretende corregir?

Las comprobaciones automáticas responden a varias de estas preguntas antes de que mire una persona. La puerta de pruebas de prompts hace fallar la compilación cuando un archivo de prompt cae por debajo de una puntuación de calidad mínima, supera un presupuesto de tokens o contiene un hallazgo crítico. La configuración vive en el repositorio:

{
  "include": ["prompts/**/*.md"],
  "model": "gpt-4.1",
  "minScore": 70,
  "maxTokens": 2000,
  "failOn": "critical"
}

Como las comprobaciones son deterministas y sin conexión, no necesitan clave de API en CI y nunca producen un fallo intermitente.

Prueba antes de publicar

Las comprobaciones estáticas confirman que el prompt es sólido. Un conjunto de pruebas de salida confirma que sigue comportándose. Ejecuta ambos cuando cambie un prompt, y vuelve a ejecutar las pruebas de salida cuando cambie la versión del modelo. Consulta las pruebas y la evaluación de prompts.

Despliega gradualmente

Para prompts con tráfico real:

1. Sombra. Ejecuta la versión nueva junto a la antigua y compara salidas sin mostrárselas a los usuarios.
2. Canario. Envía una pequeña parte del tráfico a la versión nueva y vigila las tasas de error, la validez del formato y las señales de los usuarios.
3. Promociona o revierte. Decide con los números.

Mantén desplegable la versión anterior hasta que la nueva se haya demostrado.

Supervisa en producción

Registra por versión de prompt:

• Tokens de entrada y de salida, y coste.
• Latencia.
• Proporción de respuestas que fallan la validación.
• Rechazos y alternativas de reserva.
• Opiniones de los usuarios cuando las recojas.

Ten cuidado con lo que registras. Los prompts y las salidas pueden contener datos personales y secretos. Registra metadatos por defecto y oculta el contenido antes de almacenarlo. Consulta la detección de PII y secretos en prompts.

Mantén los secretos fuera de los prompts

Los archivos de prompts se leen, se comparan, se comparten y se envían a terceros. No guardes nunca credenciales en ellos. Pasa los secretos a las herramientas a través de tu aplicación, no a través del contexto del modelo. Un escáner en CI detecta los descuidos; el escáner de seguridad de prompts falla ante cualquier credencial detectada.

Propiedad y reutilización

• Asigna un responsable a cada prompt. Alguien decide los cambios y responde a las preguntas.
• Comparte mediante una biblioteca, no copiando. Una sola fuente, importada donde haga falta.
• Documenta el contrato. Qué variables recibe, qué devuelve y qué da por supuesto.
• Retira los prompts antiguos. Los prompts sin uso siguen siendo copiados por la siguiente persona que los encuentra.

Ayudan los puntos de partida seleccionados y probados. Las plantillas de PromptFlowEngine se mantienen con una puntuación alta y sin advertencias en cada compilación.

Herramientas específicas o archivos simples

Las plataformas de gestión de prompts añaden un editor visual, seguimiento de experimentos y acceso para quien no es ingeniero. Valen la pena cuando muchas personas ajenas a ingeniería editan prompts. Para la mayoría de los equipos, los archivos en git más comprobaciones automáticas dan lo esencial sin nada nuevo que operar. Elijas lo que elijas, los requisitos son los mismos: una única fuente de verdad, historial, revisión, pruebas y reversión.

Una lista de comprobación para empezar

• Todo prompt de producción es un archivo bajo control de versiones.
• Las variables tienen nombre y están delimitadas.
• La versión del prompt y el modelo se registran con cada solicitud.
• Se ejecuta una comprobación estática en cada pull request.
• Existe un conjunto de pruebas que se ejecuta cuando cambia el prompt o el modelo.
• Los presupuestos de tokens están fijados y se aplican.
• Sin secretos en los archivos de prompts, comprobado automáticamente.
• Hay una forma documentada de volver atrás.