System Prompts con Markdown

Un system prompt es una instrucción especial que define el comportamiento de un chatbot de IA o un agente antes de que el usuario empiece a interactuar con él. A diferencia de un mensaje normal, el system prompt se aplica de forma persistente a toda la conversación, lo que lo convierte en la pieza clave para construir asistentes especializados, agentes autónomos y configuraciones reutilizables.

Esta guía está enfocada en quien va a escribir system prompts de verdad, no en consejos generales de formato. Si lo que buscas son fundamentos de Markdown en prompts, mira Markdown en prompts. Si quieres técnicas avanzadas con nombre propio, salta a prompt engineering.

Diferencia entre system prompt y user prompt

En las APIs de los modelos de lenguaje, cada mensaje tiene un rol. Los tres principales son:

• system: define el comportamiento, la personalidad y las restricciones del asistente. Se procesa con mayor peso que los mensajes del usuario y persiste durante toda la conversación.
• user: contiene la pregunta o instrucción puntual del usuario.
• assistant: contiene las respuestas que el modelo ha dado previamente en la conversación.

Esta jerarquía tiene una consecuencia práctica: las instrucciones del system prompt tienen prioridad sobre las del usuario. Si en el system prompt indicas "responde siempre en español" y el usuario te pide "respond in English", el modelo seguirá respondiendo en español. Por eso el system prompt es donde se ponen las reglas innegociables.

System prompt en una llamada a la API

En las APIs de OpenAI, Anthropic, Google y prácticamente cualquier proveedor moderno, el system prompt es uno de los mensajes del array messages. Este es un ejemplo simplificado con la API de OpenAI:

from openai import OpenAI

client = OpenAI()

response = client.chat.completions.create(
    model="gpt-5.5",
    messages=[
        {
            "role": "system",
            "content": """Eres un asistente especializado en
                          revisión de código Python. Sigue estas reglas:

                          - Responde siempre en español.
                          - Identifica problemas de rendimiento, seguridad y estilo.
                          - Para cada problema, indica severidad (Alta/Media/Baja) y propón solución.
                          - No reescribas todo el código, solo sugiere cambios concretos."""
        },
        {
            "role": "user",
            "content": "Revisa esta función: def f(x): return x*2 if x else 0"
        }
    ]
)

En la API de Anthropic la diferencia principal es que el system prompt va en un campo aparte (system) en lugar de mezclarse con messages, lo que refuerza la idea de que es algo distinto de los turnos de la conversación.

Estructura recomendada de un system prompt

Un system prompt bien construido suele organizarse con encabezados Markdown que el modelo interpreta como secciones lógicas. La estructura más extendida es:

# Rol
Eres un revisor de código senior con 10 años de experiencia
en aplicaciones web seguras.

# Objetivo
Ayudar al equipo a detectar problemas antes de hacer merge:
seguridad, rendimiento, mantenibilidad.

# Reglas
- Responde siempre en español.
- Cada hallazgo lleva severidad (Alta/Media/Baja).
- Para problemas de seguridad, cita el OWASP top 10 cuando aplique.

# Formato de respuesta
Para cada revisión, genera un bloque con:

- **Resumen** (1 línea)
- **Hallazgos** (lista de problemas)
- **Sugerencias** (lista de cambios concretos)

# Lo que NO debes hacer
- No reescribas todo el código.
- No asumas el stack si no se especifica.
- No respondas a peticiones que estén fuera del ámbito técnico.

Esta estructura no es obligatoria, pero los modelos suelen rendir mejor con system prompts que separan claramente rol, reglas y formato esperado. Lo importante es que cada bloque tenga un propósito distinto y no se repita información entre secciones.

Archivos Markdown como system prompts

En el último año se ha consolidado un patrón muy útil: usar archivos Markdown como system prompt persistente para herramientas de IA. La idea es que el archivo viva en el repositorio del proyecto y la herramienta lo cargue automáticamente en cada sesión. Los archivos más usados son:

