Debuggear prompts: aislar la variable, después arreglar | Cleon

Un prompt se portó mal y alguien está esperando el arreglo. El instinto es abrirlo y reescribirlo entero — y es el instinto equivocado, porque un prompt es no determinístico, así que una reescritura que "se ve mejor en una corrida" no probó nada sobre si de verdad arregló el bug o solo tiró los dados y le tocó una mejor cara esta vez. El movimiento que cambia todo es el que casi todos se saltean bajo presión: cambiá una sola cosa por vez y puntuala contra un eval set. Aislá la variable. Un prompt son varias instructions, un orden, quizás algunos examples, todo interactuando — reescribí cinco cosas a la vez y aunque la salida mejore no podés decir cuál cambio lo hizo, ni si arreglaste el bug mientras rompías en silencio un vecino. Un edit, puntuado contra casos reales, te dice qué se movió (principio 3). La reescritura completa, mirada a ojo sobre una sola corrida, no te dice nada en lo que puedas confiar.

Esta página asume que tenés un eval set — un puñado de casos reales con resultados conocidos-buenos — porque nada de abajo funciona sin uno: un arreglo de prompt que no podés puntuar es una adivinanza con un tilde verde, y sobre un sistema no determinístico una sola corrida que pasa no es un puntaje. Es por síntoma: encontrá la falla que coincide con lo que estás viendo, inspeccioná la salida real en la capa que la sección señala, cambiá una variable, y — el paso que separa debuggear de jugar al topo — convertí el caso fallido en un caso de eval para que la regresión no pueda volver. Nada de esto depende del toolkit: un prompt que dirige una acción de Agentforce, una llamada al Claude API, o un paso adentro de un loop de LangGraph falla en las mismas cinco formas, y el eval set es donde las cazás a todas.

The loop: read the actual output → isolate one variable → eval-driven fix

Cada sesión de debug de abajo corre los mismos tres pasos, en este orden:

Leé la salida real. Traé lo que el prompt produjo de verdad en el caso fallido — el texto crudo, no tu recuerdo de él, y a través de varias corridas, no una, porque una corrida de un sistema no determinístico esconde si la falla es constante o intermitente. El bug se nombra distinto según dispare cada vez o una de cada cinco, y solo sabés cuál leyendo más de una sola corrida (principio 11).
Aislá una variable. Cambiá exactamente una cosa — mové una instruction, agregá un example, ajustá una regla, sacá una que pelea con otra — y mantené todo lo demás fijo. La razón misma por la que un prompt es difícil de debuggear es que sus partes interactúan; la disciplina que le gana es la misma sobre la que corre un experimento controlado, una variable por vez. Reescribí el prompt entero y no corriste ningún experimento — cambiaste una caja negra por otra.
Arreglar con evals. Agregá el caso fallido al eval set antes de cambiar nada, miralo fallar, hacé el único cambio, miralo pasar, y corré el set entero para confirmar que no rompiste un vecino. El caso de eval es lo que hace permanente el arreglo — sin él, la misma falla vuelve a entrar en el próximo edit de prompt o cambio de model y nadie lo nota (principio 3).

Ignora una instruction

Cómo reconocerlo. La regla está en el prompt — podés señalarla — y el model la rompe igual. La peor clase de bug para discutir, porque todos pueden ver que la instruction está ahí mismo en el texto, y el model igual no la siguió.

Qué inspeccionar. Encontrá dónde está la instruction y con qué compite. Dos formas, ambas cubiertas en system prompts and instructions y prompting gotchas (gotchas 1 y 3). Primero, salience: la regla está enterrada a mitad del prompt, la oración número once en un párrafo denso, ponderada igual que las diez que la rodean — presente pero no prominente. Segundo, contradicción: otra instruction la pelea en silencio — "sé conciso" contra "sé exhaustivo", una excepción que niega la regla de arriba — y el model está obedeciendo la que vos te olvidaste que estaba. Leé el prompt buscando las dos, porque el arreglo es opuesto: una necesita que la regla se haga más fuerte, la otra necesita que se saque la regla en conflicto.

El arreglo. Si es salience, sacá la constraint de la prosa y dale estructura — su propia línea o sección, dicha una vez y con claridad, donde el model de verdad la pondera. Más palabras no es el arreglo; la prominencia sí. Si es contradicción, el arreglo es resta: sacá o reconciliá la regla que pelea con la que querés, porque agregar un tercer "siempre" encima de dos que ya no coinciden solo profundiza el pozo (gotcha 3). En cualquier caso, cambiá la única cosa que la inspección señaló — no reescribas el prompt entero y pierdas de vista qué movimiento importó.

