Cómo construimos nuestro marco de desarrollo guiado por especificaciones (SDD) y cómo construir el suyo

Por Alfredo Castillejos · Dixi-Project · 4 de noviembre de 2026 · 16 min de lectura
Ilustración: cinco columnas de colores sobre dos barras horizontales, con un documento a la izquierda y una marca de verificación a la derecha.

En los artículos anteriores contamos piezas sueltas: cómo clasificamos el riesgo de un cambio, quién responde por el código que escribe la IA y qué pasó en treinta días con un mantenedor, un agente y 141 PRs. Este artículo es el mapa que las une: cómo está hecho el marco de desarrollo guiado por especificaciones (SDD) con el que construimos todos nuestros sistemas, por qué tiene la forma que tiene y cómo puede construir el suyo otra organización.

El marco se llama EIS-IA (Ecosistema de Ingeniería de Software Asistida por IA). Vive en un repositorio propio y lleva 20 versiones publicadas desde marzo de 2026; la más reciente es la 4.11.0, del 5 de noviembre. De él nace cada proyecto nuevo de la empresa, y los existentes lo adoptan, como la plataforma que sirve el sitio donde lee esto.

La idea en una frase: con IA, el cuello de botella ya no es escribir código, sino validarlo. La velocidad de un equipo la marca su capacidad de validar, no la de generar. Todo lo demás se desprende de ahí. Y vale igual para un equipo de desarrollo que para una sola persona trabajando con agentes: el marco opera de las dos formas, con los mismos controles.

Qué entendemos por SDD

En un desarrollo guiado por especificaciones, la especificación manda: el código se escribe para cumplirla y la prueba demuestra que la cumple. Con agentes de IA esto deja de ser una buena costumbre y se vuelve una necesidad práctica, porque el agente solo sabe lo que está escrito. Lo que no está en el repositorio, para el próximo agente no existe.

Pero un SDD no es una carpeta de documentos. Nuestra primera versión lo era, y ahí empieza la historia.

Cómo llegamos aquí: tres versiones, tres lecciones

Versión Fecha Qué traía Qué aprendimos
1.0 Marzo 2026 Estructura de especificaciones por secciones numeradas, cuatro agentes (arquitecto, desarrollador, probador y revisor) y un modo de operación Una estructura no garantiza nada si nadie la verifica
3.0 Octubre 2026 Las reglas pasan a ser mecanismos que fallan solos: hooks del agente, gates en la pipeline, responsabilidad humana firmada Una regla que depende de que alguien se acuerde no es un control
4.x Octubre y noviembre 2026 Proceso proporcional a la ambigüedad y al riesgo de cada tarea, perfiles según el tamaño del proyecto, autonomía delegada y un límite de trabajo en curso La misma ceremonia para un typo que para una migración cuesta mucho y no compra calidad; y con agentes, lo que se agota es la atención de quien revisa

La versión 2.0 (mayo de 2026) agregó lo que rodea al código: guía para cualquier agente, no solo uno, due diligence, estrategia de calidad completa y un playbook para arrancar proyectos de clientes.

El modelo: cinco pilares y dos ejes

Modelo de EIS-IA: cinco pilares sostenidos por dos ejes transversales

Cada pilar responde una pregunta. Si falta uno, el ecosistema queda incompleto: generar sin verificar es vibe coding; verificar sin operar es una pipeline en verde que no dice nada de producción.

Pilar Pregunta que responde Qué contiene
Métodos ¿Cómo se piensa y se especifica el software? SDD, DDD, BDD, TDD, pruebas de propiedades, pruebas de contrato, historias de usuario
Orquestación ¿Cómo trabajan juntos personas y agentes? Un ciclo de agentes especializados con modos de operación
Gobernanza ¿Quién decide, quién aprueba y quién responde? Decisiones de arquitectura (ADR), políticas, uso de IA, cumplimiento
Verificación ¿Cómo sabemos que es correcto y seguro antes de producción? Escalera de verificación, hooks, gates del PR, análisis de seguridad, revisión por riesgo
Operación ¿Cómo se despliega, se observa y se recupera? Cadena de despliegue, observabilidad, SLOs, rollback, incidentes, costos

