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
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.
- 12 oct 2026T-Bank enseñó a un agente de IA a escribir tests unitarios de iOS con AGENTS.md y SKILL.md
- 16 jun 2026IA en el desarrollo: cómo un LLM detecta conflictos entre microservicios
- 18 nov 2026Kub Tri dio al agente de IA una memoria del proyecto: la revisión es más sencilla, pero el modelo cuesta casi un tercio más
- 2 may 2026El framework zymi propone construir agentes de IA como un proyecto dbt, con YAML y event sourcing
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.
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.
Lo esencial de la IA — una vez por semana
Siete historias que de verdad importaron, elegidas a mano. Sin ruido ni notas de prensa.
¡Listo! Revisa tu correo para la confirmación.