Diseñar prompts para producción: capas del sistema, del desarrollador y del usuario

En un prototipo, un prompt puede ser una cadena de texto escrita en una tarde. En producción, ese enfoque suele venirse abajo durante el primer mes.

Necesitarás cambiar una parte de las instrucciones sin alterar las demás. Necesitarás comportamientos distintos según el nivel del cliente, comparar versiones mediante pruebas A/B, volver atrás cuando algo falle y saber cuándo se modificó el prompt por última vez y por qué.

Un sistema de prompts de producción resuelve todo esto. No se trata de «escribir una cadena», sino de diseñar una arquitectura.

Este artículo explica esa arquitectura: las tres capas, la disciplina de las plantillas, el control de versiones, la evaluación y las prácticas operativas que convierten los prompts en infraestructura.

El trabajo con prompts de producción tiene dos artefactos separados: plantillas reutilizables y datos por solicitud. Versiona las plantillas como código. Trata los prompts renderizados y las respuestas del modelo como registros sensibles siempre que contengan datos del usuario, del cliente o internos.

Las tres capas

Los prompts de producción constan de tres capas distintas, cada una con una responsabilidad:

Capa del sistema. Comportamiento estable, identidad, restricciones. Cambia raramente. Es propiedad del equipo que diseña el comportamiento de la IA.

Capa del desarrollador. Instrucciones específicas de cada funcionalidad, descripciones de herramientas y requisitos del formato de salida. Cambia cuando lo hace la funcionalidad. Es responsabilidad del equipo que la mantiene.

Capa del usuario. La solicitud concreta del usuario y el contexto dinámico: sus datos, el historial de la conversación y el conocimiento recuperado. Es distinta en cada llamada.

Mezclar estas capas es el error más común al crear prompts de producción. El prompt del sistema acaba teniendo 5,000 palabras que combinan identidad, instrucciones específicas de funcionalidades y contexto dinámico; cualquier cambio termina rompiendo otra cosa.

Separarlas es fundamental:

┌─────────────────────────────────────┐
│ System prompt (stable)              │  Identity, behavior, hard constraints
├─────────────────────────────────────┤
│ Developer prompt (per-feature)      │  Feature instructions, tools, format
├─────────────────────────────────────┤
│ User prompt (per-call)              │  User query, context, conversation
└─────────────────────────────────────┘

Las API de los modelos admiten explícitamente esta separación:

• OpenAI: system, developer, user roles.
• Anthropic: system, seguido de messages con los roles user y assistant. Las descripciones de herramientas se proporcionan en un parámetro independiente.
• Gemini: systemInstruction, seguido de contents con sus roles.

Aprovecha estas distinciones de forma deliberada.

Capa 1: El prompt del sistema

El prompt del sistema define quién es la IA y cómo debe comportarse. Cambia con poca frecuencia.

Un buen prompt del sistema cubre:

Identidad. Quién es la IA. «Eres un asistente de IA de [Empresa], especializado en [dominio]».

Voz y estilo. Cómo debe sonar. Características específicas, no descripciones vagas.

Restricciones estrictas. Acciones que nunca debe realizar: generar determinado contenido, tomar ciertas decisiones o ignorar ciertas instrucciones.

Patrones de comportamiento. Cómo debe gestionar situaciones habituales: rechazos, derivaciones e incertidumbre.

Seguridad y cumplimiento normativo. Avisos obligatorios, requisitos regulatorios y políticas de contenido.

Lo que no debe contener:

• Instrucciones específicas de funcionalidades («para los correos de ventas, haz X»).
• Contexto dinámico («el historial de pedidos del usuario es…»).
• Descripciones de herramientas (van a otro lugar).
• Cosas que cambian con frecuencia.

Un buen prompt del sistema tiene 300-1000 palabras. Si es más largo, resulta difícil de gestionar; si es más corto, probablemente no define el comportamiento con suficiente precisión.

Una plantilla que funciona:

You are [name], an AI assistant for [company / context].

## Your role
[2-3 sentences on what you do]

## Voice and style
- [Specific trait 1]
- [Specific trait 2]
- [Specific trait 3]
- Do not [anti-pattern 1]
- Do not [anti-pattern 2]

## Hard constraints
- Never [hard rule 1]
- Never [hard rule 2]
- Always [hard rule 3]

## How to handle uncertainty
- If you don't know something factual: say so explicitly.
- If a user asks for something outside scope: offer what you can help with.
- If a request might cause harm: refuse and explain why.