Los dos ejes atraviesan los cinco pilares y hacen que lo decidido sobreviva a cambios de agentes, de modelos y de equipos:

  • Gestión del conocimiento. Una decisión que no está escrita no existe. El contexto de un agente es efímero; el repositorio no.
  • Trazabilidad. Cada línea en producción se puede seguir hasta su porqué: objetivo de negocio → dominio → módulo → feature → contrato → prueba, y después tarea → commit → PR → artefacto → despliegue.

Una regla práctica que sale del modelo: todo mecanismo nuevo declara a qué pilar pertenece y qué eje refuerza. Si no encaja en ninguno, probablemente sobra.

Las piezas, una por una

1. Especificaciones con trazabilidad verificada por máquina

El repositorio tiene 29 secciones numeradas, del negocio y los dominios a los contratos de API, datos, arquitectura, calidad, seguridad, despliegue y operación. La numeración no es estética: da un orden de lectura, y un agente que llega en frío sabe por dónde empezar.

La trazabilidad no se revisa a ojo. Un validador recorre el repositorio y falla si un módulo no cita su dominio, si una feature no cita su módulo o si un documento menciona otro que no existe. Funciona como trinquete: la deuda acumulada se registra en una línea base y el validador solo falla ante hallazgos nuevos. La línea base solo puede bajar, nunca subir para silenciar un error.

2. Norma y proyecto, separados

Cada proyecto nace como copia del marco, y eso obliga a decir qué es de quién. Cada carpeta cae en una de cuatro clases:

Clase Qué significa
Norma La define el marco y rige en todos los proyectos. No se edita en el proyecto: un cambio se propone en el marco y llega con la siguiente versión
Hueco Estructura que cada proyecto llena con lo suyo: negocio, dominios, contratos
Ejemplo Muestra de un hueco lleno. No viaja a los proyectos
Del marco Estado del propio marco como proyecto. No viaja

Las decisiones de arquitectura siguen la misma separación: las numeradas del 1 al 99 son del marco y las del 100 en adelante, de cada proyecto. Apartarse de una norma es posible, pero exige escribir por qué, en una decisión propia del proyecto. La plataforma que sirve este sitio tiene varias; por ejemplo, la que la deja operar con una sola persona.

Aprendimos esta separación a la mala: hasta la versión 3.0, los proyectos nuevos nacían con los dominios del gimnasio que usábamos de ejemplo.

3. Orquestación: un ciclo de agentes con la prueba congelada

Una tarea de construcción recorre cinco pasos, cada uno con un agente especializado:

  1. Arquitecto: lee las especificaciones y propone un plan.
  2. Probador: escribe las pruebas que deben fallar, y se congelan en su propio commit.
  3. Desarrollador: escribe el código hasta ponerlas en verde, sin tocarlas.
  4. Probador: verifica el conjunto.
  5. Revisor: compara el resultado con la especificación y los riesgos.

La pieza clave es el paso 2. Una prueba aprobada es una especificación ejecutable, y el agente no puede editarla: un hook lo bloquea. Si una prueba parece incorrecta, el agente se detiene y lo explica; la cambia una persona. Sin esta regla, el camino más corto a «verde» sería ajustar la prueba.

¿Cuándo pregunta el agente? Aquí aplicamos lo que llamamos autonomía delegada: dentro de su rama, el agente avanza solo y se detiene únicamente en las fronteras, un catálogo cerrado de casos. Por ejemplo: romper un contrato publicado, borrar datos, tocar permisos o secretos, agregar una dependencia no autorizada, encontrar dos especificaciones que se contradicen o una prueba congelada que parece incorrecta. Fuera de ese catálogo decide, y escribe cada supuesto en el PR, con la alternativa que descartó, para que la revisión lo compruebe. Un supuesto que falta en la lista cuenta como hallazgo. Cada proyecto puede ajustar en un archivo propio lo que delega, como las dependencias que el agente puede agregar sin preguntar, pero solo para sumar fronteras, nunca para quitarlas. Así, la persona no pasa el día aprobando decisiones sueltas, que es la forma más rápida de acabar aprobando sin leer.

