La mayoría del software no se presenta. Empieza con un repositorio, un archivo de paquetes, un laberinto de convenciones y una larga lista de cosas que supuestamente ya deberías saber. La primera experiencia no es entender: es excavar. Abrís carpetas, inferís intenciones a partir de nombres de archivo y buscás rutas, scripts de build, archivos generados, esquemas, variables de entorno y supuestos sobre el despliegue. Si el proyecto tiene suficiente historia, también heredás explicaciones transmitidas de boca en boca: por qué existe este archivo, por qué se guarda aquel resultado en el repositorio o por qué el build se comporta distinto los martes.
Hoy eso es normal, pero no deja de ser extraño.
Un sistema de software debería poder responder preguntas básicas sobre sí mismo. ¿Qué se generó? ¿Qué existe? ¿Qué tipo de artefacto es éste? ¿Qué build lo produjo? ¿Qué capacidades afirma tener el runtime? ¿Son válidos los contratos? ¿Este resultado está pensado para personas, agentes o ambos?
Paideia es mi intento de construir un framework pequeño alrededor de esa idea. La premisa es sencilla: los sistemas generados deberían explicarse a sí mismos.
No mediante un enorme dashboard, un plano de control en la nube o la obligación de memorizar la mitología interna del framework. Un sistema generado debería llevar un conjunto pequeño de archivos legibles que describan su estructura. Esos archivos deberían vivir junto al resultado y ser lo suficientemente simples para inspeccionarlos con un editor de texto. Deberían ayudar a personas y agentes a entender el sistema sin adivinar.
Por eso Paideia genera `system.json`, `context.json`, `llms.txt` y `runtime.json`. Cada uno tiene una función.
`system.json` es el contrato del sistema: describe el sitio generado y la estructura de su runtime. `context.json` es el mapa comprimido para agentes: les da a los modelos de lenguaje un resumen conciso de páginas, artículos y hechos importantes del runtime. `llms.txt` es la guía en lenguaje natural: indica dónde empezar y qué archivos importan. `runtime.json` es la identidad del runtime: dice qué build produjo el resultado, qué artefactos existen, de qué tipo son, cuánto ocupan, qué capacidades declara el runtime y si el manifiesto está normalizado.
No son metadatos por acumular metadatos. El objetivo es reducir la arqueología.
Cuando termina un build, el resultado no debería parecer una pila de archivos, sino un sistema estructurado. Una persona debería poder ejecutar `paideia inspect` y obtener una respuesta compacta: versión del framework, identificador del build, cantidad de páginas, artículos y artefactos, tipos de artefactos, capacidades, estado del manifiesto y de los diagnósticos. Una máquina debería poder leer los mismos hechos en `runtime.json`. Un comando `doctor` debería verificar que los archivos de identidad sean válidos, que el inventario apunte a archivos reales, que el manifiesto esté normalizado y que las capacidades requeridas se declaren una sola vez.
Esto es lo que más me interesa: la posibilidad de inspeccionar un sistema no es decorativa. Cambia la relación entre el desarrollador y el sistema. Muchos frameworks buscan dar más poder ocultando complejidad detrás de convenciones. Eso puede ser útil, pero también puede producir una especie de indefensión aprendida. Sabés ejecutar el framework, pero no qué hizo realmente. Conocés las palabras mágicas, pero no la forma del hechizo. Te volvés rápido para usar la herramienta y lento para entender su resultado.
Paideia intenta otro equilibrio.
No busca ser el framework más grande, competir en amplitud con ecosistemas frontend maduros ni controlar cada capa del desarrollo de aplicaciones. Busca hacer más legible el software pequeño que genera.
Esa restricción importa. El framework debería seguir siendo pequeño, legible y acotado. Cada superficie nueva tiene que justificar su lugar haciendo que el sistema sea más comprensible o verificable. El inventario se lo gana porque responde qué existe. Un identificador determinista del build, porque responde si el resultado cambió. Las capacidades, porque dicen qué afirma poder hacer el runtime. `doctor`, porque convierte contratos en comprobaciones. `inspect`, porque las personas necesitan una forma rápida de ver la estructura del sistema.
Pero también hay un peligro. Es muy fácil que un proyecto así termine haciendo teatro con metadatos. Una vez que empezás a describir un sistema, siempre aparece una cosa más para describir: otro campo, otro contrato, otro esquema, otra capa que explica la capa que explica la capa. Por ese camino se llega a un pantano muy bien presentado.
Paideia tiene que mantener la disciplina.
El objetivo no es describirse infinitamente. Es describirse lo suficiente para que el sistema generado se pueda entender. La prueba es práctica: ¿esto ayuda a alguien a inspeccionar, verificar, depurar, operar o entregarle el sistema a un agente? Si la respuesta es no, probablemente no corresponde agregarlo.
Por eso Paideia también busca tener pocas dependencias. Un framework que trata sobre legibilidad no debería necesitar una catedral de maquinaria oculta para explicar un sitio pequeño. Debería ser posible leer el generador, inspeccionar el resultado, entender el runtime y ejecutar los diagnósticos sin confiar en una enorme pila de comportamientos invisibles.
Los agentes importan, pero no en el tono exaltado con el que a veces el software habla de la IA. No necesitan misticismo: necesitan superficies estables, archivos que indiquen qué existe, contratos que definan qué es válido y resúmenes que entren en contexto. Necesitan identificadores deterministas para reconocer cambios y capacidades del runtime para razonar sobre las herramientas disponibles sin inventarlas.
Las personas necesitan lo mismo. Ese es el punto que recorre todo el proyecto. Las funciones que facilitan el uso del software por agentes suelen facilitarlo también para las personas, siempre que sean explícitas y simples. Un buen archivo de contexto le sirve a un modelo y a un desarrollador cansado. Una buena identidad del runtime sirve para automatizar y para volver a un proyecto después de tres semanas y preguntar: ¿qué produjo este build?
Paideia empezó como un pequeño experimento con runtimes inspeccionables y contratos explícitos. Ahora se está convirtiendo en un framework para sistemas generados que se describen a sí mismos. Suena ambicioso, pero la implementación es deliberadamente modesta: generar el sitio, emitir los contratos, validarlos, describir los artefactos, declarar capacidades, ofrecer un comando de inspección para personas y mantener el runtime pequeño.
Eso alcanza para producir una experiencia distinta. El resultado generado deja de parecer un residuo del build. Parece un objeto con identidad: tiene un contrato, un mapa, una guía, una huella y un inventario. Se puede inspeccionar y comprobar.
Quiero ver más software así: software que no convierta la comprensión en una búsqueda del tesoro y que pueda entregarse a una persona o a un agente diciendo «esto soy, esto hice, esto puedo hacer y así podés verificarme». Eso estoy construyendo con Paideia.