## Format expectations
- Plain text by default
- Use markdown when displaying code or structured data
- Be concise; do not pad responses with filler

Este es el armazón por el que pasa cada interacción. Sus cambios deben ser deliberados y poco frecuentes.

Capa 2: El prompt del desarrollador

El prompt del desarrollador es específico de cada funcionalidad. Cada funcionalidad utiliza el suyo.

Un prompt del desarrollador para una función de resumen:

Task: produce a summary of the document below.

Requirements:
- 3-5 bullet points
- Each bullet is one complete sentence
- Focus on facts and concrete claims, not impressions
- If the document contains numbers, include the most important ones
- Do not include marketing language or speculation
- If the document is ambiguous about something important, note it

Format: plain markdown bullets, no preamble.

Un prompt del desarrollador para una función de revisión de código:

Task: review the code diff below.

Output a JSON object with:
- summary: 1-2 sentence overview of the change
- concerns: array of specific issues (each: file, line, severity, description)
- suggestions: array of improvements (each: file, line, suggestion)
- approved: boolean (true if no blocking concerns)

Severity levels:
- "blocker": must be fixed before merge
- "warning": should be addressed but not blocking
- "nit": stylistic, optional

Focus on:
- Logic errors
- Security issues
- Performance issues
- Missing test coverage
- Unclear naming or structure

Skip:
- Formatting (handled by formatter)
- Subjective style preferences

Cada funcionalidad tiene su propio prompt del desarrollador. Cada uno se almacena, versiona y evalúa por separado.

Capa 3: El prompt del usuario

La capa del usuario es dinámica. Normalmente incluye:

La solicitud real del usuario. «Resume este documento».

El contexto recuperado por el sistema. Documentos de RAG, historial del cliente e historial de la conversación.

Variables por llamada. Nombre del usuario, zona horaria, preferencia de idioma, nivel de cuenta.

Esta capa se construye mediante código en el momento de la llamada. Suele presentar una estructura como esta:

{conversation_history_summary}

{retrieved_context}

User's request: {user_query}

Additional context:
- User name: {name}
- User timezone: {timezone}
- User tier: {tier}

La estructura exacta depende de la funcionalidad. El principio es sencillo: los datos se incluyen aquí, no en los prompts del sistema ni del desarrollador.

Disciplina de plantillas

Los prompts de producción se construyen a partir de plantillas. Concatenar cadenas directamente en el código puede servir en un prototipo, pero no escala.

Un sistema de plantillas simple:

from string import Template

SUMMARIZE_TEMPLATE = Template("""
$conversation_summary

Document to summarize:
$document

User's specific instructions: $user_instructions
""")

prompt = SUMMARIZE_TEMPLATE.substitute(
    conversation_summary=summarize_conversation(history),
    document=document_text,
    user_instructions=user_query,
)

En sistemas más sofisticados, puede utilizarse una biblioteca de plantillas (Jinja2, Handlebars) con condicionales y plantillas parciales.

{% if user_tier == "enterprise" %}
You have access to advanced analysis features.
{% endif %}

{% if retrieved_context %}
Relevant context from your knowledge base:
{{ retrieved_context }}
{% endif %}

User's request: {{ user_query }}

Las plantillas ayudan a evitar la inyección de prompts a través de variables —siempre que la entrada del usuario se escape cuando sea necesario—, permiten aplicar lógica condicional y mantienen una estructura coherente.

Control de versiones

Los prompts son código. Guárdalos en un sistema de control de versiones.

Un patrón que funciona: un directorio prompts/ en tu repositorio, con un archivo por prompt:

prompts/
  system/
    main.txt
    customer-support.txt
    code-assistant.txt
  features/
    summarize.txt
    classify-ticket.txt
    generate-email.txt
  templates/
    base.j2

Cada archivo contiene un prompt independiente y conserva su propio historial de commits. Los cambios se revisan mediante una PR y los despliegues de producción hacen referencia a versiones concretas.

Por qué esto importa:

• Visibilidad de los cambios. Cuando se modifica un prompt, el diff queda en la PR y los revisores pueden ver exactamente qué ha cambiado.
• Reversión. Si un cambio rompe algo, puedes revertirlo.
• Historial. «¿Cuándo cambiamos la política de reembolsos del prompt?» «¿Por qué está aquí este párrafo?» Son preguntas que pueden responderse mediante git blame.
• Herramientas. Linters, validadores, suites de evaluación se integran con prompts basados en archivos.