4. Controles que fallan solos

La norma tiene 20 reglas que no se negocian, y cada una declara tres cosas: la regla, dónde está escrita y qué mecanismo la hace cumplir, con un estado honesto: falla sola, parcial o pendiente.

Los mecanismos más baratos son los que más protegen. Cinco hooks revisan cada acción del agente antes de que ocurra:

Hook Qué impide
Modo de operación Comandos catastróficos, empujar a ramas desplegables, integrar o desplegar a mano
Secretos Leer archivos de entorno, llaves o secretos de la nube
Atestación Firmar commits o marcar la casilla de responsabilidad del PR
Pruebas Editar una prueba ya commiteada
Verificación al terminar Declarar una tarea terminada con la verificación local en rojo

Casi no cuestan nada en tiempo ni en tokens, y no dependen de que nadie se acuerde. Los hooks también tienen sus pruebas: una matriz de casos que deben permitirse y casos que deben bloquearse.

5. Una persona responde por cada cambio

La IA no firma, no atesta, no aprueba y no integra. El agente prepara el PR; la persona firma cada commit, marca la casilla que dice «revisé y respondo por esto» y lo integra. Un gate de la pipeline comprueba después del merge que todo eso ocurrió: que el commit venga de un PR, que esté firmado, que la atestación esté marcada y que el cambio no rebase el tamaño máximo.

Firmar e integrar son dos comandos que solo puede correr la persona: piden confirmación en su terminal y se niegan si los lanza un agente. El de integrar, además, se niega si algún check obligatorio no está en verde, si falta la casilla o si un commit no está firmado, e integra siempre con un merge commit para no borrar las firmas.

Lo desarrollamos en ¿Quién responde por el código que escribe la IA?.

6. Una sola cadena de despliegue

PR → CodePipeline → CodeBuild → despliegue, con dos gates humanos independientes: la revisión del PR (¿el cambio es correcto?) y la aprobación manual antes de producción (¿este artefacto va a producción ahora?). El artefacto se construye una vez, se etiqueta con su commit y es el mismo que pasa por cada etapa. Volver atrás es redesplegar el artefacto anterior, no construir uno nuevo.

Dos reglas que parecen menores y no lo son: las validaciones del PR no tienen credenciales de la nube, ni temporales; y después del merge, la nube controla todo: infraestructura, migraciones y rollback. Nadie opera producción desde su laptop.

7. Proceso proporcional a la ambigüedad y al riesgo

Este fue el gran cambio de la versión 4. Antes, toda tarea recorría el ciclo completo de agentes. Cada uno volvía a leer las mismas especificaciones para llegar a un plan que en una corrección pequeña ya era obvio. Ahora cada tarea se clasifica antes de empezar:

Nivel Tipo de trabajo Proceso
0, corrección Causa y solución entendidas Prueba en rojo si cambia comportamiento, cambio y verificación. Sin agentes
1, reglas claras Funcionalidad acotada, sin dudas de negocio Ficha corta, pruebas en rojo, código y verificación
2, ambigua Dudas de negocio, de alcance o de diseño Historia completa validada por una persona y ciclo completo
3, estructural Arquitectura, contratos, datos o migraciones Además, decisión de arquitectura escrita y plan en varios PRs

Dos reglas impiden que esto se convierta en una forma de saltarse el proceso:

  • El riesgo fija un piso. Si la tarea toca dinero, permisos, datos personales, seguridad o infraestructura, es nivel 2 como mínimo. Si toca contratos o datos persistentes, nivel 3.
  • Se sube, nunca se baja. El agente propone el nivel; la persona puede subirlo. Si a mitad del trabajo aparece una duda de negocio, el agente se detiene y reclasifica.

