Principios de IA agéntica para el desarrollo de software

J.I. Montes-Monsalve, PhD · A.M. Álvarez-Meza, PhD Universidad Nacional de Colombia sede Manizales 2026

2 · IA->Software

El ciclo de vida tradicional: fases y handoffs

  • Fases secuenciales: requisitos, diseño, implementación, pruebas, despliegue y mantenimiento. Cada una con su rol y su entregable.
  • Tres estrategias dominantes: cascada, iterativo/ágil y DevOps con CI-CD.
  • Cada frontera es un handoff humano: un documento, una reunión y una espera entre fases.
  • El costo de corregir crece con la fase: cuanto más tarde se detecta un error de requisitos, más caro resulta corregirlo.
  • Feedback lento: el ciclo de aprendizaje se mide en semanas o meses, no en minutos.
CICLO DE VIDA TRADICIONAL Requisitos negocio + analista Diseño arquitectura Implementación desarrollo Pruebas / QA verificación Despliegue release Mantenimiento operación RETROALIMENTACIÓN: SEMANAS A MESES ESTRATEGIAS Cascada Iterativo / Ágil DevOps · CI-CD Cada frontera = handoff humano · corregir tarde cuesta más

3 · IA->Software

La IA reconstruye el ciclo: de fases a bucles

  • Los artefactos se generan, no se redactan: specs, código, pruebas y documentación salen en minutos (Hou et al., 2024).
  • El cuello de botella se mueve: deja de estar en escribir y pasa a estar en especificar y verificar.
  • Las fases se solapan: un mismo agente cruza diseño, código y pruebas dentro de un solo bucle, sin handoff intermedio.
  • El feedback pasa de semanas a minutos: el ciclo se recorre varias veces al día.
  • Aparece una fase nueva: curar el contexto —specs, memoria y skills— es ahora trabajo de ingeniería.
IA ejecuta Humano decide Revisión conjunta CONTEXTO specs · memoria skills · agentes Intención qué y para quién Diseño IA propone, tú eliges Construcción código · tests · docs Verificación review del diff Entrega merge · deploy Exploración lee y mapea el repo minutos por vuelta

4 · IA->Software

¿Dónde ejecuta la IA y dónde decide el humano?

  • La IA ejecuta: explorar el repo, generar código y pruebas, refactorizar, documentar y dar la primera pasada de revisión.
  • El humano decide: la intención, los requisitos, la arquitectura y los criterios de aceptación. Nada de eso se delega.
  • El humano verifica: lee el diff, corre las pruebas que importan y responde por seguridad y datos sensibles (NIST, 2023).
  • Puertas irrenunciables: merge, despliegue a producción y cualquier operación destructiva o irreversible (Unión Europea, 2024).
  • La regla: la IA propone, el humano dispone. Sin verificación, la velocidad solo acumula deuda técnica.
REPARTO POR ETAPA IA ejecuta Humano decide y verifica Explorar mapea el repo, resume, encuentra Diseñar propone opciones arquitectura y tradeoffs Construir código · tests · docs · refactor Verificar 1ª pasada lee el diff · criterios de aceptación Entregar merge · deploy · rollback PUERTAS HUMANAS: verificar · merge · deploy · borrar La IA propone, el humano dispone

5 · Forward Deployed Engineer

Perfiles tradicionales: back-end, front-end, full stack

  • Back-end: APIs, modelo de datos, escalabilidad e infraestructura. Manda en el servidor.
  • Front-end: interfaz, manejo de estado, accesibilidad y rendimiento en el navegador.
  • Full stack: cruza las dos puntas, pero rara vez con la misma profundidad en ambas.
  • El límite de la vieja escuela: el perfil se optimizó para producir código rápido, y esa es justo la capa que la IA ya cubre.
  • Lo que no se automatiza: decidir la arquitectura, poner los límites del sistema y saber qué NO construir.
PERFILES TRADICIONALES Front-end Interfaz Estado Accesibilidad Back-end APIs Datos Infraestructura Full stack Cruza las dos puntas amplitud, no siempre profundidad LA IA YA CUBRE ESTA CAPA CRUD · boilerplate · glue code · tests base · migraciones LO QUE SIGUE SIENDO TUYO arquitectura · límites del sistema · criterio técnico saber qué NO construir Especializarse solo en una punta ya no alcanza

6 · Forward Deployed Engineer

Los roles de la IA: datos, modelos y producción

  • Data engineer: ingesta, pipelines, calidad y gobierno del dato. Sin datos confiables no hay modelo.
  • Data scientist: hipótesis, features, métricas y validación. Convierte datos en evidencia.
  • AI engineer: modelos en producción, prompts, evals, latencia y costo. Convierte evidencia en producto (Kreuzberger et al., 2023).
  • Ninguno alcanza solo: los datos sin modelo no dan producto, y el modelo sin dato real no sirve.
  • El valor está en el cruce: el problema del negocio no respeta las fronteras del organigrama.
ROLES DE IA Data engineer pipelines · calidad gobierno del dato Data scientist hipótesis · features métricas · validación AI engineer modelos en prod evals · latencia · costo Dato confiable Evidencia Producto ¿POR QUÉ CADA SILO FALLA? Solo datos pipelines impecables que nadie usa en producto Solo modelos métricas de notebook que no sobreviven al dato real Solo herramientas integra el API pero no sabe si el resultado sirve El valor aparece cuando los tres se cruzan

7 · Forward Deployed Engineer

Forward Deployed Engineer: dónde se cruza todo

  • ¿Qué es?: un ingeniero que trabaja dentro del problema del cliente, no detrás de un ticket.
  • Base de software engineering: arquitectura, pruebas y sistemas distribuidos, para poder revisar lo que la IA produce.
  • Base de AI engineering: modelos, evals, costos, límites reales de la herramienta.
  • Programar con IA: dirigir agentes, especificar con precisión y verificar. La IA ejecuta; tú respondes.
  • Habilidades blandas, no opcionales: inglés, comunicación asertiva, trato con clientes y entender el negocio que estás resolviendo.