Evita almacenar los prompts como cadenas dentro del código —son difíciles de encontrar y comparar—, en una herramienta con interfaz gráfica —el versionado queda en manos de esa herramienta— o copiarlos desde las conversaciones de otras personas —no tienen trazabilidad ni pruebas—.

No incluyas en el repositorio conversaciones de producción, registros de clientes, tickets de soporte, documentos internos ni prompts renderizados que contengan variables sensibles. El control de versiones debe contener plantillas reutilizables, fixtures y ejemplos de evaluación saneados. Las trazas reales deben guardarse en un sistema de observabilidad con políticas de retención, control de acceso y anonimización.

Prompt como datos: almacenamiento externo

Para los prompts que cambian con frecuencia —por pruebas A/B, variaciones según el nivel de usuario o versiones específicas por idioma—, el control de versiones basado en archivos puede ser demasiado lento.

Una solución consiste en utilizar una base de datos o un servicio que almacene versiones de los prompts junto con sus metadatos.

prompt = prompt_service.get(
    name="summarize",
    version="v3",
    locale="en",
    user_tier="enterprise",
)

El servicio mantiene:

• Versiones actuales e históricas de cada prompt.
• Metadatos: cuándo se añadió, por quién, por qué.
• Puntajes de evaluación adjuntos a cada versión.
• Capacidad de reversión.

Herramientas: PromptLayer, Helicone o una solución interna. Para la mayoría de los equipos, una implementación interna con un esquema de base de datos sencillo funciona bien.

La interfaz es fundamental. Tanto los perfiles técnicos como los no técnicos —producto o contenido— deben poder editar los prompts. Sin embargo, todos los cambios deben revisarse y superar las evaluaciones antes de llegar a producción.

Cambios sujetos a evaluación

Cada cambio en un prompt debe superar las evaluaciones antes de desplegarse. En un sistema de producción serio, este requisito no es negociable.

El flujo:

1. Una persona del equipo, sea técnica o no, prepara un cambio en el prompt.
2. El cambio se ejecuta contra la suite de evaluación.
3. Los resultados de la evaluación se revisan junto con el cambio.
4. Si las evaluaciones se superan —sin regresiones y, preferiblemente, con mejoras—, el cambio puede aprobarse.
5. Los cambios aprobados se despliegan.
6. La monitorización posterior al despliegue detecta lo que las evaluaciones hayan podido pasar por alto.

En la práctica, cada prompt debe tener una suite de evaluación que se ejecute en CI cada vez que cambie.

Sin este control, los cambios pueden provocar fallos impredecibles. Con él, puedes avanzar con rapidez y confianza.

Lista de verificación práctica para una publicación

Antes de que una versión de prompt vaya a producción, exige una breve lista de verificación:

La lista complementaria enlazada desde este artículo convierte estas comprobaciones en un proceso de publicación repetible.

Pruebas A/B en producción

Al probar un prompt nuevo frente a la versión existente con una pequeña fracción del tráfico de producción, obtienes señales del mundo real que complementan las evaluaciones.

Patrón:

• El 95% del tráfico usa el prompt de producción v3.
• El 5% recibe la versión candidata v4.
• Se miden los comentarios de los usuarios, las métricas posteriores del flujo y las puntuaciones de evaluación sobre tráfico real.
• Cuando haya suficientes datos, se decide si desplegar v4 al 100% o mantener v3.

Herramientas: indicadores de funcionalidad (LaunchDarkly o una solución interna), servicios de versionado de prompts (PromptLayer) o enrutamiento personalizado.

Limitaciones:

• Las pruebas A/B solo capturan las señales que se miden. Si no dispones de comentarios de usuarios ni de métricas de conversión posteriores, aportarán poca información.
• La significancia estadística requiere volumen. Para funciones de bajo volumen, las pruebas A/B son difíciles.
• No ejecutes demasiadas pruebas A/B a la vez; sus interacciones dificultan la interpretación de los resultados.

Observabilidad de prompts

Cada llamada de LLM en producción debe registrar:

• Qué plantilla de prompt se usó (nombre, versión).
• Qué variables se sustituyeron, utilizando nombres permitidos y valores anonimizados cuando sea necesario.
• El prompt final renderizado, pero solo cuando la política lo permita; de lo contrario, una representación anonimizada, muestreada o resumida mediante un hash.
• La respuesta del modelo, anonimizada o muestreada en los flujos de trabajo sensibles.
• Latencia, tokens y coste.
• Señales posteriores: comentarios de los usuarios y métricas de éxito.