Lo que no cambia en ningún nivel: PR obligatorio, verificación en verde, pruebas congeladas, secretos fuera del alcance del agente, firma humana y la cadena de despliegue. El ahorro sale de la ceremonia, no de los controles.

8. Perfiles: una landing no es una plataforma

Esta pieza responde a una queja justa: un sitio de contenido no debería cargar con lo mismo que una plataforma con pagos.

Perfil Qué es
S, sitio Landing o sitio de contenido sin backend propio
A, aplicación Pocas piezas desplegables: sitio, panel, API, una base de datos
P, plataforma Varios servicios, eventos, varias aplicaciones o equipos
+R, regulado Se suma a cualquiera: pagos, salud, datos sensibles o clientes enterprise

El perfil se elige con un cuestionario de seis ejes (componentes, datos y dinero, usuarios, presupuesto, equipo y vida esperada) y gana el eje más alto. Lo propone el agente y lo confirma una persona.

Dos garantías lo hacen seguro. Hay un núcleo que ningún perfil omite: la cadena de despliegue, los controles del agente, la responsabilidad humana, la política de idiomas y los cinco hooks. Y el perfil solo sube: el validador busca señales de un perfil mayor, como migraciones en un sitio o eventos en una aplicación, y falla si las encuentra.

9. Una sola persona o un equipo: el mismo marco

El marco funciona igual con un equipo de desarrollo que con una sola persona. Lo único que cambia es quién hace la segunda revisión; firma, atestación, pruebas, verificación y cadena de despliegue son idénticas en los dos casos.

Equipo Una sola persona
Quién escribe el cambio Una persona con sus agentes Una persona con sus agentes
Segunda revisión Otra persona aprueba el último commit; en riesgo alto, dos aprobaciones. El autor nunca se aprueba a sí mismo Un agente revisor independiente revisa el último commit y el autor da una confirmación final explícita
Cambios al propio sistema de control Revisión de otra persona Espera obligatoria desde el último cambio, para revisar en frío
Firma, atestación, pruebas y despliegue Iguales Iguales

El modo de una sola persona viene apagado en todo proyecto nuevo: activarlo es una decisión explícita del primer día. Y se apaga solo en cuanto otra persona recibe permiso de escritura en el repositorio. No hay que acordarse de desactivarlo: el día que entra la segunda persona, el proyecto pasa a funcionar como equipo.

Esto importa para adoptar el marco. Una empresa pequeña puede empezar con una persona y agentes, con los mismos controles que tendrá cuando crezca, y el paso a equipo no exige rehacer nada.

10. El ritmo lo marca quien revisa

La última pieza vuelve a la premisa. Con agentes, generar PRs es casi gratis; revisarlos no. Si nada lo frena, la cola de revisión crece más rápido de lo que una persona puede leer, y la revisión se vuelve un trámite.

Por eso hay un límite de trabajo en curso: tres PRs abiertos por persona, contando los de los agentes que lanzó y los borradores. El agente lo comprueba antes de empezar una tarea nueva, no al abrir el PR. Si el límite está alcanzado, no empieza otra: atiende los comentarios de revisión, corrige los checks en rojo y, si no queda nada que hacer, le entrega a la persona la lista de lo que espera por ella. Solo un incidente que bloquea producción pasa el límite, por uno, y eso lo declara la persona, no el agente.

El control falla abierto: si el propio contador falla, avisa y deja seguir. Su función es marcar el ritmo, no convertirse en otro punto de bloqueo.

Cómo construir el suyo