Cómo hacerlo sostener. Agregá un caso al eval set que afirme que la constraint se sostiene, y correlo sobre inputs que tienten al model a romperla — no solo el fácil donde ya cumple. El eval es lo que prueba que la reestructura o la remoción arregló el caso real y no aflojó en silencio una regla que antes se sostenía.

Produce un format equivocado o inconsistente

Cómo reconocerlo. La forma está mal — un preámbulo amable antes del JSON, campos reordenados, la salida envuelta en un code fence, una key renombrada — o está bien en algunas corridas y mal en otras. El parser río abajo se atraganta con la primera salida que no probaste.

Qué inspeccionar. Leé la salida cruda a través de varias corridas, no una, porque las fallas de format son la clase más intermitente — el prompt emite la forma correcta diez veces y se rompe en la once, así que una sola corrida que pasa no te dice nada (gotcha 2). Poné varias corridas lado a lado y mirá qué varía: ¿es el mismo campo cada vez, o el model deriva a algún lado nuevo en cada corrida? El patrón te dice si estás peleando un punto débil o confiando en la prosa para cargar una estructura que no puede sostener.

El arreglo. Pasá de prosa a structured output, no "por favor usá el format". Pedir con más firmeza la forma correcta sigue siendo pedirle a un generador no determinístico que se porte; el arreglo es dejar de confiar en la prosa para cargar estructura y declarar la forma contra un schema — la mecánica completa es structured output. Eso mueve la carga de producir una forma válida de tu parser frágil al model y al contrato de la API, donde corresponde, y convierte "casi la forma correcta" en una constraint que la plataforma impone en vez de una esperanza que reescribís.

Cómo hacerlo sostener. Agregá un caso de eval que afirme la forma, no la prosa — la salida parsea, cada campo requerido está presente, los tipos están bien — y correlo a través de suficientes casos para atrapar la rotura intermitente, ya que un bug de format que dispara una corrida de cada diez pasa un chequeo de una sola corrida cada vez. El eval es lo que prueba que el schema se sostuvo bajo los inputs que antes rompían el parser.

Su salida es inconsistente entre corridas

Cómo reconocerlo. Mismo input, respuestas distintas — no exactamente mal, solo inestables, derivando en contenido o criterio de una corrida a la siguiente. Un revisor no puede confiar en ella porque no dice lo mismo dos veces.

Qué inspeccionar. Primero, la pregunta que casi nadie hace: ¿esta tarea tiene siquiera una sola respuesta correcta? Algunas tareas son genuinamente abiertas — un brainstorm, un borrador, un resumen con muchas formas válidas — y exigirles determinismo es pelear la batalla equivocada; el arreglo ahí es un gate humano, no un prompt más ajustado (principio 8). Pero si la tarea sí tiene una respuesta correcta estable y el model igual divaga, inspeccioná qué está subespecificado: una instruction vaga que el model llena distinto cada corrida, un juicio que describiste en prosa en vez de fijar con un example, espacio que dejaste y el model usa (gotcha 4, y system prompts and instructions).

El arreglo. Bajá la varianza en su fuente. Instructions más claras y directas sacan el espacio en el que el model divagaba; un par de examples trabajados (few-shot) fijan un juicio o una forma que la prosa solo gesticulaba, mostrando en vez de contar; y donde tu plataforma lo expone, una temperature más baja reduce la aleatoriedad de sampling — útil para una tarea que quiere una sola respuesta estable, el movimiento equivocado para una que quiere rango. Tirá de la palanca más barata primero — la claridad normalmente le gana a cualquier otra perilla — y cambiá una por vez para poder ver cuál de verdad estabilizó la salida. La guía de Anthropic sobre esto está en la referencia de abajo.

Cómo hacerlo sostener. Agregá un caso de eval que puntúe consistencia, no una sola corrida: corré el mismo input varias veces y afirmá que las respuestas coinciden en lo que importa — la clasificación es estable, los hechos requeridos son constantes, la forma se sostiene. Un bug de consistencia es invisible para un chequeo de una corrida por definición, así que el eval tiene que muestrear más de una vez, o el drift vuelve a entrar pareciendo sano.

Se degradó después de un cambio de model

Cómo reconocerlo. Mismo prompt, model nuevo — un upgrade, un salto de versión, un swap — y la salida está sutilmente peor. Nada en el prompt cambió, así que la regresión se esconde en la única variable que todos asumen estable.

Qué inspeccionar. Re-corré el eval set entero sobre el model nuevo y leé el diff contra los puntajes del model viejo. El prompt estaba en parte ajustado al model viejo — sus hábitos de formato, las frases a las que respondía, las rarezas alrededor de las que tuneaste — y ese tuneo no se transfiere gratis (gotcha 8). El diff del eval lo localiza: qué casos cayeron, y sobre qué clase de input, te dice dónde el model nuevo lee tu prompt distinto a como lo leía el viejo. Sin el set, tenés una sensación vaga de que "empeoró" y ninguna forma de decir dónde.