Estos son los datos necesarios para investigar «¿por qué dio el modelo una respuesta extraña a este usuario?». Sin ellos, solo puedes hacer conjeturas.

Almacenamiento: una tabla de base de datos o una herramienta de observabilidad. Registrar todo tiene un coste real —volumen de llamadas × cantidad de tokens × almacenamiento— y también supone un riesgo para la privacidad. Decide en cada flujo de trabajo qué campos pueden almacenarse de forma segura, anonimiza por defecto los secretos y los datos personales y aplica periodos de retención cortos, salvo que exista un requisito normativo para conservar las trazas durante más tiempo. Algunos equipos solo guardan una muestra.

Revisión: establece una práctica periódica —por ejemplo, semanal— para leer una muestra de prompts y respuestas reales de producción. Así detectarás problemas que las evaluaciones no cubren.

Antipatrones de prompts

Algunos patrones a evitar:

Antipatrón 1: el megaprompt. Un prompt del sistema de 10,000 palabras que intenta cubrir todas las situaciones. Es difícil de modificar y depurar, y el modelo suele ignorar las instrucciones que aparecen al final.

Solución: divídelo en capas y utiliza prompts específicos, uno por funcionalidad.

Antipatrón 2: concatenación directa de cadenas.

prompt = "You are helpful. " + (
    "The user is a paid customer. " if user.tier == "paid" else ""
) + f"Their name is {user.name}. " + ...

Es frágil, difícil de leer y vulnerable a la inyección de prompts.

Solución: sistema de plantillas.

Antipatrón 3: el mismo prompt para demasiados casos de uso.

Un único prompt general se utiliza para redactar correos, revisar código, prestar soporte al cliente e investigar. Son tareas diferentes y un solo prompt no estará optimizado para ninguna.

Solución: utiliza prompts del desarrollador específicos para cada funcionalidad sobre un prompt del sistema compartido.

Antipatrón 4: prompts codificados de forma rígida.

response = openai.chat.completions.create(
    messages=[
        {"role": "system", "content": "You are a helpful assistant..."},
        {"role": "user", "content": query}
    ]
)

El prompt queda enterrado en el código. No puede editarse sin realizar un despliegue, compararse mediante pruebas A/B ni versionarse de forma independiente.

Solución: extrae a un archivo de prompt o servicio.

Antipatrón 5: ausencia de cobertura de evaluación.

Una funcionalidad se publica con un prompt que nunca se ha probado de forma sistemática. La calidad se basa en impresiones y no es posible detectar su degradación.

Solución: cada prompt tiene una suite de evaluación.

Antipatrón 6: mezclar datos con el prompt del sistema.

You are an assistant for John, a premium customer who joined in 2023, lives in Tallinn, and has 47 open tickets.

El prompt del sistema cambia ahora en cada llamada, lo que invalida la caché y genera confusión.

Solución: los datos dinámicos deben ir en la capa de usuario o contexto, no en el prompt del sistema.

Antipatrón 7: instrucciones enterradas en el cuerpo del prompt.

Help the user with their request. Be polite. Format output as JSON. Don't use markdown. The user is asking about pricing, so be careful about quoting numbers. Output should be 1-2 sentences. Now help them.

Las instrucciones importantes se pierden y es posible que el modelo no las tenga en cuenta.

Solución: utiliza secciones claras y coloca las instrucciones críticas al principio y al final; el efecto de recencia resulta útil.

Patrones para funcionalidades habituales

Estos son algunos patrones específicos:

Clasificación

Task: classify the following text into one of these categories:
- billing: payment, refund, subscription
- technical: bug, error, integration issue
- account: login, password, profile changes
- feature_request: new functionality requests
- complaint: general dissatisfaction without specific actionable issue

Output a JSON object: {"category": "<one of above>", "confidence": "<high|medium|low>", "reasoning": "<1 sentence>"}

Text to classify:
{text}

Patrones: categorías enumeradas con definiciones, salida estructurada y campos de confianza y razonamiento.

Extracción

Task: extract structured data from the document below.

Schema:
- vendor_name: company that issued the invoice
- invoice_number: as printed on the document
- date: ISO 8601 format
- line_items: array of {description, quantity, unit_price, total}
- subtotal, tax, total: numbers

