Desarrollar con SoftOS: cuando la IA necesita barandas
Una bitácora honesta sobre specs, agentes, OpenAPI, Laravel y gates verificables. Porque construir con IA puede acelerar mucho el proceso, sí. Pero sin evidencia, la velocidad también puede acelerar el incendio.
De velocidad improvisada a entrega gobernada
El problema no era escribir código. Era poder confiar en lo que se estaba entregando.
Durante varias semanas trabajamos en un workspace SoftOS real en PLG: Laravel, ChatGPT Actions, OAuth, facade Auto, OpenAPI publicado en staging, submódulos, gates y evidencia para beta.
No era un demo bonito. Era producto vivo. De esos donde cada cambio puede arreglar algo, romper otra cosa o dejar una sorpresa escondida para el viernes a las 5:47 p.m.
Antes
- Agentes rápidos, pero con riesgo de tocar superficies equivocadas.
- Contratos OpenAPI con posibilidad de duplicarse o quedar desactualizados.
- Pruebas ejecutadas en entornos que no siempre reflejaban el runtime real.
- Un “listo” que podía significar muchas cosas distintas.
Después
- Specs como fuente de verdad para humanos y agentes.
- Targets claros para definir qué se puede tocar y qué no.
- Tests, gates y evidencia como cierre obligatorio del slice.
- Un sistema más gobernable para construir EdTech con IA sin jugar a la ruleta.
SoftOS, en una frase útil: un sistema operativo de entrega.
SoftOS trata el repositorio como algo más que una carpeta con código. Lo entiende como un sistema de entrega donde la intención, la implementación, la verificación y la evidencia tienen lugares separados.
La intención vive en specs/**.
El estado operativo vive en .flow/**.
El código vive en los repos de implementación.
Y la calidad no se presume: se verifica con comandos, tests, contratos y evidencia.
No es “documentación bonita con CI”. Es contrato antes de código. Es permiso de edición por targets. Es cerrar cada slice con pruebas. Es obligar al sistema a responder una pregunta incómoda: ¿esto está listo o solo parece listo?
Más velocidad no sirve de mucho si nadie puede verificar qué se rompió, qué se respetó y qué quedó realmente listo.
El escenario: varios repos, un GPT y cero paciencia para errores silenciosos.
Nuestro contexto mezclaba un root plg-dev-env,
un backend Laravel en lms-backend,
frontends legacy, V2 Hub, rutas de Actions, facade Auto, OpenAPI público
y un GPT conectado por Actions.
El trabajo no era crear un endpoint suelto. Era sostener un programa completo: OAuth, borradores, aprobación antes de publicar, compatibilidad con rutas existentes y reglas claras para evitar efectos secundarios.
En otras palabras: el escenario perfecto para que un “hagamos un PR rápido” termine convertido en una novela rusa con logs.
Seis capas que sí cambiaron la forma de trabajar
La metodología empezó a tener valor cuando dejó de ser teoría y se volvió operación diaria. Estas fueron las capas que más orden pusieron.
Spec como fuente de verdad
Cada slice serio empezó con una spec: estado, targets, dependencias, decisiones, superficies afectadas y evidencia esperada. Menos interpretación creativa, más contrato común.
Targets como permiso de edición
Si algo no estaba en targets, no se tocaba sin actualizar la spec. Incómodo al principio. Muy útil después. Especialmente cuando hay agentes con ganas de “ayudar”.
Runtime correcto
Las pruebas tenían que correr donde realmente vive el repo.
flow repo exec ayudó a salir del clásico “en mi máquina sí pasó”.
Contratos verificables
OpenAPI dejó de ser un YAML que alguien revisa cuando algo falla. Pasó a ser parte de la calidad: paths, operationId, rutas públicas y fragmentos prohibidos.
Gates y evidencia
“Hecho” empezó a significar comandos ejecutados, pruebas corridas, evidencia guardada y limitaciones claras. Mucho menos humo. Mucho más sistema.
Política en tests
No bastaba con validar status 200. También había que probar que publish no disparara PDFs, emails o webhooks cuando la spec lo prohibía.
Un sistema puede responder bien y aun así hacer algo que no debía.
La calidad real no es solo “respondió”. Es “respondió sin romper las reglas del negocio”.Historia real: OpenAPI y el problema de tener dos verdades.
Durante un tramo del proyecto mantuvimos dos contratos: uno con rutas v1 y otro con rutas Auto. En papel sonaba razonable. En operación era una trampa.
Dos YAML. Dos fuentes de verdad. Un GPT intentando importar el contrato correcto. Un equipo tratando de recordar cuál archivo era “el bueno”. Nada bueno empieza con esa combinación.
La decisión fue simplificar: publicar solo rutas Auto en el contrato principal para GPT Builder, mantener una sola URL importable y un solo flujo de generación.
La lección fue clara: dual-run puede existir en runtime, pero no debería existir como confusión documental.
Historia real: “cerré desde ChatGPT, pero no hay PDF”.
Este fue uno de esos casos donde el problema no era simplemente técnico. Era de modelo mental.
Desde ChatGPT, el cierre guardaba feedback y respetaba la regla de no disparar efectos secundarios.
Pero el dashboard habilitaba la descarga del PDF solo cuando
class_closed estaba en true.
Resultado: el GPT hacía lo que debía, pero la interfaz seguía esperando otra señal. El backend no estaba necesariamente roto. El sistema estaba hablando varios dialectos del mismo proceso.
SoftOS ayudó a poner la respuesta en términos verificables:
flags como pdf_download_available,
errores con hint,
reglas documentadas en spec y pruebas de comportamiento.
Pero hay que decirlo sin maquillaje: una buena API no arregla sola una UX legacy que mira otro dato. La metodología ayuda a ordenar el problema. No lo desaparece mágicamente.
Lo que más pagó renta en el proceso
No todo proceso agrega valor. Algunos solo decoran el caos con nombres bonitos. Pero estos harness sí hicieron diferencia.
Spec + targets
Dieron una frontera clara para humanos y agentes. Menos cambios fantasma, menos improvisación.
flow repo exec
Permitió correr pruebas en el runtime correcto. La frase “en mi laptop funciona” perdió poder diplomático.
Tests de contrato
OpenAPI dejó de depender de QA manual en GPT Builder. Los contratos empezaron a cuidarse solos.
Tests de side-effects
Blindaron reglas como “publish no dispara PDF ni email”. Porque los efectos secundarios son expertos en aparecer sin invitación.
Gates de agentes
Hicieron el cierre repetible. El agente ya no podía inventarse el plan de pruebas sobre la marcha.
Evidencia por slice
Sirvió como auditoría, onboarding y memoria técnica para el equipo del futuro. Ese equipo siempre llega. Y siempre pregunta “¿por qué esto está así?”.
Conceptos clave del aprendizaje
Si tuviéramos que resumir el proceso en etiquetas, estas serían las que más se repitieron.
- Contrato antes de código
- Targets como barandas
- OpenAPI verificable
- Runtime correcto
- Gates antes de “listo”
- Evidencia por slice
- Agentes con límites
- Menos fe, más pruebas
Impacto real en la calidad del código
SoftOS no convirtió mágicamente todo el Laravel legacy en una obra renacentista. Tampoco era su trabajo.
Lo que sí logró fue mejorar la correctitud de slices específicos: menos efectos colaterales, menos deriva del contrato público, más invariantes protegidas por tests y menos “done” falso.
También dejó visibles los límites: la UX del dashboard todavía necesita trabajo, la deuda legacy no desaparece por estar mejor documentada y la homogeneidad del código requiere un programa de refactor aparte.
Esa honestidad es parte del punto. No todo está resuelto. Pero ahora sabemos mejor qué está resuelto, qué está frágil y qué no deberíamos vendernos como listo.
Qué nos llevamos para el siguiente proyecto
Después de este proceso, quedan varias reglas prácticas para no volver a aprender lo mismo a punta de sustos.
Una spec activa, un contrato publicado
No dos OpenAPI compitiendo por la verdad. Compatibilidad técnica sí. Confusión documental no, gracias.
Nombres de negocio consistentes
Si class_closed significa algo,
debe significar lo mismo para API, GPT, dashboard y equipo.
Tests que afirmen política
No basta con validar status 200. Hay que validar también lo que el sistema no debe hacer.
Runtime correcto por defecto
Las pruebas deben correr donde el repo vive realmente. Lo demás es optimismo con sintaxis.
Evidencia mínima por slice
Comandos, URLs, resultados y limitaciones.
READY_WITH_LIMITATIONS es válido si es honesto.
Separar merge, deploy y smoke test
Código mergeado no significa staging validado. Y staging validado no significa que GPT Builder ya esté feliz.
La fricción que no conviene esconder
SoftOS tiene costo. El primer día de un slice puede sentirse más lento. Hay que leer, definir, acotar, escribir, revisar y ejecutar. No es el paraíso de “yo solo codeo y ya”.
Además, los submódulos pueden pelear. Los hooks pueden bloquear. El root puede exigir disciplina. Y los agentes sin spec pueden volverse rápidos, seguros y peligrosos. Una combinación muy de película de ciencia ficción, pero con menos láseres y más YAML.
La metodología tampoco arregla por sí sola los desacuerdos entre negocio, API y frontend. Si el producto dice una cosa, la spec otra y la pantalla legacy mira un tercer campo, habrá problemas.
SoftOS no reemplaza criterio. Lo obliga a quedar escrito.
Una spec desactualizada no es documentación.
Es una mentira con formato Markdown. Y de esas ya hay suficientes en internet.Construir tecnología educativa no es decorar procesos con IA.
Desarrollar con SoftOS se parece menos a “sacar features” y más a operar un sistema de entrega: contratos versionados, runtimes federados, agentes con barandas, specs que gobiernan y evidencia que evita la fe ciega.
En PLG, eso se notó donde más importa: en evitar efectos secundarios, no mentirle al GPT con rutas obsoletas, proteger reglas del negocio y saber con más claridad qué estaba listo para beta y qué todavía tenía deuda.
Construir EdTech real no es ponerle IA a todo. Es construir sistemas que puedan mejorar sin romper la experiencia de quienes aprenden, enseñan y operan todos los días.
Esa es la vara. Y sí: ahora toca sostenerla.
