Este artículo es la versión escrita —y bastante más larga— de la charla que he llevado a GDG Madrid. Los fragmentos de código son ilustrativos: reproducen la forma y las decisiones de diseño de nuestra implementación, no un volcado del repositorio. La idea es que puedas reconstruir el marco en tu casa, no que copies el nuestro.
El lunes por la mañana
Tu director ha leído en Forbes que la IA reduce los tiempos de desarrollo un 70%. Es lunes, son las nueve, y lo quiere para el viernes.
Esta escena se ha repetido en tantas empresas que ya tiene forma reconocible: la curva de expectativa crece exponencialmente y la capacidad real de ingeniería crece de forma lineal.
El hueco entre las dos curvas no se cierra con voluntad. Se cierra de una de estas dos maneras: o pones un marco que aguante la presión, o el equipo paga la diferencia en deuda técnica, en incidentes y en gente quemada.
Nosotros elegimos lo primero, y al marco lo llamé L.U.C.I.A. Esto es lo que hay dentro.
El diagnóstico: qué pasa exactamente cuando no hay marco
No es que la IA "no funcione". Funciona demasiado bien para lo rápido que se adopta. Cinco fallos que hemos visto de verdad, y cada uno tiene después su contramedida:
1. Fugas de seguridad y PII. API keys personales en scripts locales y datos de cliente enviados sin anonimizar a nubes públicas, porque alguien pegó un CSV entero en el prompt "para que lo entendiera mejor".
2. Inflación de costes. Sin observabilidad del gasto no hay forma de explicar por qué la factura se ha triplicado. Suele ser lo mismo: contextos gigantes reenviados enteros en cada turno y peticiones redundantes que nadie deduplica.
3. Degradación técnica. El modelo optimiza para "que compile", no para "que se pueda mantener dentro de seis meses". Código espagueti, alucinaciones lógicas y una deuda que se acumula más rápido de lo que se paga.
4. Fragmentación arquitectónica. Cada generación ignora las decisiones previas del proyecto. Clean Architecture y SOLID se evaporan porque el agente no sabe que existen.
5. Shadow AI. Cada persona con su modelo, su prompt y su criterio. No hay cerebro corporativo, no hay flujos repetibles y el conocimiento no se acumula en ningún sitio.
El patrón: ninguno de los cinco es un problema del modelo. Son problemas de proceso. Y los problemas de proceso se arreglan con procesos.
El caos es el enemigo de la escala. Lo que falta no es más IA: es un marco de control.
Las cinco decisiones
L.U.C.I.A. no es una herramienta que se instala. Es un acuerdo sobre cómo trabaja el equipo:
- Lifecycle — cubre todo el ciclo de vida, de la idea al despliegue, haciendo que todos los roles trabajen de forma ordenada con la IA. No solo desarrollo.
- Universal — se pide un modelo lógico, no un proveedor: una sola salida, una sola política. Y se adapta a las herramientas de CI/CD que ya tengas.
- Collaborative — personas y agentes en el mismo tablero: la IA propone, las personas deciden.
- Iterative — tareas pequeñas, rama y Merge Request por tarea, verificación en beta antes de producción, en mejora continua.
- Automation — todo lo repetible es un comando; lo determinista nunca se delega a la IA. Es cultura DevSecOps, no magia.
Si te tienes que llevar una sola frase de todo el artículo, que sea esta:
La IA propone y prepara; desde la Merge Request en adelante, todo es determinista.
Esa frase es una frontera, y colocarla bien es el 80% del trabajo. A la izquierda, la IA acelera la parte cognitiva: entender, planificar, escribir. A la derecha no hay IA en absoluto: build, tests, imagen, despliegue, promoción. El mismo pipeline aburrido y auditable de siempre.
Para discutir esto sin ambigüedades usamos un código de cuatro colores que se repite en todos los diagramas. Cada elemento del sistema es una de estas cuatro cosas:
| Qué es | Quién responde | |
|---|---|---|
| Artefacto versionado | Markdown + Git. Si no está en el repo, no existe. | el repositorio |
| Lo ejecuta la IA | Propone plan, escribe código y tests. Nunca aprueba ni despliega. | quien lo valida |
| Lo decide una persona | El plan, el bump de versión, la aprobación del MR, la promoción a prod. | quien firma |
| Automatización determinista | Scripts, CI/CD, GitOps. Mismo input, mismo output, siempre. | el sistema |
Cuando alguien discute una decisión de diseño, la pregunta que zanja el debate es siempre la misma: ¿de qué color es esto?
El concepto en una imagen
Tres fases en el centro —Discovery, Dispatcher, Delivery— y dos servicios transversales a los lados: el cerebro corporativo y la pasarela de IA. Todo lo demás son detalles de esta misma foto.
Y así se mueven los datos por dentro:
Fíjate en dos cosas antes de seguir. La primera: todo vive en repositorios Git, tanto la definición como el código. La segunda: hay exactamente una salida hacia los modelos, y pasa por Shield.
Empiezo por los dos servicios transversales, porque son los cimientos: sin ellos, lo demás es un flujo de trabajo bonito con los mismos problemas de siempre.
Cimiento 1: brain MCP, el cerebro corporativo
El problema del contexto empresarial tiene dos soluciones malas y una buena. Las malas: pegar la documentación entera en el prompt —caro, ruidoso y obsoleto en cuanto alguien edita un documento— o darle al agente acceso total a los sistemas internos, que es exactamente lo que todos queremos evitar.
La buena es exponer el conocimiento como herramienta, vía MCP, con un servicio único para toda la empresa.
Cuatro propiedades, y las cuatro importan:
Acceso por rol, con token. Cada persona tiene el suyo y el rol decide qué se puede leer. El agente hereda ese límite, no lo amplía: si tú no puedes ver los contratos de cliente, tu agente tampoco.
Solo lectura y bajo demanda. El agente consulta lo que necesita cuando lo necesita. El corpus entero nunca se pega en el contexto — que además es la mitad de tu factura de tokens.
Las propuestas van a una bandeja. Cuando un agente detecta conocimiento nuevo —una decisión tomada en un MR, un término que nadie había definido—, lo propone. Otro agente lo revisa y lo clasifica antes de que entre al cerebro. El que escribe nunca es el mismo que el que propone, y esa separación es la que evita que el cerebro se llene de ruido.
Lo consultan todos los agentes. El mismo cerebro sirve a la definición (qué construimos) y a la implementación (cómo lo hacemos aquí). No hay una copia por equipo.
El efecto neto es el que buscas de verdad: la IA aprende cómo funciona tu empresa, con tus procesos, en lugar de aplicar la media de internet a tu caso particular.
Cimiento 2: Shield, la aduana
Si toda llamada a un modelo sale por un único punto, ese punto es donde se aplican las políticas y donde se mide. Nuestro Shield está implementado sobre OmniRoute y hace cuatro cosas.
Capa de abstracción. No se pide gpt-x ni claude-y: se pide un modelo lógico. Y las API keys de pago viven aquí, no en cuarenta portátiles.
El día que aparece un modelo mejor o más barato se cambia una línea en el centro. Nadie toca su entorno. Ahí es donde vive la "U" de Universal.
Gobierno por persona. Cada llamada va firmada con la API key personal de quien la hace. De ahí salen consumo, coste y cuota, persona a persona, en tiempo real. No es vigilancia: es la única forma de responder a "¿por qué ha subido la factura?" con un dato en vez de con una teoría.
Filtro de privacidad. Escudo preventivo sobre datos personales y propiedad intelectual antes de que nada salga a la nube.
Optimización de coste. Compresión de contexto y deduplicación de peticiones. En nuestras mediciones internas, hasta un 85% de ahorro en consumo cloud y el 100% de las llamadas trazadas.
Fase 1 · Discovery: la definición vive en Git
Con los cimientos puestos, el ciclo. La primera decisión —y la que más discusión genera— es que el "qué" también es un artefacto versionado. Dos tipos de repositorio sobre el mismo Git: el de producto guarda los requisitos; los técnicos, el código.
repositorio-producto/
├── product_vision.md
├── requirements/
│ ├── RQ-001-exportacion-csv.md
└── context/
└── technical-mapping.md
El requisito no es prosa suelta: lleva sus criterios de aceptación en Gherkin, que es lo que hace que después los tests verifiquen el requisito y no otra cosa.
# requirements/REQ-001-exportacion-csv.md — ILUSTRATIVO
Característica: Exportación de informes a CSV
Para poder analizar los datos fuera de la plataforma
Como usuario con rol analista
Quiero descargar el informe en CSV
Escenario: Exportación de un informe con datos
Dado un informe con 1.500 filas
Y un usuario con rol "analista"
Cuando solicita la exportación en formato CSV
Entonces recibe un fichero con 1.501 líneas
Y la primera línea contiene las cabeceras
Escenario: Exportación sin permisos
Dado un usuario con rol "invitado"
Cuando solicita la exportación en formato CSV
Entonces recibe un error 403
Y no se genera ningún fichero
Y el mapeo técnico, que es la pieza que hace posible la fase siguiente donde se definen los distintos repositorios técnicos asociados.
En esta fase también hay un agente, y consulta al cerebro corporativo lo que necesita saber de la empresa —normativa, decisiones previas, glosario— en lugar de arrastrar todo el contexto en el prompt. Pero lo importante es qué produce: artefactos versionados, no una conversación que se pierde en un historial de chat. El agente estructura, detecta huecos y propone; la persona valida.
Fase 2 · Dispatcher: un requisito, una issue por repositorio
Aquí es donde mucha gente mete un agente y se equivoca. El reparto no lo hace un modelo: lo hace un script contra la API del forge. Mismo input, mismo resultado, siempre. Es transformación de datos, no una tarea cognitiva.
Un requisito se convierte en una issue en el frontend, una en cada microservicio de backend y una en QA. Parece trivial, y lo es. Pero fíjate en lo que consigue: el agente que después implementa no recibe una petición vaga por chat. Recibe una issue con el requisito enlazado, sus criterios de aceptación y el alcance concreto de su repositorio.
La calidad y el acierto de la fase 3 se deciden aquí.
Fase 3 · Delivery: la capa que piensa y la capa que opera
Dentro de cada repositorio técnico conviven dos capas con responsabilidades separadas.
La capa cognitiva: AGENTS.md y .agents/
El manual de estrategia: instrucciones semánticas que dirigen cómo razona el agente antes de escribir una línea.
repositorio-tecnico/
├── AGENTS.md # arquitectura limpia, SOLID, estándares de la casa
├── .agents/
│ ├── workflows/ # los pasos lógicos para abordar una tarea
│ │ ├── nueva-feature.md
│ │ ├── bugfix.md
│ │ └── refactor.md
│ └── skills/ # catálogo de capacidades delegadas
│ ├── generar-contrato-openapi.md
│ └── migracion-bbdd.md
└── src/
Un detalle importante de operación: estos ficheros los distribuye tk. No se copian a mano de repo en repo ni divergen con el tiempo: hay una sola fuente de la verdad y los repositorios la reciben. Si no, a los tres meses tienes catorce dialectos de tus propios estándares.
Un workflow no es un prompt: es un procedimiento.
<!-- .agents/workflows/nueva-feature.md — ILUSTRATIVO -->
# Workflow: nueva feature
1. Lee la issue en `.tasks/` y extrae los criterios de aceptación Gherkin.
2. Consulta `brain` para las decisiones de arquitectura vigentes que
afecten a los módulos implicados. No asumas: pregunta.
3. **Presenta un plan y detente.** El plan debe incluir ficheros a tocar,
contratos nuevos o modificados y estrategia de test. No escribas código
hasta que una persona apruebe el plan.
4. Implementa el test primero, uno por cada escenario Gherkin.
5. Implementa la funcionalidad mínima que pone los tests en verde.
6. Ejecuta `./tk v` y no propongas el MR hasta que esté en verde.
7. Deja en la descripción del MR qué decisión tomaste y qué alternativa
descartaste.
Ese paso 3 es deliberado. La IA no empieza a escribir hasta que alguien ha leído el plan. Es el único filtro barato contra veinte ficheros modificados en la dirección equivocada.
La capa operativa: ./tk
El validador determinista: un motor de comandos dockerizado que impone pruebas objetivas en lugar de opiniones. Existía antes que la IA, y que el agente use exactamente los mismos comandos que las personas es justo lo que hace su trabajo comparable.
$ ./tk st # trae al repo la issue que te has asignado → .tasks/
$ ./tk mr # crea la rama y abre el Merge Request
$ ./tk v # build, tests y cobertura dentro del contenedor
$ ./tk commit # bump de versión, mensaje y push
./tk v es la pieza clave, porque es equivalente a lo que corre en CI. Si pasa en local, pasa en el pipeline; si falla en el pipeline, falla en local. Esa equivalencia elimina la clase entera de problemas del "en mi máquina funciona":
$ ./tk v
▸ contenedor kairos/runtime:2.14.0
▸ build ✓ 12.4s
▸ tests unit ✓ 284 passed
▸ tests contract ✓ 31 passed (OpenAPI v1.7.2)
▸ cobertura ✓ 87.3% (mínimo 85%)
▸ lint ✓ 0 errores, 0 warnings
✓ VALIDACIÓN OK — puedes proponer el Merge Request
La división es limpia: la IA planifica y hace los cambios con .agents; la realidad se opera con ./tk. Sin la capa operativa, la capa cognitiva es un chat con buenas intenciones.
El ciclo completo de una tarea
Ocho pasos. Tres los hace la máquina, uno la IA y cuatro son tuyos:
| # | Paso | Quién |
|---|---|---|
| 1 | Mueves la tarea a Doing en el board y te la asignas | tú |
| 2 |
./tk st — trae la issue al repo, queda en .tasks/
|
automático |
| 3 |
./tk mr — crea la rama y abre el Merge Request |
automático |
| 4 | El agente implementa (plan → validación → código) | la IA |
| 5 |
./tk v — validación equivalente a la de CI |
automático |
| 6 |
./tk commit — bump, mensaje y push |
tú eliges |
| 7 | Revisas el MR, pipeline verde, apruebas y se mergea | tú |
| 8 | Verificas en beta antes de promover a producción | tú |
Y cuatro reglas que no se negocian:
-
Nunca lances
./tkdesde dentro del chat de la IA. Terminal aparte, para no saturar el contexto con salida de build. -
Nunca trabajes sobre
main. Toda tarea vive en su rama y en su MR, sin excepciones y tampoco para arreglos urgentes. - El bump lo apruebas tú, aunque lo proponga la IA.
- Valida el plan antes de aplicar cambios grandes.
Un detalle que suele sorprender: sin IA disponible el ciclo no cambia. Son los mismos ocho pasos, escritos a mano.
La pregunta incómoda: ¿IA para todo?
No. Y lo medimos antes de decidirlo. Comparativa real de nuestras fases, por script frente al mismo trabajo hecho por un agente:
| Fase | Script (tiempo) | IA (tiempo) | Script (coste) | IA (coste) |
|---|---|---|---|---|
sync-tasks |
1 s | 37,7 s | 0 | $0,07 |
create-mr |
3 s | 120 s | 0 | $0,11 |
plan-apply |
n — alta complejidad | ~10 min | n | $0,49 – $4,84 |
bump |
5 s | 156 s | 0 | $0,14 |
commit |
1 s | 15 s | 0 | $0,27 |
En cuatro de las cinco filas gana el script, y no por poco: dos órdenes de magnitud en tiempo y todo el coste. La única fila donde la IA compensa es plan-apply, que es precisamente la que tiene carga cognitiva real.
Multiplica cada fila por las iteraciones de una semana y por el tamaño del equipo. Ahí es donde la decisión de no usar IA se convierte en dinero.
La conclusión no es "la IA no sirve". Es que usar IA donde ya hay un script resuelto es pagar por ir más lento, y que un marco serio te obliga a hacerte esa pregunta fase por fase en lugar de por intuición.
El punto de parada, y lo que hay detrás
Desde la Merge Request en adelante no hay IA. Solo pipeline. Dos decisiones merecen un párrafo.
La imagen se construye una sola vez. Se valida en beta y a producción llega la misma imagen, promovida por el tag. Producción no reconstruye nada: si reconstruyes, lo que despliegas no es lo que probaste.
El estado está declarado en Git. ArgoCD no aplica lo que alguien escribe en una consola: aplica lo que está declarado en el repositorio. El historial de Git es la auditoría, sin herramientas adicionales.
Esta parte es deliberadamente aburrida. La previsibilidad de aquí abajo es justo lo que te permite experimentar arriba.
Cómo adoptarlo sin parar el trabajo
Se adopta por capas, y cada paso vale por sí solo aunque nunca llegues al siguiente:
Paso 1 · Crea el cerebro corporativo. El brain y su MCP, para que todos los agentes puedan consultarlo y proponer contenido. Empieza aquí aunque te parezca el más ambicioso: es lo que hace que todo lo demás tenga contexto.
Paso 2 · Monta el repositorio de producto. Con su product_vision.md y los repositorios técnicos asociados. Ajusta las skills de .agents y empieza a descubrir requisitos y tareas técnicas.
Paso 3 · Prepara los repositorios técnicos. Usa tk para ejecutar las issues y para distribuir AGENTS.md y la carpeta .agents con skills y workflows ajustados a la naturaleza de cada desarrollo.
Paso 4 · Mejora continua del CI/CD. Trabaja la parte determinista: elimina fricciones en la experiencia de desarrollo y fortalece la red de tests. Es la que sostiene todo lo de arriba.
La prueba de fuego
Hay una pregunta que te dice si lo estás haciendo bien:
Si mañana se cae tu proveedor de IA, ¿tu equipo sigue entregando?
Con este marco la respuesta es sí. El ciclo no cambia: los mismos pasos, hechos a mano, más lentos pero igual de seguros. La IA acelera el camino; no es el camino.
Si en tu equipo la respuesta es "no", no tienes un problema de modelo. Tienes un problema de proceso — y esa es una buena noticia, porque los problemas de proceso sí sabemos arreglarlos.
Con L.U.C.I.A. ajustas la IA a tus procedimientos actuales y a tu mejora continua, no al revés. Y si te llevas una última idea, que sea esta:
No es solo IA: hacemos ingeniería.
Rubén Aguilera — FDE & Tech Coach en Kairos. Más de 20 años en el sector IT, speaker ocasional y aprendiz constante. LinkedIn · dev.to/raguilera82
Top comments (0)