FORWARD DEPLOYED ENGINEER Software engineering arquitectura · tests · sistemas AI engineering modelos · evals · costo Negocio y cliente entender el problema real FDE despliega en el terreno BASES fundamentos sólidos · programar con IA · dirigir agentes · verificar BLANDAS inglés · comunicación asertiva · trato con clientes · visión de negocio

8 · IA Generativa

¿Qué es un LLM?: predicción, no pensamiento

  • Qué es: una red neuronal con billones de parámetros, entrenada para predecir el siguiente token.
  • No piensa: completa patrones estadísticos, no razona sobre el mundo (Bender et al., 2021).
  • Depende del contexto: la calidad del resultado sigue a la calidad de lo que le das.
TOKENS DE ENTRADA Hola como estas Red Neuronal Billones de parámetros Patrones estadísticos PROBABILIDADES hoy 12% tu 8% bien 67% mal 5% ... 8% Predice el más probable · No "entiende" ≠ Pensar Razonar Comprender

9 · IA Generativa

Modelos que existen hoy

  • Cada modelo tiene su fuerte: Gemini para razonamiento profundo, Opus para código limpio.
  • Especialización por tarea: Codex para testing, Copilot para autocompletado.
  • La clave: no es cuál es «mejor», sino cuál usar en cada tarea.
MODELO CORRECTO PARA CADA TAREA G Gemini Razonamiento profundo O Opus Codigo limpio y preciso C Codex Testing y validacion Co Copilot Autocompletado rapido No existe el "mejor" modelo Cada tarea tiene su motor ideal

10 · IA Generativa

Open source chinos: frontier por centavos

  • Capacidad comparable: Kimi K2.6, MiniMax M2.7 y GLM-5 dan cerca del 90% de Opus o GPT.
  • A 1/15 del precio: el frontier dejó de ser exclusivo de las grandes (Guo et al., 2025).
BENCHMARK COMPARISON Open source chinos: frontier por centavos REFERENCIA OCCIDENTAL GPT 5.5 GPQA 93.6% SWE-bench 88.7% $5 – $30 / M tok Claude Opus 4.7 GPQA 94.2% SWE-bench 87.6% $5 – $25 / M tok VS CHALLENGERS CHINOS Kimi K2.6 GPQA 90.5% SWE-bench 80.2% $0.55 – $2.65 MiniMax M2.7 GPQA 87.4% SWE-bench 78.0% $0.30 – $1.20 GLM-5 GPQA 86.0% SWE-bench 77.8% $0.30 – $1.20 ~90% de capacidad a 1/15 del precio input/output per million tokens

11 · IA Generativa

¿Qué NO es un LLM?

  • No es una base de datos: no almacena tus datos ni aprende de tus conversaciones.
  • No entiende como un humano: tampoco es determinista y puede alucinar (Ji et al., 2023).
  • Si no lo sabes: tendrás expectativas equivocadas y frustración constante.
LO QUE UN LLM NO ES ✕ No es base de datos No almacena hechos, genera texto ✕ No aprende de ti Tus chats no lo re-entrenan ✕ No entiende Completa patrones, no comprende ✕ No es determinista Mismo prompt, distinta respuesta Expectativas incorrectas = frustracion constante Saber que NO es te ayuda a usarlo bien

12 · Chat vs Agente

Chat responde texto. Agente actúa.

  • Un chat genera texto: responde, y ahí termina su alcance.
  • Un agente actúa: lee código, edita archivos, ejecuta tests y guarda aprendizaje (Wang et al., 2024).
  • La diferencia: pedir consejo frente a tener un par-programmer con acceso al proyecto.
CHAT Pregunta Texto Solo genera texto vs AGENTE Lee codigo Edita archivos Ejecuta tests Guarda memoria Actua sobre el entorno

13 · Chat vs Agente

Tools: las capacidades del agente

  • Las capacidades: terminal, editor de archivos, buscador y memoria.
  • Cada tool es externa: sin tools es chat, con tools es agente (Wang et al., 2024).
HERRAMIENTAS DEL AGENTE Agente nucleo Terminal Ejecutar comandos Editor Leer y escribir archivos Buscador Buscar en codebase Memoria Guardar y recuperar contexto Sin tools = Chat | Con tools = Agente

14 · Context Window

La pizarra de tamaño fijo

  • El contexto: system prompt, historial, archivos leídos y tu instrucción.
  • La ventana: el tamaño físico de esa pizarra, medido en tokens (Liu et al., 2024).
VENTANA DE CONTEXTO La pizarra de tamano fijo Todo lo que el modelo "ve" cabe en un espacio finito System Prompt Historial mensajes previos Archivos leidos codigo, docs Tu instruc- cion Espacio libre 128K tokens Cada token que entra desplaza espacio disponible. Cuando se llena, el modelo pierde contexto antiguo. SE LLENA →

15 · Context Window

Attention decay: más no es mejor

  • No falla, degrada: a medida que llenas la ventana la calidad baja (Liu et al., 2024).
  • Los síntomas: instruction drift, sesgo de recencia y código genérico.
  • Por qué es peligroso: es sutil, porque el output «parece» correcto.
ATTENTION DECAY 20% contexto usado Calidad alta 60% contexto usado Calidad media 90% contexto usado Calidad degradada AUMENTA EL RUIDO El output "parece" correcto — pero no lo es

16 · Context Window

Compactación: la amnesia forzada

  • Qué pasa: el sistema resume y borra los mensajes originales (Wang et al., 2024).
  • Qué pierdes: nombres de variables, decisiones de diseño y preferencias del usuario.