Rules:
- If a field is not present, use null
- Numbers should be numeric, not strings
- For ambiguous cases, set "needs_review": true and explain

Document:
{document}

Patrones: esquema explícito, tipos esperados, tratamiento de datos ausentes y derivación de casos ambiguos.

Generación con estilo

Task: write a {format} on the topic of {topic}, targeting {audience}.

Style:
- {Specific style trait 1}
- {Specific style trait 2}
- Avoid: {anti-pattern 1}, {anti-pattern 2}

Constraints:
- Length: {N} words
- Include: {required elements}
- Exclude: {forbidden elements}

Voice reference:
[Provide a sample of the desired voice]

Output: the {format} only, with no preamble or post-script.

Patrones: rasgos de estilo concretos —no genéricos—, restricciones explícitas y una voz anclada mediante una muestra de referencia.

Bucle de un agente

You have access to the following tools:
{tool_descriptions}

For each turn:
1. Think about what you need to do.
2. Decide if you need a tool. If yes, call it.
3. After observing the result, decide if you need more tools or can answer.
4. When you have enough information, produce the final answer.

Constraints:
- Maximum 5 tool calls per request.
- If after 5 calls you can't complete, explain what's missing.
- Never invent tool names or arguments.
- Verify tool results before acting on them.

User request:
{user_query}

Patrones: pasos explícitos de razonamiento, límite de uso de herramientas, prevención de alucinaciones y reflexión.

El aspecto del equipo

Los prompts de producción suelen involucrar a varias personas:

• Ingeniería integra los prompts en el sistema, mantiene las plantillas y gestiona los despliegues.
• Producto define los resultados que deben lograr los prompts.
• Contenido/marketing es responsable de la guía de voz y estilo.
• Especialistas del dominio determinan qué es correcto en casos de uso específicos: lenguaje jurídico, terminología médica, etc.

Un patrón útil es establecer un proceso de «revisión de prompts» similar a la revisión de código, con las personas adecuadas para cada ámbito. El equipo de contenido revisa los cambios de voz; ingeniería, los cambios de lógica; y los especialistas, el contenido propio de su dominio.

En casos de uso sensibles —jurídicos, médicos o financieros—, los prompts pueden requerir una revisión y aprobación formales. Diseña el proceso en consecuencia.

Plan de madurez de prompts de 90 días

Para los equipos que quieren pasar de «los prompts son cadenas dentro del código» a «los prompts son infraestructura gestionada»:

Días 1-30: Fundamentos.

• Extrae todos los prompts a archivos dedicados en control de fuentes.
• Adopta el patrón de 3 capas (sistema / desarrollador / usuario).
• Construye una capa de plantillas simple.
• Configura un registro básico de prompts y respuestas.

Días 31-60: Evaluación.

• Construye suites de evaluación para los 5 prompts principales.
• Ejecuta las evaluaciones cada vez que cambie un prompt (al principio, de forma manual).
• Configura la integración de CI para evaluaciones (ejecución automática en PRs).

Días 61-90: Operaciones.

• Implementa el versionado de prompts (base de datos o servicio).
• Añade capacidad para realizar pruebas A/B en al menos un prompt crítico.
• Construye paneles para la calidad de los prompts de producción.
• Establece un proceso de revisión para los cambios en los prompts.

Después de 90 días, los prompts serán infraestructura gestionada. Los cambios serán deliberados, verificables, revisables y reversibles. La calidad podrá medirse y su degradación podrá detectarse.

Prompts como infraestructura

Los prompts de producción no son cadenas. Son un sistema en capas con disciplina alrededor del versionado, plantillas, evaluación y observabilidad.

La arquitectura de tres capas (sistema / desarrollador / usuario) separa responsabilidades y facilita el mantenimiento de los prompts. Las plantillas reducen la fragilidad. El control de versiones o un servicio de prompts proporciona un historial. Las evaluaciones controlan los cambios y la observabilidad detecta lo que estas pasan por alto.

En un entorno de producción serio, esto no es opcional. Los equipos que omiten estos pasos acaban sumidos en el caos: cadenas dispersas por el código, desconocimiento de la versión en producción, ausencia de métricas de calidad y cambios de comportamiento constantes e inexplicables.

Los equipos que invierten en infraestructura de prompts obtienen un comportamiento de la IA controlable, medible y mejorable. Esa es la diferencia entre una funcionalidad que evoluciona bien y otra que se convierte en deuda técnica.

Empieza con la arquitectura. Todo lo demás se vuelve más fácil.