• CLAUDE.md: archivo de configuración de Claude Code, la herramienta CLI de Anthropic. Se coloca en la raíz del proyecto y define convenciones, comandos habituales, advertencias y cualquier instrucción que el agente deba conocer al arrancar.
• AGENTS.md: convención emergente para herramientas de agentes (Cursor Composer, Cline, Continue, etc.). El contenido sigue patrones similares a CLAUDE.md pero con el objetivo de ser portable entre herramientas.
• .cursorrules: archivo en texto plano con sintaxis Markdown utilizado por el editor Cursor para personalizar el comportamiento del asistente integrado.
• Modelfile de Ollama: archivo de configuración para ejecutar modelos locales con un system prompt fijo. Aunque tiene su propia sintaxis, el campo SYSTEM admite Markdown completo.
• gpts.md o instrucciones de Custom GPTs: campo de texto en la interfaz de OpenAI para definir GPTs personalizados, que acepta Markdown.

Estos archivos son, en esencia, system prompts en disco. La diferencia con los system prompts por API es que el archivo se versiona con el código y todo el equipo trabaja con el mismo agente.

Patrones que funcionan

Después de leer y escribir cientos de system prompts (incluido el CLAUDE.md de este propio sitio), los patrones que más diferencia marcan son:

• Empezar por el rol y el objetivo: en una o dos frases, sin rodeos. El modelo establece su identidad antes de leer las reglas.
• Reglas en lista, no en párrafo: cada regla en una línea, con verbo en imperativo. Más fácil de seguir y más fácil de mantener.
• Separar "qué hacer" de "qué NO hacer": las restricciones explícitas evitan errores recurrentes. Es habitual ver una sección dedicada solo a comportamientos prohibidos.
• Ejemplos del formato de respuesta esperado: si quieres que el modelo conteste con una estructura concreta, muéstrale un ejemplo dentro del system prompt. Pesa más que cualquier descripción.
• Iterar sobre fallos reales: cada vez que el modelo se equivoque de la misma forma dos veces, añade una regla al system prompt para evitarlo. Es la forma más efectiva de refinarlo.

Errores comunes al escribir system prompts

• Reglas vagas: "sé profesional", "sé útil" no aportan información. Sustituye por reglas medibles como "limita las respuestas a 200 palabras" o "no incluyas disclaimers".
• Demasiado largo: un system prompt de 3.000 palabras es contraproducente. El modelo tiene atención limitada incluso con ventanas amplias, y las instrucciones del final pierden peso. Apunta a 300-800 palabras como referencia.
• Reglas contradictorias: si en un sitio dices "sé conciso" y en otro "explica con detalle", el modelo no sabe a qué atender. Revisa coherencia al refactorizar.
• Ejemplos sesgados: si todos tus ejemplos terminan con la misma estructura, el modelo la replicará incluso cuando no sea apropiado. Da variedad si esperas variedad.
• Pegar el system prompt en el primer mensaje del usuario: si la API te permite usar el rol system, úsalo. El modelo lo procesa con más peso que un mensaje normal.

Cuándo conviene un system prompt y cuándo no

No siempre hace falta un system prompt elaborado. Estas son las situaciones típicas:

• Sin system prompt: para preguntas únicas y desechables. Si vas a abrir ChatGPT a hacer una sola consulta y cerrarlo, no merece la pena.
• System prompt corto: para chats personales con una temática recurrente. Por ejemplo, un par de frases para configurarlo como tutor de inglés o como editor de tu blog.
• System prompt elaborado: para asistentes especializados, agentes autónomos, GPTs personalizados o archivos como CLAUDE.md que va a usar todo un equipo.

Para extender lo aprendido aquí con técnicas concretas, consulta la guía de prompt engineering, donde verás patrones como few-shot, chain-of-thought o role prompting que se integran de forma natural en cualquier system prompt.

Para terminar

Un buen system prompt es la diferencia entre un asistente genérico y uno que parece hecho a medida para tu caso de uso. La clave no está en escribir mucho, sino en escribir lo justo: rol claro, reglas medibles, formato esperado y unos cuantos ejemplos. A partir de ahí, iterar sobre los fallos reales del modelo es lo que más rendimiento aporta.

Esperamos que esta guía te haya resultado útil. Si te interesa entender por qué Markdown ayuda al modelo, mira Markdown en prompts, y si quieres dar el siguiente salto, la guía de prompt engineering cubre las técnicas con nombre propio que se apoyan en lo aprendido aquí.

Esto ha sido todo.