COMPACTACION: LA AMNESIA FORZADA ANTES Arquitectura Usar Clean Arch Variable userRepo Patrón Inyeccion de Dep. Preferencia Tabs, no spaces Convencion camelCase strict COMPACTACION DESPUES Resumen generico Arquitectura: ??? Variable: ——— Patron: ——— Preferencia: ——— Contexto perdido 5 decisiones → 1 resumen vago

17 · Context Window

¿Cómo lo ataca la industria?

  • Las opciones: long context, RAG, fine-tuning, memory layers y vector stores.
  • Todas tienen tradeoffs: costo, latencia, precisión y complejidad (Fan et al., 2024).
SOLUCIONES ACTUALES Ninguna resuelve el problema por completo Long Context 1M+ tokens en ventana Degrada calidad en contextos largos RAG Vector search + retrieval Depende de calidad de embeddings Fine-tuning Re-entrenamiento del modelo Lento, costoso y fragil Memory Layers Persistencia experimental No productivo aun ? Cada enfoque sacrifica algo — el problema sigue abierto

18 · Context Window

¿Por qué ninguna solución es completa?

  • Cada una falla distinto: long context degrada y RAG depende de embeddings.
  • Las otras dos: fine-tuning es lento y memory layers siguen siendo experimentales.
  • Lo que falta no es ventana: es memoria que sobreviva sesiones y compactaciones (Liu et al., 2024).
LIMITACIONES ACTUALES Long Context Degrada calidad RAG Depende de embeddings Fine-tuning Lento, no iterativo Memory Layers Experimental Necesitas: memoria que sobreviva sesiones , compactaciones y cambios de modelo → Memoria persistente

19 · Memoria persistente

¿Qué tiene que sobrevivir a la compactación?

  • No la transcripción: lo que tiene que sobrevivir son las decisiones.
  • El caso típico: defines Clean Architecture con DI durante dos horas y no persiste.
  • La regla: guarda el porqué, no el qué (Wang et al., 2024).
Compactación mata decisiones SESSION 1 Clean Architecture DI Pattern Prisma ORM GPX-Store state decisiones arquitectónicas COMPACTACIÓN context window reset SESSION 2 class UserService { // todo: add logic getUser() { return db.query() } ✗ Sin arquitectura ✗ Sin patrones código genérico sin contexto 2 horas de decisiones → destruidas en un resumen El agente arranca de cero. Tus decisiones arquitectónicas no sobreviven.

20 · Memoria persistente

Memoria señal, no total

  • No se guarda todo: el volcado completo es ruido.
  • Se guardan señales: decisiones, errores resueltos y patrones.
  • El formato: observaciones estructuradas con What, Why, Where y Learned.
Memoria señal, no total Guardar todo file_read: package.json command: git status (x47) tool_use: glob *.ts file_read: README.md search: "import React" command: npm install ...y 200 observaciones más RUIDO vs Guardar señales Decisiones Qué se eligió y por qué Errores resueltos Bug + causa + solución Patrones Convenciones del proyecto What/Why/Where/Learned Formato estructurado siempre SEÑAL No ruido, solo señales que importan

21 · Memoria persistente

Progressive disclosure: 3 capas de eficiencia

  • Por capas, no de golpe: el agente decide qué tan profundo ir según lo que necesita.
  • Primero el índice: títulos y snippets compactos.
  • Después: el contexto de la sesión, y solo al final el contenido completo sin truncar.
  • El resultado: mínimo de tokens y máxima precisión.
Progressive Disclosure: 3 capas Capa 1 Barato Índice Títulos + snippets Resultados compactos ↓ Capa 2 Medio Sesión Contexto de sesión Timeline reciente ↓ Capa 3 Profundo Detalle completo Contenido completo Sin truncar MÁS DETALLE El agente decide — mínimos tokens, máxima precisión

22 · Evolución del Contexto

Todo empezó con AGENTS.md

  • La primera idea: un archivo markdown gigante con todas las reglas del proyecto.
  • Qué contenía: estilo, patrones, anti-patrones, convenciones y workflows.
  • Cómo funcionaba: el agente lo leía al inicio y «sabía» cómo trabajar.
EL ORIGEN Todo empezo con AGENTS.md AGENTS.md Estilos Patrones Anti-patrones Convenciones Workflows Reglas de testing Arquitectura +2400 LINEAS Agent Un archivo con TODO el conocimiento

23 · Evolución del Contexto

AGENTS.md crece infinito

  • Cada convención lo engorda: en proyectos reales llega a miles de líneas.
  • El costo: se come la ventana antes de que escribas tu primer prompt.
AGENTS.md crece infinito Cada convencion nueva engorda el archivo 200 lineas Manejable 800 lineas Ruidoso 3000+ lineas Inmanejable Ventana de contexto AGENTS.md — 85% consumido Tu prompt aca?

24 · Evolución del Contexto

Primera evolución: Skills

  • Un router, no un monolito: un AGENTS.md liviano que apunta a SKILL.md específicos.
  • Carga selectiva: solo entra el contexto que necesita la tarea actual.
  • El resultado: contexto dinámico bajo demanda.
Primera evolucion: Skills AGENTS.md router liviano react-19 SKILL.md activo typescript SKILL.md testing SKILL.md django-drf SKILL.md Router → Skill activo Solo se carga lo necesario Contexto bajo demanda

25 · Evolución del Contexto

Anatomía de un SKILL.md

  • El router decide cuál cargar: el módulo dice cómo hacerlo.
  • Qué trae cada SKILL.md: patrones, anti-patrones y templates de su tarea.
  • El criterio: contexto preciso, no contexto completo.
Anatomía de un SKILL.md AGENTS.md Lightweight Router React → react-19 TypeScript → typescript Testing → playwright Styling → tailwind-4 State → zustand-5 ~30 líneas detect intent SKILL.md — react-19 Patterns • Server Components by default • No useMemo/useCallback needed Anti-patterns • "use client" everywhere • useEffect for data fetching Templates • Component scaffold • Hook patterns & examples ~200 líneas de contexto específico Solo se carga lo que necesitás

26 · God Agent y orquestación

Un agente que hace todo: por qué degrada

  • La promesa: «analiza, diseña, testea e implementa» en un solo agente.
  • El problema: llena su contexto al 80% antes de la primera línea (Liu et al., 2024).
  • El resultado: compila, pero ignora las decisiones del paso 1.
ANTI-PATRÓN God Agent: por qué degrada GOD AGENT un solo agente → todas las tareas Analizar Diseñar Implementar Revisar Testear Documentar Refactorizar CONTEXT WINDOW análisis diseño implement. 80% LLENO ↑ zona perdida ⚠ Las decisiones del paso 1 ya no están en contexto El agente alucina o contradice su propio análisis → calidad degrada con cada paso

27 · God Agent y orquestación

Segunda evolución: sub-agentes

  • Skills no alcanza: resuelve qué cargar, pero un solo agente lo sigue acumulando.
  • La salida: delegar cada fase a un sub-agente efímero con contexto fresco.
  • Su ciclo de vida: nace, ejecuta, reporta y muere.
Segunda evolucion: sub-agentes Delegar cada fase a un agente efimero con contexto fresco ORQUESTADOR liviano · solo coordina spawn spawn spawn contexto vacio Explorar nacer → ejecutar → reportar → ✕ contexto vacio Disenar nacer → ejecutar → reportar → ✕ contexto vacio Implementar nacer → ejecutar → reportar → ✕ Contexto fresco por fase

28 · God Agent y orquestación

Divide y vencerás: orquestador + sub-agentes

  • El orquestador no trabaja: coordina.
  • Delega por especialidad: cada sub-agente recibe solo lo que necesita (Wang et al., 2024).
  • El resultado: máxima precisión y cero ruido acumulado.
ARQUITECTURA DE AGENTES Divide y vencerás ORQUESTADOR solo coordina · sin código Explorar investigar · contexto contexto 18% Especificar specs · diseño contexto 15% Implementar código · tasks contexto 20% Verificar tests · validar contexto 16% Máxima precisión, cero ruido acumulado cada agente nace limpio · contexto mínimo · foco total

29 · God Agent y orquestación

Fresh context: arrancar limpio

  • Pizarra vacía: cada sub-agente nace sin historial previo.
  • Solo su fase: recibe las instrucciones que le tocan, sin ruido anterior (Wang et al., 2024).
  • Por qué importa: es la ventaja arquitectónica clave del patrón.
COMPARACIÓN Fresh context: arrancar limpio GOD AGENT prev context... old tool calls... stale files... wrong paths... hallucinations... 85% 85% usado ruido acumulado ! VS SUB-AGENTE tarea enfocada 15% 15% usado solo su tarea Cada sub-agente nace con la pizarra vacía

30 · God Agent y orquestación

El patrón actual: todo junto

  • Orquestador: coordina el flujo sin ejecutar trabajo.
  • Skills: aportan el contexto preciso de cada tarea.
  • Sub-agentes: ejecutan limpio, con contexto fresco.
  • Memoria persistente: da continuidad entre sesiones.
EL PATRÓN COMPLETO El patrón actual: todo junto ORQUESTADOR Coordinador ligero delega, no ejecuta SKILLS Contexto preciso cargadas bajo demanda SUB-AGENTES Agentes efímeros contexto fresco cada vez MEMORIA PERSISTENTE Continuidad entre sesiones Decisiones que sobreviven la sesión carga lanza lee/escribe consulta reporta Arquitectura que resuelve limitaciones del LLM

31 · Spec-Driven Development

La filosofía: ingeniería aplicada a IA

  • El cuello de botella: dejó de estar en escribir y pasó a especificar y verificar.
  • La respuesta: en vez de «pedir y rezar», una línea de montaje de expertos.
  • Qué es SDD: principios de ingeniería de software aplicados al flujo con IA (Hou et al., 2024).
LA FILOSOFÍA Ingeniería aplicada a IA PEDIR Y REZAR ? Un prompt, una oración → LÍNEA DE MONTAJE Explore Spec Apply Expertos especializados ✓ Resultado verificado Spec-Driven Development Principios de ingeniería de software aplicados al flujo con IA

32 · Spec-Driven Development

De la idea al código, con trazabilidad

  • Seis fases, un artefacto cada una: entender, decidir, descomponer, traducir, construir y cerrar.
  • Orden estricto: ninguna fase empieza sin la anterior.
  • Trazabilidad: cada línea de código se rastrea hasta el requisito que la justifica.
De la idea al código, con trazabilidad cada fase produce algo que se puede verificar 1 Entender brief y PRD requisitos numerados 2 Decidir arquitectura y UX se decide una sola vez 3 Descomponer épicas e historias Given / When / Then 4 Traducir contrato ejecutable determinista 5 Construir código que cumple los escenarios son los tests 6 Cerrar el contrato es la verdad mide lo que llegue después trazabilidad cada línea de código, el requisito que la justifica

33 · Spec-Driven Development

Especificación por ejemplo

  • Prosa contra ejemplo: un requisito en prosa se interpreta, un ejemplo se ejecuta.
  • Given/When/Then: convierte «debe validar el email» en casos que pasan o fallan.
  • Un solo artefacto: el criterio de aceptación y el test dejan de ser dos documentos.
De la prosa al ejemplo EN PROSA "El sistema debe validar el email del usuario." ¿qué formato? ¿y si falla? ¿mayúsculas cuentan? Se interpreta POR EJEMPLO GIVEN un email sin arroba WHEN el usuario se registra THEN responde 422 y no crea la cuenta Se ejecuta El mismo artefacto sirve dos veces Criterio de aceptación para el humano · caso de prueba para la máquina El agente no adivina Implementa contra un caso, no contra una interpretación. Verificar deja de ser opinión El ejemplo pasa o falla. No hay término medio.

34 · Spec-Driven Development

La matriz de trazabilidad

  • La cadena: requisito, historia, contrato, tarea, código y test, cada eslabón al anterior.
  • Hacia abajo: verifica que nada se construyó de más.
  • Hacia arriba: dice qué se rompe cuando el requisito cambia.
Cada eslabón apunta al anterior Requisito qué tiene que pasar y por qué Historia quién lo necesita y para qué Contrato la regla, escrita en estricto Tarea la unidad de trabajo, acotada Código la implementación que la cumple Test el ejemplo, ahora ejecutable COBERTURA ¿construí de más? IMPACTO ¿qué se rompe? Sin la cadena completa, "trazabilidad" es solo una palabra

35 · Spec-Driven Development

Las tres reglas que lo sostienen

  • El contrato se regenera: nace de la historia y no se edita a mano.
  • Control de alcance: lo pasa un requerimiento nuevo, no un defecto.
  • Un solo dueño: cada dato se define en un único lugar.
Las tres reglas que lo sostienen 1 El contrato es derivado, no fuente historia se regenera contrato editar a mano lo desincroniza si el contrato está mal, la historia está mal 2 El alcance se controla antes de tocar archivos requerimiento nuevo control de alcance dentro del alcance scope creep épica nueva defecto no negocia alcance directo al arreglo 3 Cada dato tiene un solo dueño duplicar entre capas = contradecirse el qué de negocio el qué técnico el porqué el dónde

36 · Spec-Driven Development

¿Por qué esto no es cascada?

  • La objeción es justa: hay fases ordenadas y ninguna empieza sin la anterior.
  • En cascada: el documento se congela y cualquier cambio renegocia el plan.
  • Aquí: el contrato se regenera desde la historia y un defecto no pide permiso.
  • La diferencia: las fases dan orden, no rigidez.
Mismas fases, distinta física CASCADA SPEC-DRIVEN EL CICLO Se recorre una vez por proyecto Se recorre varias veces al día EL ARTEFACTO Documento congelado en la fase Se regenera desde la historia EL CAMBIO Pasa por comité y renegocia todo Solo si cambia lo acordado LAS FASES Cerradas, con handoff humano Ordenadas, con artefacto verificable El orden no es el problema de cascada. Lo es el congelamiento.

37 · Spec-Driven Development

Los roles especializados

  • Explorer y Proposer: leen el código y definen qué se hace.
  • Spec Writer y Designer: escriben los requisitos y la arquitectura.
  • Task Planner: divide el trabajo en tareas ordenadas.
  • Implementer y Verifier: escriben el código y validan la calidad.
Los roles especializados 7 sub-agentes del flujo SDD 1 Explorer Lee código y analiza contexto 2 Proposer Define qué cambiar y por qué 3 Spec Writer Requisitos y escenarios 4 Designer Arquitectura y decisiones técnicas 5 Task Planner Divide en tareas implementables 6 Implementer Escribe código siguiendo el plan 7 Verifier Valida contra specs y diseño proposal → specs ∥ design → tasks → apply → verify Orquestador coordina el flujo delega todo — nunca ejecuta

38 · Spec-Driven Development

El DAG: flujo de dependencias

  • El flujo: Proposal → [Specs || Design] → Tasks → Apply → Verify → Archive.
  • Con checkpoints: las fases se ejecutan en orden y se validan al pasar.
  • En paralelo: Specs y Design pueden avanzar a la vez.
El DAG: flujo de dependencias Cada fase depende de la anterior — sin atajos Proposal Specs Design Paralelo Tasks Apply Verify Archive proposal → [specs ‖ design] → tasks → apply → verify → archive Spec-Driven Development — DAG de fases

39 · Spec-Driven Development

Ejemplo real: crear endpoint de usuarios

  • Arranque: Explorer detecta el stack y Proposer define el alcance.
  • Planeación: Spec y Design corren en paralelo, y Tasks divide en cuatro.
  • Ejecución: Implementer genera el código y Verifier lo valida contra las specs.
Ejemplo real: crear endpoint usuarios /sdd:new create-users-endpoint Explorer detecta Next.js + Prisma stack Proposer define POST /api/users con validación Zod Spec requisitos + escenarios Design arquitectura técnica || Tasks 4 tareas: modelo ruta API validación test Implementer genera código siguiendo specs + design Verifier valida contra specs: ✓ pass 6 fases · 1 comando · 0 fricción

40 · Spec-Driven Development

¿Por qué escala?

  • Aislamiento de contexto: el Implementer no se distrae con dudas del Explorer.
  • Checkpoints de calidad: si el Verifier rechaza, no llega al PR.
  • Memoria institucional: lo aprendido queda para la próxima vuelta.
Por qué escala Aislamiento de contexto Cada agente solo ve lo que necesita. Sin ruido acumulado. Checkpoints de calidad Verifier chequea contra specs antes de ir al PR. Memoria institucional La memoria persistente guarda las decisiones: la próxima sesión arranca donde terminó esta. SCALE

41 · Engram

Ecosistema: Engram + SDD + Skills

  • Hasta aquí, la teoría: estas son las piezas que la implementan.
  • Una pieza por límite: Engram da continuidad, Skills consistencia y SDD estructura.
  • Los límites que cubren: amnesia, genericidad y degradación.
Ecosistema: Engram + SDD + Skills Engram Memoria persistente Continuidad SDD Workflow orquestado Estructura Skills Patrones codificados Consistencia LLM sin amnesia, degradación ni genericidad Continuidad + Estructura + Consistencia = Sistema profesional

42 · Engram

Arquitectura: Go + SQLite + FTS5

  • Un binario: sin dependencias externas.
  • Almacenamiento: SQLite con Full-Text Search 5.
  • Se conecta vía MCP: Claude Code, OpenCode, Kilo Code, Gemini CLI, Cursor y Copilot.
  • Y también: Codex, Windsurf, Antigravity, Kimi Code, Qwen Code y Kiro IDE.
Arquitectura: Go + SQLite + FTS5 12 AGENTS Claude OpenCode Kilo Gemini Cursor VS Code Codex Windsurf Antigrav Kimi Qwen Kiro IDE + cualquier MCP agent MCP Protocol ENGRAM Go Go binary Compilado, rápido SQLite Embebido, sin servidor FTS5 Full-text search Un binario. Sin dependencias. Funciona offline.

43 · Engram

Las herramientas de memoria

  • Cinco herramientas críticas: son el núcleo de la memoria en cualquier agente.
  • mem_current_project: confirma qué proyecto recibe tus saves antes de escribir.
  • mem_save: captura el prompt asociado sin llamar a mem_save_prompt.
Las herramientas de memoria mem_save Guarda una decisión o descubrimiento mem_search Busca contexto de sesiones anteriores mem_context Recupera la sesión inmediata anterior mem_session_summary Resume la sesión para el futuro mem_current_project NEW Detecta el proyecto desde tu cwd ✨ mem_save ahora captura el prompt asociado automáticamente

44 · Engram

El Engram Loop: dos sesiones

  • Sesión 1: diseñas y guardas la decisión con mem_save.
  • Sesión 2: mem_search la recupera y el código sale consistente.
  • La diferencia: sin Engram la sesión 2 ignora la 1, con Engram hay continuidad.
El Engram Loop: dos sesiones SESSION 1 diseñar → mem_save guarda decisión SESSION 2 implementar → mem_search recupera decisión ENGRAM persistent storage WRITE READ Sin Engram ✗ Session 2 ignora las decisiones de Session 1 Con Engram ✓ Session 2 conoce las decisiones de Session 1 La memoria persiste entre sesiones — el agente no parte de cero

45 · Engram

Dos formas de sincronizar: git o Cloud

  • Dos caminos válidos: uno para uso individual y otro para equipo.
  • Git sync: usa tu repo existente, sin infra extra y de forma asíncrona.
  • Engram Cloud: servidor self-hosted con dashboard, autosync y roles.
  • El criterio: eliges entre simplicidad o visibilidad.
Dos formas de sincronizar Git sync INFRA Zero usa tu repo existente SYNC Async commit-based VISIBILITY CLI / archivos git log, mem_search CUÁNDO Sin infra extra commit-based · async Engram Cloud INFRA Postgres + servidor self-hosted SYNC Real-time autosync background VISIBILITY Dashboard web multi-user, roles CUÁNDO Querés dashboard real-time · multi-user Ambos sirven solo y para equipo — elegís según necesidad

46 · Engram

Cloud mode: el mismo binario engram, multi-máquina y real-time

  • No es otro producto: es un modo del mismo binario engram.
  • Qué cambia: pasas de SQLite local a Postgres con engram cloud serve.
  • Qué sumas: dashboard web, autosync con backoff exponencial y JWT con roles.
  • Self-hosted: tu hardware, tu data y sin telemetría.
Engram Cloud Machine 1 local + sync Machine 2 local + sync Engram Cloud SELF-HOSTED templ + htmx dashboard autosync autosync +24 +11 JWT auth Dashboard Postgres Self-hosted Backoff exponencial · multi-user · roles Tu hardware, tu data — sin telemetría

47 · Engram

Auto-detect: el proyecto lo decide tu cwd, no el LLM

  • El problema: los agentes inventaban nombres distintos y rompían la búsqueda.
  • La solución: Engram detecta el proyecto desde tu cwd vía git remote.
  • El LLM no puede mentir: los write tools ya no aceptan el campo project.
  • Si hay ambigüedad: te avisa con la lista de proyectos disponibles.
Auto-detect del proyecto BREAKING cwd $ pwd ~/work/stream-web GIT REMOTE github.com/Org/stream-web → normalize: lowercase + trim CANONICAL PROJECT stream-web SI HAY AMBIGÜEDAD Encontré proyectos similares: stream-web match stream-mode streaming-app Te avisa con la lista — no inventa el nombre. Write tools ya no aceptan project

48 · Engram

Prompt capture automático: contexto que se guarda solo

  • Captura automática: mem_save guarda el prompt asociado sin que lo pidas.
  • Cómo funciona: SessionActivity recuerda el último prompt y mem_save lo dedupea.
  • El resultado: cada decisión guardada trae el contexto que la motivó.
  • mem_save_prompt: sigue disponible cuando un hook necesita anticiparse.
Prompt capture automático USER PROMPT "refactorizá el auth para usar JWT en vez de session" auto SessionActivity recuerda último prompt auto mem_save() call title: "Refactor auth → JWT" type: decision PERSISTED TOGETHER Observation decisión + Prompt contexto que motivó FALLBACK mem_save _prompt para hooks anticipatorios

49 · Engram

Engram vs alternativas: por qué lightweight gana

  • Sin infraestructura: sin servidor, sin embeddings y sin cloud.
  • Un binario local: funciona offline.
  • Para equipos que arrancan: la simplicidad es la feature más importante.
Engram vs alternativas Feature RAG / Vector Fine-tuning Engram Servidor requerido ✓ ✓ ✗ Costo Alto Muy alto Gratis Setup Complejo Complejo 1 binario Funciona offline ✗ ✗ ✓ Para equipos que arrancan, la simplicidad es la feature más importante WINNER

50 · Skills Registry

skill-creator: el equipo enseña al agente

  • El conocimiento lo tiene el equipo: no el modelo.
  • Con skill-creator: cada persona crea sus convenciones, patrones y checklists.
  • Contextual loading: el agente carga las skills relevantes al detectar triggers.
  • El efecto: se acaba el «olvidé usar la skill X».
skill-creator: el equipo enseña al agente Dev Frontend Tech Lead QA Engineer SKILL.md Convenciones naming, estructura, estilos SKILL.md Patrones arquitectura, DDD, SOLID SKILL.md Checklists testing, PR review, deploy Skills Registry contextual loading react-19 typescript playwright zustand AI Agent con contexto específico El conocimiento institucional lo tiene el equipo

51 · Skills Registry

Contextual skill loading: orchestrator resuelve, sub-agents consumen

  • Una sola lectura: el orchestrator lee el registry al inicio y cachea las rules.
  • Por delegación: matchea triggers de archivo y tarea, e inyecta las rules digeridas.
  • Los sub-agents no leen nada: reciben todo pre-resuelto.
  • Compaction-safe: si el caché se pierde, la siguiente delegación re-lee el registry.
Contextual skill loading skill-registry .atl/skill-registry.md Orchestrator resolves once cache read once apply sub-agent verify sub-agent design sub-agent compact rules compact rules compact rules compact rules injected, not paths — pre-digeridas, compaction-safe sub-agents NO leen SKILL.md ni el registry

52 · Spec-Driven Development

Model router: un motor por fase

  • No existe el «mejor modelo»: existe el adecuado para cada fase.
  • El reparto: Gemini para arquitectura, Opus para implementación y Codex para testing.
  • Ya soportado: OpenCode, Kilo Code y Kiro IDE, con subagents nativos.
  • Tú decides: qué motor maneja cada fase del DAG.
Model router: un motor por fase ORCHESTRATOR Arquitectura → Gemini Implementación → Opus Testing → Codex Review → Claude CONFIGURABLE OpenCode Kilo Code Kiro IDE multi-mode SDD soportado "No existe el mejor modelo — existe el correcto para cada fase" 3 plataformas con multi-mode: OpenCode, Kilo Code, Kiro IDE

53 · UN-SpecWeaver

BMAD y OpenSpec: las piezas del flujo

  • Las herramientas que las producen: especificación por ejemplo y matriz de trazabilidad.
  • BMAD: te lleva de la idea a la historia.
  • OpenSpec: arranca en el contrato y lo valida en estricto.
  • El hueco: cada una resuelve su tramo y ninguna cubre el de la otra.
BMAD y OpenSpec: las piezas del flujo BMAD 1 · entender 2 · decidir 3 · descomponer produce épicas e historias Given / When / Then OpenSpec 4 · contrato ejecutable 5 · construir 6 · cerrar produce specs verificables validate --all --strict termina en la historia arranca en el contrato ? gentle-ai + Engram construcción · revisión · memoria

54 · UN-SpecWeaver

un-specweaver: el puente que faltaba

  • La fase 4 no la resolvía nadie: BMAD terminaba en la historia y OpenSpec arrancaba en el contrato.
  • El puente la cierra: mismo epics.md y mismos contratos, byte por byte.
  • Lo que aporta: el enlace requisito ↔ historia ↔ contrato queda escrito en un archivo.
un-specweaver: el puente que faltaba BMAD fases 1-3 4 · TRADUCIR — el puente misma entrada, misma salida, siempre OpenSpec fases 4-6 BMAD OpenSpec ## Epic {N} capability ### Story {N}.{M} un change Given / When / Then #### Scenario FR Coverage Map trace.json determinista: misma entrada, misma salida no forkea nada: orquesta y pinea versiones poda los agentes constructores que se pisan

55 · UN-SpecWeaver

Solo-agent vs Full delegation: dos formas de hacer SDD

  • Full delegation: cada fase corre en un sub-agent con contexto fresco.
  • Quién lo soporta: Claude Code, OpenCode, Kilo Code, Cursor, Gemini CLI y Copilot.
  • Solo-agent: todas las fases corren inline y el orchestrator es el ejecutor.
  • Quién lo soporta: Codex, Windsurf y Antigravity, con Engram dando persistencia.
Solo-agent vs Full delegation Full delegation orch coord explore fresh ctx propose fresh ctx apply fresh ctx verify fresh ctx SOPORTADO POR Claude · OpenCode · Kilo · Cursor Gemini · VS Code · Kimi · Qwen · Kiro Solo-agent orchestrator = executor explore propose spec design tasks apply verify archive Engram = persistencia entre fases SOPORTADO POR Codex · Windsurf · Antigravity Dos formas válidas — la misma estructura SDD

56 · UN-SpecWeaver

Resultado: velocidad + consistencia + calidad

  • Velocidad: por automatización.
  • Consistencia: por skills.
  • Calidad: por verificación contra specs.
  • El cambio de rol: el developer pasa de escribir código a dirigir y validar código.
RESULTADO Velocidad + Consistencia + Calidad Velocidad Automatización del flujo Consistencia Skills estandarizan código Calidad Verificación contra specs El developer pasa de escribir código a dirigir y validar

57 · UN-SpecWeaver

El setup: el stack y los agentes que lo hablan

  • gentle-ai: el instalador del stack. Un comando, tres sistemas operativos, cero configuración artesanal.
  • Engram: la memoria persistente que sobrevive a la compactación y a la sesión.
  • El flujo spec-driven: BMAD, OpenSpec y el puente entre ambos. Vía de instalación propia, sobre el mismo entorno.
  • Cuatro agentes CLI: Claude Code, Codex, OpenCode y Pi, con el mismo protocolo en los cuatro.
  • El stack no es el agente: skills, SDD y memoria viven fuera del modelo, así que cambiar de agente no cuesta el setup.
EL SETUP EL STACK gentle-ai Engram AGENTES CLI COMPATIBLES $ claude Claude Code $ codex Codex $ opencode OpenCode $ pi Pi Un comando instala el stack en los cuatro skills · SDD · memoria · reglas de orquestación

58 · UN-SpecWeaver

¿Por qué CLI y no el chat web o la app de escritorio?

  • El agente vive donde vive el código: lee, escribe y ejecuta en tu repositorio real, no sobre un fragmento que pegaste.
  • Su verdad son las herramientas: git, tests, linters y build. No tu descripción del problema.
  • Cierra el ciclo solo: propone, ejecuta, ve el error y corrige. En el chat el cable entre la ventana y el editor eres tú.
  • El setup se versiona: reglas, skills y memoria viven en el repo y viajan con el equipo.
  • Se automatiza: corre en hooks, scripts y CI. Una ventana de chat no entra en un pipeline.
CHAT WEB / APP Describes el problema El modelo responde texto COPIAS Y PEGAS tú eres el transporte Falla y vuelves a contarlo No ve el repo · no ejecuta · no verifica AGENTE CLI Le das la intención CICLO CERRADO lee el repo · escribe corre tests · lee el error corrige y repite sin intervención manual Revisas el diff Versionable · scriptable · va en CI El copy-paste no es una molestia: es el cuello de botella

59 · UN-SpecWeaver

La diferencia: arquitectura alrededor del modelo

  • El modelo es el motor: potente, pero solo una pieza.
  • Sin chasis ni frenos: un motor suelto no es un auto, es un peligro.
  • La arquitectura decide: define si tienes un juguete o una herramienta.
LA DIFERENCIA Arquitectura alrededor del modelo MODELO SOLO prompt context? output ??? retry random log? hack copy paste LLM Engine Motor sin chasis vs MODELO + ARQUITECTURA LLM Engine SDD Engram Skills Context Auto completo

60 · UN-SpecWeaver

Empieza aquí: GentlemanDots y gentle-ai

  • GentlemanDots: el entorno completo listo para trabajar con agentes — terminal, multiplexor y editor ya configurados.
  • gentle-ai: encima del entorno, instala el stack: skills, protocolo SDD, Engram y las reglas de orquestación.
  • Por qué importa: el setup deja de ser artesanal. Se instala, se versiona y se repite en cualquier máquina del equipo.
EMPIEZA AQUÍ GentlemanDots terminal · multiplexor · editor el entorno donde trabajas github.com/Gentleman-Programming encima gentle-ai skills · SDD · Engram · reglas el stack sobre el entorno gentle-ai install Un comando, cualquier agente, cualquier sistema El setup deja de ser artesanal: se instala, se versiona y se repite

61 · Referencias

Referencias

  • Bender, E. M., Gebru, T., McMillan-Major, A., & Shmitchell, S. (2021). On the dangers of stochastic parrots. En Proceedings of the 2021 ACM Conference on Fairness, Accountability, and Transparency (pp. 610–623). ACM. https://doi.org/10.1145/3442188.3445922
  • Fan, W., Ding, Y., Ning, L., Wang, S., Li, H., Yin, D., Chua, T., & Li, Q. (2024). A survey on RAG meeting LLMs: Towards retrieval-augmented large language models. En Proceedings of the 30th ACM SIGKDD Conference on Knowledge Discovery and Data Mining (pp. 6491–6501). ACM. https://doi.org/10.1145/3637528.3671470
  • Guo, D., Yang, D., Zhang, H., Song, J., Wang, P., Zhu, Q., Xu, R., Zhang, R., Ma, S., Bi, X., Zhang, X., Yu, X., Wu, Y., Wu, Z., Gou, Z., Shao, Z., Li, Z., Gao, Z., Liu, A., … Zhang, Z. (2025). DeepSeek-R1 incentivizes reasoning in LLMs through reinforcement learning. Nature, 645(8081), 633–638. https://doi.org/10.1038/s41586-025-09422-z
  • Hou, X., Zhao, Y., Liu, Y., Yang, Z., Wang, K., Li, L., Luo, X., Lo, D., Grundy, J., & Wang, H. (2024). Large language models for software engineering: A systematic literature review. ACM Transactions on Software Engineering and Methodology, 33(8), 1–79. https://doi.org/10.1145/3695988
  • Ji, Z., Lee, N., Frieske, R., Yu, T., Su, D., Xu, Y., Ishii, E., Bang, Y. J., Madotto, A., & Fung, P. (2023). Survey of hallucination in natural language generation. ACM Computing Surveys, 55(12), 1–38. https://doi.org/10.1145/3571730
  • Kreuzberger, D., Kühl, N., & Hirschl, S. (2023). Machine learning operations (MLOps): Overview, definition, and architecture. IEEE Access, 11, 31866–31879. https://doi.org/10.1109/access.2023.3262138
  • Liu, N. F., Lin, K., Hewitt, J., Paranjape, A., Bevilacqua, M., Petroni, F., & Liang, P. (2024). Lost in the middle: How language models use long contexts. Transactions of the Association for Computational Linguistics, 12, 157–173. https://doi.org/10.1162/tacl_a_00638
  • National Institute of Standards and Technology. (2023). Artificial intelligence risk management framework (AI RMF 1.0) (NIST AI 100-1). U.S. Department of Commerce. https://doi.org/10.6028/NIST.AI.100-1
  • Unión Europea. (2024). Reglamento (UE) 2024/1689 del Parlamento Europeo y del Consejo, de 13 de junio de 2024, por el que se establecen normas armonizadas en materia de inteligencia artificial. Diario Oficial de la Unión Europea. https://eur-lex.europa.eu/eli/reg/2024/1689/oj
  • Wang, L., Ma, C., Feng, X., Zhang, Z., Yang, H., Zhang, J., Chen, Z., Tang, J., Chen, X., Lin, Y., Zhao, W. X., Wei, Z., & Wen, J. (2024). A survey on large language model based autonomous agents. Frontiers of Computer Science, 18(6), Artículo 186345. https://doi.org/10.1007/s11704-024-40231-1