Versionado de prompts y gestión del catálogo
En esta página
Lección actualizada el 3 de noviembre de 2026 según la documentación de OpenAI:
temperatureytop_psolo se aceptan con un esfuerzo de razonamiento denone, mientras que los modelos GPT-5.6 razonan por defecto (medium). Por tanto, las llamadas que establezcan estos parámetros deben especificarreasoning={"effort": "none"}(API de Responses) oreasoning_effort="none"(Chat Completions). Fuentes: Uso de GPT-6 · GPT-5.6 Terra.
Versionado de prompts y gestión del catálogo
En producción, tus prompts evolucionan tanto como tu código. Sin un sistema de versionado, pierdes el rastro de los cambios, no puedes revertir a versiones anteriores y desconoces qué versión se está ejecutando en producción. Esta lección te muestra cómo gestionar los prompts como artefactos de software.
Por qué versionar los prompts
Un cambio en un prompt puede alterar radicalmente el comportamiento de tu aplicación. A diferencia del código, estos cambios suelen ser sutiles y difíciles de detectar sin pruebas automatizadas: una frase reformulada, una palabra desplazada, y el modelo comienza a clasificar mal uno de cada diez casos límite. Ninguna prueba unitaria estándar detectará esta brecha, pero el equipo de soporte la señalará tres semanas después como una queja vaga sobre tickets mal derivados.
El versionado responde a cuatro necesidades distintas. Primero, la trazabilidad: saber quién cambió qué y cuándo convierte un debate estéril en el equipo en una simple consulta del historial. Segundo, la reversión (rollback): cuando aparece una regresión, el objetivo inmediato no es entender el porqué, sino restaurar un comportamiento conocido. Tercero, la comparación de rendimiento: esto exige que las versiones antiguas sigan siendo ejecutables exactamente como fueron, con su modelo y configuración originales. Por último, la auditoría: para sistemas sujetos al RGPD (Reglamento General de Protección de Datos) u otros marcos de cumplimiento, debes demostrar qué instrucciones estaban vigentes en una fecha determinada; una captura de pantalla no es suficiente.
Estructura del catálogo
La clase PromptCatalog satisface estas necesidades con una infraestructura mínima: una carpeta por prompt, un archivo JSON por versión, numerados secuencialmente. Cada archivo agrupa el texto del prompt del sistema junto con el modelo y la temperatura asociados; un prompt ajustado a 0,1 y ese mismo prompt a 0,7 no son lo mismo, y bloquearlos juntos evita restaurar el texto olvidando su configuración.
El campo status rastrea el ciclo de vida. Una versión comienza como draft (borrador), lo que permite la preparación y las pruebas sin afectar al tráfico en vivo. Llamar a activate la cambia a active (activa) y degrada automáticamente la versión anterior a deprecated (obsoleta), garantizando que solo una versión sirva tráfico en cualquier momento. Este método hace que la reversión sea trivial: reactivar una versión anterior es una única llamada, no un despliegue. Tu aplicación llama a get_active en producción, mientras que list_versions facilita las revisiones y auditorías.
import json
from datetime import datetime
from pathlib import Path
class PromptCatalog:
"""Gestor de catálogo de prompts con versionado."""
def __init__(self, catalog_dir: str = "prompts/"):
self.catalog_dir = Path(catalog_dir)
self.catalog_dir.mkdir(parents=True, exist_ok=True)
def save_prompt(self, name: str, system_prompt: str,
model: str, temperature: float,
metadata: dict = None) -> str:
"""Guarda una nueva versión de un prompt."""
prompt_dir = self.catalog_dir / name
prompt_dir.mkdir(exist_ok=True)
# Determinar el número de versión
versions = sorted(prompt_dir.glob("v*.json"))
version = len(versions) + 1
version_str = f"v{version:03d}"
# Guardar
prompt_data = {
"name": name,
"version": version_str,
"created_at": datetime.now().isoformat(),
"model": model,
"temperature": temperature,
"system_prompt": system_prompt,
"metadata": metadata or {},
"status": "draft" # draft | active | deprecated
}
filepath = prompt_dir / f"{version_str}.json"
filepath.write_text(json.dumps(prompt_data, indent=2,
ensure_ascii=False))
return version_str
def get_prompt(self, name: str,
version: str = "latest") -> dict:
"""Recupera un prompt por nombre y versión."""
prompt_dir = self.catalog_dir / name
if version == "latest":
versions = sorted(prompt_dir.glob("v*.json"))
if not versions:
raise FileNotFoundError(f"Prompt '{name}' no encontrado")
filepath = versions[-1]
else:
filepath = prompt_dir / f"{version}.json"
return json.loads(filepath.read_text())
def get_active(self, name: str) -> dict:
"""Recupera la versión activa de un prompt."""
prompt_dir = self.catalog_dir / name
for filepath in sorted(prompt_dir.glob("v*.json"),
reverse=True):
data = json.loads(filepath.read_text())
if data["status"] == "active":
return data
raise FileNotFoundError(
f"No hay versión activa para '{name}'"
)
def activate(self, name: str, version: str):
"""Activa una versión y desactiva las demás."""
prompt_dir = self.catalog_dir / name
for filepath in prompt_dir.glob("v*.json"):
data = json.loads(filepath.read_text())
if data["version"] == version:
data["status"] = "active"
elif data["status"] == "active":
data["status"] = "deprecated"
filepath.write_text(json.dumps(data, indent=2,
ensure_ascii=False))
def list_versions(self, name: str) -> list[dict]:
"""Lista todas las versiones de un prompt."""
prompt_dir = self.catalog_dir / name
versions = []
for filepath in sorted(prompt_dir.glob("v*.json")):
data = json.loads(filepath.read_text())
versions.append({
"version": data["version"],
"status": data["status"],
"created_at": data["created_at"],
"model": data["model"]
})
return versions
Uso del catálogo en tu aplicación
Por parte del llamador, la regla es simple: tu código no contiene texto de prompt; solicita la versión activa al catálogo. Esto mantiene los prompts modificables sin tocar el código de la aplicación y evita que cadenas de treinta líneas queden enterradas en medio de una función. Los metadatos guardados durante el almacenamiento —autor, descripción, registro de cambios— no tienen efecto en la ejecución, pero hacen que el historial sea legible seis meses después, cuando nadie recuerda por qué cambió la redacción.
El detalle crítico reside al final de classifier_ticket: la respuesta devuelta incluye prompt_version. Registra este campo con cada resultado y el análisis de incidentes será posible; sabrás que los tickets mal clasificados de la tarde del martes provenían todos de la v004, sin necesidad de cruzar marcas de tiempo de despliegue.
from openai import OpenAI
client = OpenAI()
catalog = PromptCatalog("prompts/")
# Guardar un prompt
catalog.save_prompt(
name="ticket-classifier",
system_prompt="""Eres un clasificador de tickets de soporte.
Categoriza cada ticket como: bug, feature, question, billing.
Responde en JSON con category, priority (1-5), summary.""",
model="gpt-5.6-terra",
temperature=0.1,
metadata={
"author": "marie.dupont",
"description": "Clasificación automática de tickets de Zendesk",
"changelog": "Versión inicial"
}
)
# En producción: usar la versión activa
def classifier_ticket(ticket_text: str) -> dict:
"""Clasifica un ticket usando el prompt activo."""
prompt_config = catalog.get_active("ticket-classifier")
response = client.responses.create(
model=prompt_config["model"],
reasoning={"effort": "none"}, # temperature requiere effort none
instructions=prompt_config["system_prompt"],
input=ticket_text,
temperature=prompt_config["temperature"]
)
return {
"result": json.loads(response.output_text),
"prompt_version": prompt_config["version"]
}
Versionado con Git
Para equipos, guarda tus prompts en un repositorio Git dedicado. El árbol siguiente sigue una convención simple: una carpeta por prompt, que contiene su definición, casos de prueba y registro de cambios. Mantener las pruebas junto al prompt que verifican no es cosmético; una pull request modifica ambos juntos, y el revisor juzga el cambio basándose en pruebas y no en intenciones declaradas.
prompts/
ticket-classifier/
prompt.yaml
tests/
test_cases.json
CHANGELOG.md
invoice-extractor/
prompt.yaml
tests/
test_cases.json
CHANGELOG.md
YAML reemplaza aquí a JSON por una razón específica: los prompts son textos multilínea, y la sintaxis | los muestra exactamente como se envían, sin caracteres de escape ni \n extraños. Un diff de Git en este archivo se lee como un diff de prosa: el revisor ve que se ha añadido una frase. El esquema de salida viaja en el mismo archivo, de modo que la configuración completa de una llamada cabe en un único artefacto.
# prompts/ticket-classifier/prompt.yaml
name: ticket-classifier
model: gpt-5.6-terra
temperature: 0.1
max_output_tokens: 500
system_prompt: |
Eres un clasificador de tickets de soporte.
Categoriza cada ticket como: bug, feature, question, billing.
Responde en JSON con category, priority (1-5), summary.
schema:
type: object
properties:
category:
type: string
enum: [bug, feature, question, billing]
priority:
type: integer
summary:
type: string
required: [category, priority, summary]
additionalProperties: false
Buenas prácticas
Lo que separa un catálogo vivo de una carpeta de archivo se reduce a unas pocas reglas de mantenimiento. Mantén un prompt por archivo: mezclar múltiples prompts en un solo documento hace que los diffs sean ilegibles y las reversiones imposibles de dirigir. Exige un registro de cambios que documente no qué cambió —el diff ya muestra eso—, sino por qué: «añadida instrucción sobre tickets multilingües tras comentarios de soporte» vale más que diez líneas de descripción técnica.
Asocia sistemáticamente un conjunto de pruebas a cada prompt; de lo contrario, serán los usuarios los primeros en avisarte cuando una modificación rompa un comportamiento establecido. Canaliza los cambios de prompt a través del mismo proceso de revisión de código que el código mismo: un prompt que llega a producción sin revisión produce las mismas sorpresas que un código no revisado. Verifica que la reversión tome menos de un minuto y pruébala en un día tranquilo, no durante un incidente. Por último, marca las versiones desplegadas con etiquetas para vincular sin ambigüedades el comportamiento observado con un estado específico del repositorio.
Prueba del catálogo con una reversión
Configura un PromptCatalog para tres prompts reales de tu aplicación y registra dos o tres versiones de cada uno evolucionando las instrucciones en pequeños pasos: una instrucción de tono, una categoría añadida. El versionado demuestra su valía en estos cambios de grano fino, porque son los que no recordarás haber hecho. Configura la activación y desactivación, y adjunta un conjunto de pruebas a cada prompt.
Termina con el ejercicio más instructivo: activa deliberadamente una versión degradada, observa la regresión mediante las pruebas y ejecuta la reversión cronometrándola. Si la operación supera el minuto, arregla el procedimiento antes de añadir un solo prompt al catálogo; una reversión lenta no es una reversión, es un incidente prolongado.
Puntos clave
- Los prompts son artefactos de software que requieren versionado
- Cada versión es un archivo JSON o YAML con metadatos
- El estado (draft, active, deprecated) permite un despliegue gradual
- Almacena los prompts en Git con pruebas y un registro de cambios
- La reversión debe ser instantánea en caso de regresión