El arreglo. Re-tuneá el prompt contra el eval sobre el model nuevo — no portes el prompt viejo y reces. Las instructions que cargaban el model viejo pueden necesitar re-redacción para el nuevo; un example que fijaba un comportamiento antes ahora puede ser redundante o hasta contraproducente. Hacé cada cambio contra el set sobre el model nuevo, una variable por vez, hasta que los puntajes se recuperen. Esto es también por qué "esperar al model mejor" no es un upgrade gratis: un model más nuevo puede regresionar un prompt tuneado a los hábitos del viejo, y solo el eval te dice si el swap ayudó o lastimó.

Cómo hacerlo sostener. El eval set es el mecanismo acá — hacelo correr en cada cambio de model, no solo en este. Un swap de model que no se puntúa contra el set es un cambio de calidad silencioso lanzado a fe; un swap de model que sí se puntúa convierte "el upgrade lo empeoró en silencio" en un test rojo el día que la versión se mueve, en vez de una degradación que un usuario encuentra por vos.

Está bien a veces, mal en edge cases

Cómo reconocerlo. El prompt maneja bien los inputs comunes y falla en los inusuales — un input largo, un campo vacío, una redacción ambigua, un format que ve poco. El camino feliz es sólido; los márgenes gotean.

Qué inspeccionar. No debuggees las fallas de a una — juntalas e inspeccionalas como un cluster. Traé cada caso equivocado que tengas y preguntá qué comparten: el mismo campo faltante, el mismo largo de input, la misma ambigüedad, la misma categoría para la que el prompt nunca tuvo un example. Una sola falla de edge case parece ruido; las mismas fallas alineadas revelan la única cosa que el prompt no maneja, y ese rasgo compartido es lo que de verdad arreglás — no cinco parches separados que cada uno pelea un síntoma.

El arreglo. Apuntá al cluster, no a las instancias. Normalmente uno de dos movimientos: agregá un example trabajado (few-shot) que demuestre el manejo correcto para ese caso — el arreglo de mayor palanca cuando la forma de "correcto" es más fácil de mostrar que de describir (system prompts and instructions) — o agregá una regla explícita para el caso que los examples no cubren. Resistí pegar una excepción separada por cada input que falla; así es como un prompt crece hasta ser una pared inmantenible de excepciones (gotcha 3). Un example o una regla que cubre el cluster entero le gana a cinco que cada uno cubre uno.

Cómo hacerlo sostener. Agregá el edge case al eval set — el real que falló, con su resultado conocido-bueno — para que no pueda regresionar. Los edge cases que te pegaron en producción son los casos más valiosos del set, porque codifican las formas en que tu tarea de verdad se rompe; cada uno que agregás es un margen que el próximo edit de prompt no puede volver a abrir en silencio sin un test rojo.

El hilo

Cinco fallas, un método debajo: leé la salida real a través de varias corridas, aislá la única variable que el síntoma señala, cambiá solo esa, y trabá el arreglo detrás de un caso de eval para que no pueda volver en silencio. La no determinación del prompt es justo por qué la reescritura completa falla y el cambio controlado gana — no podés probar un arreglo sobre un sistema cuya salida se mueve entre intentos mirando a ojo una corrida, y no podés decir cuál de cinco edits simultáneos ayudó. El prompt es el artefacto más editado y menos testeado en la mayoría de los sistemas de IA, por lo que esta disciplina importa más acá que en ningún otro lado: cada arreglo de arriba es un lugar donde un "se ve mejor" sin puntuar habría lanzado una regresión que no podías ver, y el eval set es donde cazás la separación en vez de teorizar sobre ella.

Si una falla de prompt le pegó a tu equipo y no está acá, escribí a hello@wearecleon.com — la agregamos, con crédito.

Prompting gotchas — los modos de falla que esta página operacionaliza, cada uno con la pregunta a contestar primero
System prompts and instructions — donde se deciden salience, orden, examples, y el arreglo de la instruction ignorada
Structured output — el arreglo para el síntoma de format equivocado-o-inconsistente
What is context engineering — la disciplina dentro de la que viven estos síntomas
Context windows — el presupuesto al que una falla de edge-case-sobre-input-largo suele rastrearse
Prompt caching — lo que cuesta un edit a un preámbulo cacheado, antes de tunear en un loop
Style Guide de prompting — la vara que evita que estas sesiones de debug pasen dos veces
Debuggear agentes — el mismo método para una corrida completa de agente, no solo el prompt
Debuggear grounding — la companion del lado del retrieval cuando la respuesta equivocada es un miss de retrieval, no de prompt
Principios de AI Engineering — evaluá antes de lanzar (3), la no determinación necesita un gate humano (8), trazá todo (11)

Reference: