Intensivo Gratis 21–22.11Intensivo gratuito de 2 días en Vibecoding (21–22 nov, 16:00 MSK) · Cohorte 3 inicia 23.11Registrarse gratis →Cohorte 3 (23.11)
IndustriaAnálisis · En radarHabr AI→ original

Un equipo sacó 203 KB de prompts del código PHP a YAML: es un tercio de todo el código

El equipo de un proyecto PHP mantiene 203 KB de prompts, aproximadamente un tercio de todo el código PHP, en archivos YAML dentro de Git y no en el código. Antes, los prompts se editaban en el panel de administración, y producción se desviaba del entorno de staging sin ningún historial de cambios. Ahora un mismo archivo contiene el texto, el modelo, la temperatura y el formato de respuesta, y el código invoca esa «capacidad» por su nombre. La conclusión: el prompt debe versionarse como código, junto con sus parámetros de generación.

Procesado por IA desde Habr AI; editado por Hamidun News
Un equipo sacó 203 KB de prompts del código PHP a YAML: es un tercio de todo el código
Fuente: Habr AI. Collage: Hamidun News.
Escuchar artículo
Ficha técnica y cifras clave
ParámetroDatos
Fuente originalHabr AI ↗
Editor jefe
Dato clave #1Los datos del usuario se sustituyen con str_replace después de Blade
Reintento semántico2 intentos; de red: 3, con una pausa creciente
Dato clave #3En producción solo se registran errores, porque las solicitudes contienen conversaciones

Dónde guardar los prompts es una pregunta que tarde o temprano se plantea cualquier equipo que construye un producto sobre un LLM. Un proyecto PHP la respondió de forma radical: en el repositorio hay 203 kilobytes de prompts, aproximadamente un tercio del volumen de todo el código PHP. Sin embargo, en el código en sí no hay ni un solo prompt.

Todos están en archivos YAML (un formato de texto sencillo para configuraciones), que pasan revisión, se versionan en Git y se despliegan junto con cada versión. El proyecto está bajo NDA, por lo que el autor inventó ejemplos de prompts para un escenario con un bot de soporte, pero la estructura de los archivos, el código de procesamiento y los problemas que aparecen son reales. Durante el camino quedó claro que «mover un prompt a un archivo de configuración» no es una sola decisión, sino una docena de decisiones pequeñas, y cada una es fácil de tomar mal.

Por qué no en el código ni en el panel de administración

Un prompt dentro del código implica un despliegue solo para cambiar una coma. Pero los prompts tienen una particularidad: quien los ajusta no es el desarrollador, sino quien responde por la calidad de las respuestas del modelo. Se modifica una formulación, se revisa el resultado, se revierte y se prueba de otra manera. Ese ciclo se mide en horas, no en sprints.

La respuesta obvia es un campo editable en el panel de administración. El equipo la implementó en la primera versión y obtuvo el resultado típico: el prompt en producción difiere del de staging, nadie recuerda quién cambió y por qué el párrafo sobre el formato de respuesta, y revertir solo es posible de memoria. No hay revisión, no hay historial y no hay forma de ver el diff. Git resuelve los cuatro problemas a cambio de uno solo: para corregir un prompt hay que saber hacer un commit. Para este equipo, el intercambio resultó aceptable.

La unidad de almacenamiento no fue una cadena de texto, sino una «capacidad», por ejemplo summarize-ticket. Un mismo archivo contiene el proveedor, el modelo, los parámetros de generación, las plantillas de sistema y de usuario para cada idioma y el formato de respuesta esperado. La razón es simple: el mismo texto con una temperatura de 0,2 y con una de 0,9 son dos comportamientos distintos. Si la temperatura vive en el código y el texto en un archivo, no se puede reproducir el resultado de ayer. El código invoca la capacidad por su nombre y no sabe nada sobre el modelo ni el proveedor.

Plantillas, seguridad y pequeños escollos

Un prompt casi nunca es una constante: en él se insertan el historial de mensajes y el contexto. El equipo no escribió su propio motor de plantillas y conectó Blade con una sola línea. El costo es evidente: Blade compila la plantilla a PHP y la ejecuta, lo que significa que el contenido del archivo YAML es código ejecutable. Mientras los archivos pasen revisión, esto es aceptable. Pero si el responsable de producto quisiera editar los prompts directamente en el panel de administración, no se puede permitir un motor de plantillas completo: hace falta un motor restringido, sin ejecución de código y sin acceso al sistema de archivos.

La segunda protección es el orden de sustitución. Primero se renderiza la plantilla de confianza del repositorio y solo después se insertan, con un str_replace común en el texto ya generado, las cadenas que aporta el usuario, por ejemplo su nombre. Si se pasara ese nombre al motor de plantillas, alguien que se presentara como {{ config('app.key') }} obtendría en la respuesta la clave de la aplicación.

Algunos detalles prácticos más:

  • Cinco idiomas no equivalen a una traducción. Un modelo en ruso mantiene el formato de otra manera y se desvía con más frecuencia hacia otro idioma, por eso en las plantillas no inglesas aparecen añadidos como la exigencia de responder en el idioma correspondiente. La prueba «el significado coincide» no sirve de nada; en cambio, sí es necesaria la verificación de que en todas las configuraciones regionales existe la plantilla y el mismo conjunto de sustituciones: un traductor puede convertir fácilmente {user} en la palabra «usuario».
  • En la capacidad, el modelo se indica con un alias corto, y su nombre completo está en el archivo del proveedor. Cuando el proveedor renombra un modelo, se corrige un solo archivo y no nueve.
  • En el YAML se guarda el nombre de una variable de entorno, como ${FAST_CLOUD_KEY}, y no la clave en sí. Una clave real pegada «por un minuto» queda en el historial de Git para siempre, así que en la revisión eso se comprueba aparte.
  • Las comillas alrededor de los números en YAML los convierten en cadenas de texto, y el proveedor responde con un error de validación. El equipo convierte los parámetros a números en el código.

Respuestas estructuradas, reintentos y registros

Los proveedores no todos saben devolver respuestas estructuradas de la misma manera, así que en la configuración hay tres niveles: un esquema JSON completo, solo el modo «JSON válido» y «nada». El sistema degrada por escalones. Si el proveedor entiende el esquema, este se envía en response_format.

Si solo soporta el modo JSON, el esquema se añade como texto al final del prompt de sistema, en el idioma del usuario. Pero eso es una petición, no una garantía, por lo que hay una tercera capa: de la respuesta se recorta todo lo que hay entre la primera { y la última }, porque el modelo tiene la costumbre de añadir «¡Claro! Aquí tienes tu respuesta:».

El resultado se parsea y se valida contra el esquema. El autor reconoce que se resistió a esta función durante mucho tiempo, hasta que comprobó cuántas respuestas salvaba.

Los reintentos se dividen en dos tipos. Un fallo de red (timeout, 502, conexión interrumpida) se soluciona con un reintento normal y pausa exponencial, de hasta tres intentos. Un fallo semántico (código 200, pero cadena vacía, JSON no válido o estructura que no pasa el esquema) obliga a repetir la solicitud completa, y en este caso solo hay dos intentos. Cada uno cuesta dinero y segundos de espera para el usuario, y si el modelo no pudo resolver un mismo prompt dos veces, el problema está en el prompt o en el modelo, no en la mala suerte. Es más honesto mostrar el error y registrar el caso.

En producción solo se registran los errores. Primero, el cuerpo de la solicitud —el prompt de sistema más el historial de mensajes, decenas de kilobytes por línea—, y esa tabla crece más rápido que el resto. Segundo, ahí se guarda la conversación del usuario, es decir, datos personales con plazos de conservación y eliminación a petición. Aun así, los errores sí deben registrarse: estado, proveedor, modelo, tiempo de ejecución y detalles. Si no, una queja del tipo «el bot respondió una tontería» habría que reconstruirla a partir de la descripción del usuario.

Sobre las pruebas, el autor señala que la respuesta del modelo no es determinista y no puede verificarse con una aserción habitual, pero eso no significa que no haya nada que comprobar. La conclusión práctica para quienes construyen productos sobre LLM: traten los prompts como código, guarden los parámetros de generación junto al texto, inserten los datos del usuario después del motor de plantillas y decidan de antemano cuánta potencia de plantillas están dispuestos a poner en manos de quienes editan los prompts.

Historia

Preguntas frecuentes sobre la noticia

¿Qué se sabe sobre Por qué no en el código ni en el panel de administración?

Un prompt dentro del código implica un despliegue solo para cambiar una coma. Pero los prompts tienen una particularidad: quien los ajusta no es el desarrollador, sino quien responde por la calidad de las respuestas del modelo. Se modifica una formulación, se revisa el resultado, se revierte y se prueba de otra manera. Ese ciclo se mide en horas, no en sprints. La respuesta obvia es un campo editable en el panel de administración.

¿Qué se sabe sobre Plantillas, seguridad y pequeños escollos?

Un prompt casi nunca es una constante: en él se insertan el historial de mensajes y el contexto. El equipo no escribió su propio motor de plantillas y conectó Blade con una sola línea. El costo es evidente: Blade compila la plantilla a PHP y la ejecuta, lo que significa que el contenido del archivo YAML es código ejecutable. Mientras los archivos pasen revisión, esto es aceptable.

¿Qué se sabe sobre Respuestas estructuradas, reintentos y registros?

Los proveedores no todos saben devolver respuestas estructuradas de la misma manera, así que en la configuración hay tres niveles: un esquema JSON completo, solo el modo «JSON válido» y «nada». El sistema degrada por escalones. Si el proveedor entiende el esquema, este se envía en response_format. Si solo soporta el modo JSON, el esquema se añade como texto al final del prompt de sistema, en el idioma del usuario.

ZK
Zhemal Khamidun — CPO de Alpina Digital, product manager de AlpinaGPT. Crea productos de IA desde 2019. Hamidun News es un proyecto personal que creció hasta ser un agregador en producción con más de 6.000 lectores.
✦ Unified AI Workspace · Nomad

Test Frontier LLMs & Autonomous Agents in One Workspace

Run Claude Opus 5.5, GPT-6, Gemini 3.1, and DeepSeek side-by-side in Nomad AI (nomadnet.ai) — unified model routing, deep research, and multimodal workflows under one subscription.

Try Nomad AI →Launch Nomad Agent
¿Qué te parece?
Cargando comentarios…