Si su organización quiere un SDD propio, este es el orden que seguiríamos sabiendo lo que sabemos hoy:

  1. Empiece por la premisa, no por las carpetas. Escriba qué problema resuelve el marco. El nuestro es «validar es el cuello de botella»; cada pieza se justifica contra eso.
  2. Dibuje su modelo y asigne un dueño a cada pilar. Un pilar sin dueño es una brecha, y se nota en la primera auditoría.
  3. Escriba la lista corta de lo que no se negocia. Una regla por línea, con su fuente y su mecanismo. Marque con honestidad cuáles fallan solas y cuáles todavía dependen de una persona. Si una regla no está en la lista, es una guía, no una norma.
  4. Convierta reglas en mecanismos, empezando por los baratos. Un hook que bloquea leer secretos vale más que una política que lo prohíbe. La ceremonia de agentes es lo caro; los controles, no.
  5. Haga verificable la trazabilidad, con trinquete. Así puede adoptar el marco con deuda existente sin congelar el trabajo, y la deuda solo baja.
  6. Separe norma de proyecto y versione la norma. Con versiones semánticas y una guía de migración por versión mayor. Las desviaciones se escriben.
  7. Ponga a una persona con nombre detrás de cada cambio. La IA puede preparar todo, pero alguien firma y responde. Decida desde el principio cómo será la segunda revisión si hoy son una sola persona, y que el paso a equipo ocurra solo, sin rediseñar el proceso.
  8. Haga el proceso proporcional desde el primer día. Nosotros lo agregamos después, y en el camino pagamos ceremonia que no compraba calidad.
  9. Limite el trabajo en curso. Ponga un tope de PRs abiertos por persona antes de que la cola de revisión lo ponga por usted.
  10. Mida. Tamaño de PR, tiempo de entrega, retrabajo y defectos que llegan a producción. Sin métricas no sabe si está mejor o solo más rápido.

Lo que salió mal en el camino

  • La ceremonia uniforme era cara. El ciclo completo de agentes para cada tarea consumía tiempo y tokens sin mejorar las correcciones pequeñas. De ahí salió el proceso proporcional.
  • Doce checks eran demasiados. En la versión 4.0 los agrupamos en tres, con los mismos controles. Un PR de solo documentación pasó de unos quince trabajos de CI a cinco.
  • Los ejemplos se colaban en los proyectos. Hasta que separamos norma, hueco y ejemplo.
  • El límite de tamaño era demasiado estricto. Empezamos con 400 líneas de código por PR. y las pruebas contaban. Con pruebas primero, las pruebas eran la mitad del cambio: el límite castigaba justo lo que queríamos fomentar. Hoy son 1 500 sin contar pruebas, que se muestran aparte y se revisan primero.
  • Integrar con un botón saltaba los controles. Un mismo día se integraron siete PRs con algún check en rojo, desde botones de la interfaz que no esperan nada. De ahí salió el comando de integrar que se niega con checks en rojo.
  • Los controles van un paso detrás de los incidentes. Varios nacieron de un problema real, como contamos en el artículo del mantenedor único.

Qué está implementado y qué no

Pieza Estado
Trazabilidad verificada por máquina con trinquete Implementado
Hooks del agente con su matriz de pruebas Implementado
Firma y atestación humana comprobadas en la pipeline Implementado
Firmar e integrar con comandos que solo corre la persona Implementado
Proceso proporcional y perfiles de proyecto Implementado en el marco; cada proyecto lo adopta al migrar de versión
Autonomía delegada: el agente decide dentro de la rama y la persona en las fronteras Implementado en el marco; falta medir cuántas pausas ahorra
Límite de trabajo en curso: tres PRs abiertos por persona Implementado en el marco
Segunda mirada según el nivel y un PR único para varias correcciones pequeñas Pendiente
Modo de una sola persona Implementado. Nuestro propio repositorio opera así; el control que exige aprobación de otra persona queda en modo de aviso hasta enero de 2027
Verificación automática de textos sin traducir Pendiente

Lo que este artículo no afirma

  • No afirma que este sea el único SDD correcto. Es el que funciona para nuestro tamaño y nuestro stack, y cambia cada pocas semanas.
  • No afirma que los mecanismos sustituyan al juicio. Garantizan que se siguió el proceso; si el cambio es el correcto lo sigue decidiendo una persona.
  • No afirma que el marco esté terminado. La tabla anterior lo dice: hay piezas pendientes.

Fuentes

CompartirLinkedInXWhatsApp