El corrector de prompts que diagnostica antes de reescribir

Pega un prompt defectuoso en casi cualquier "optimizador de prompts" y obtienes el mismo movimiento: tu prompt entra en una plantilla mágica — ¡el framework de las 4 D! ¡27 patrones! — y vuelve más largo, reestructurado de arriba abajo, sin registro de qué cambio importó o si sigue haciendo la misma tarea. Se lee mejor. Que funcione mejor es otra cuestión, y la herramienta nunca lo comprueba.

Dirigimos un directorio que testea skills de Claude con benchmarks para ganarnos la vida, y queríamos justo lo contrario. Así que construimos prompt-discipline, que trata un prompt como tratarías un reporte de bug: nombra el modo de fallo primero, aplica el arreglo más pequeño que lo aborde, y luego dice exactamente cómo hacer A/B del cambio. Es gratis y tiene licencia MIT: github.com/Skillproofdev/prompt-discipline.

La brecha: los reescritores no diagnostican, los diagnosticadores necesitan infraestructura

Antes de escribir una regla, revisamos 43 skills de ingeniería de prompts en nuestro catálogo más las herramientas independientes — el propio mejorador de prompts de Console de Anthropic, PromptPerfect, DSPy, el prompt-optimizer de getsentry. El terreno se divide en dos bandos que nunca se solapan.

Los reescritores de plantilla transforman cada entrada de la misma forma. No hay ningún paso que pregunte qué es lo que realmente está mal aquí — un prompt vago y un prompt contradictorio reciben el mismo tratamiento, y la salida es de forma fiable más larga. Esto no es un espantapájaros: el propio mejorador de Console de Anthropic advierte abiertamente que sus reescrituras salen más largas y más lentas. Más largo es el producto.

Los pipelines eval-first — DSPy, optimizadores guiados por trazas — tienen la epistemología correcta. De verdad miden. Pero necesitan infraestructura: trazas de producción, un servidor MCP, un arnés de worktree, un dataset etiquetado que primero tienes que montar. No recurres a ellos para arreglar el prompt que estás editando ahora mismo.

Nadie empaqueta la cosa intermedia: una skill sin dependencias que hace diagnóstico-primero → diff-mínimo → plan de test A/B, sin trazas y sin servidor que levantar. Esa brecha es la skill entera.

Nueve reglas, tres de ellas son la clave

La skill es un conjunto de reglas estrictas aplicadas en orden (SKILL.md completo). Las partes conocidas están ahí — el formato de salida como un contrato positivo (una lista de claves con tipos, no "responde en JSON"), ejemplos por encima de adjetivos, listas de prohibiciones reescritas como instrucciones afirmativas, el orden rol→datos→instrucciones→ejemplos→consulta. Las tres que la definen:

1. Diagnostica antes de tocar nada. Clasifica qué está realmente mal — ambigüedad, contexto faltante, sin contrato de salida, instrucciones contradictorias, riesgo de deriva de formato, sobreprompting, o "esto ni siquiera es un problema de prompting" — y cita el fragmento culpable de cada hallazgo. Sin diagnóstico, no hay reescritura. "Este prompt está bien" es una salida válida y completa.
2. Diff mínimo, un cambio por fallo. Cada edición corresponde exactamente a un fallo diagnosticado, mostrado como antes → después con una justificación de una línea. Las partes que funcionan se quedan tal cual. Donde el mejorador de Console rellena, este suele salir más corto — se cortan las invocaciones vacías ("eres la mejor persona del mundo en…", "respira hondo", los andamiajes gastados de "piensa paso a paso").
3. Un plan de test, no una promesa. Cada reescritura llega con 2–3 entradas de test concretas, incluyendo un caso límite, cómo se ve un aprobado, y el procedimiento A/B: mismas entradas, mismo modelo, 3–5 ejecuciones de cada uno, comparar tasas de aprobado. Si se apilaron varias ediciones, indica cuál revertir primero. Nunca promete "esto lo va a arreglar" — cambiaste variables; el test decide.

El benchmark — y un matiz que necesitas antes

Diez prompts genuinamente defectuosos, cada uno emparejado con una tarea que tiene una respuesta comprobable mecánicamente: extracción contra un ground truth conocido, formateo que debe parsear (json.loads / csv.reader), clasificación contra ejemplos etiquetados. Tres brazos por caso — el prompt original, una reescritura base (Claude a secas al que se le dice "mejora este prompt"), y una reescritura con la skill (sesión idéntica con este SKILL.md cargado). Todas las reescrituras se ejecutan luego como tareas en el mismo modelo.

Lee esto antes de la tabla: la ejecución es n=1 por caso por brazo, no el n=5 preregistrado. La varianza de muestreo no está medida. Cualquier brecha de un solo caso (0.1) está dentro del suelo de ruido. Trata cada número de aquí como provisional a la espera de una réplica con n=5 — nosotros lo hacemos.

Brazo	Éxito de tarea	Cumplimiento de formato	Δ mediana de extensión de prompt
A — prompt original	0.70 (7/10)	0.70 (7/10)	—
B — reescritura base ("mejora este prompt")	0.80 (8/10)	0.70 (7/10)	+99.5 palabras
C — reescritura con la skill (este SKILL.md)	0.90 (9/10)	0.80 (8/10)	+44.5 palabras

Contra el test preregistrado, la skill aprueba: iguala o supera a la reescritura base en éxito (0.90 ≥ 0.80) y cumplimiento (0.80 ≥ 0.70), supera el listón de +15 puntos porcentuales sobre el original (+20 pp), y lo hace añadiendo menos de la mitad de la hinchazón — mediana de +44.5 palabras frente a las +99.5 de la reescritura base. Ese último número es el hallazgo más sólido de toda la ejecución: C es más ligero en los diez casos, y es el único brazo que alguna vez va en negativo (caso-10, −10 palabras, recortando una acumulación de prohibiciones de un prompt de sistema). Tanto la reescritura ingenua como la disciplinada hinchan los prompts concisos; la ingenua más o menos duplica el coste.

Dónde es endeble, y dónde perdió

Las ventajas de éxito y cumplimiento son reales pero frágiles, y no vamos a fingir lo contrario.

En 7 de los 10 casos, los tres brazos empatan. El margen de éxito descansa casi por completo en el caso-06 (clasificación de tickets), el único caso donde la skill gana claramente: C produjo etiquetas correctas y parseables por elemento (15/15) mientras la reescritura base logró 13/15 en un formato que no parseaba. Quita ese caso y la brecha del titular casi se evapora. Así es como se ve n=1 con muchos empates — honesto, no condenatorio, pero deberías saberlo.

El caso-09 es una derrota de la skill en sus propios términos. Un prompt de corrección de tono con una audiencia faltante — exactamente la situación para la que existe la Regla 2 ("declara tu suposición cuando la intención es indecidible"). La regla no se activó. La reescritura de la skill se dejó el problema de la audiencia faltante, y C falló junto a A y B. Una skill perdiendo justo en lo que está específicamente diseñada para captar es el tipo de resultado negativo más útil, así que se queda en la tabla.

El cumplimiento del caso-02 es 0 en los tres brazos. Un prompt con instrucciones contradictorias: cada brazo resolvió la contradicción en el contenido (obtuvo el número correcto) pero ninguno forzó una salida de valor único, así que los tres puntuaron 0 en formato. Ninguna de las dos reescritoras — disciplinada o no — pensó en exigir el contrato. Un punto ciego compartido, reportado, no escondido.

Testeamos las skills de otras personas para ganarnos la vida, y nuestra metodología exige mostrar las derrotas junto a las victorias. Estas son las derrotas.

Instalación

git clone https://github.com/Skillproofdev/prompt-discipline ~/.claude/skills/prompt-discipline

Reinicia Claude Code. Se activa con "mejora este prompt", "por qué falla mi prompt", "optimiza prompt", y cuando estás escribiendo o revisando prompts de sistema e instrucciones de agente — y rechaza peticiones de jailbreak/bypass de seguridad y prompts de generación de imagen/vídeo, que tienen su propia gramática. Se suma a nuestra serie de disciplina: token-discipline recorta lo que cuesta una sesión, research-discipline recorta lo que la investigación se equivoca, y esta recorta las reescrituras de prompts hasta el cambio que de verdad importó.

Preguntas frecuentes

¿En qué se diferencia del mejorador de prompts de Console de Anthropic? El mejorador de Console es un reescritor de plantilla — reestructura todo el prompt y advierte abiertamente que el resultado sale más largo y más lento. prompt-discipline diagnostica primero el fallo específico, cambia solo lo que corresponde a ese fallo, y en nuestro benchmark añadió menos de la mitad de la extensión mientras solía salir más corto. Objetivo distinto: la herramienta de Console produce un prompt pulido; esta produce el diff más pequeño defendible más una forma de demostrarlo.

¿Por qué publicar un benchmark que admites que es n=1? Porque la alternativa en este nicho es no publicar ningún número, que es la norma contra la que reaccionamos. n=1 con el matiz dicho con claridad es más honesto que una afirmación segura sin ninguna medición detrás. El hallazgo de la mediana de extensión es sólido en los diez casos; las ventajas de éxito y cumplimiento son provisionales y están etiquetadas como tal, a la espera de una réplica con n=5.

¿Siempre reescribe mi prompt? No. Si el prompt está bien, la skill lo dice y se detiene — "este prompt no necesita cambios; aquí tienes el único riesgo que probar" es una salida válida y completa. Tampoco rellena un diagnóstico solo para justificar aplicar una plantilla, y rechaza de plano las peticiones de jailbreak en vez de "mejorarlas".

¿Esto va a arreglar mi prompt? No lo va a prometer, y ninguna herramienta que no haya ejecutado tu tarea debería hacerlo. La skill cambia variables y te entrega un procedimiento A/B concreto — mismas entradas, mismo modelo, 3–5 ejecuciones — para que decida el test, no la sensación de un prompt que se ve más limpio.