Publiqué que SDD no funcionaba. Luego me tocó hacerlo funcionar.

Hace unas semanas publiqué un artículo cuestionando Spec Driven Development. Planteé preguntas incómodas sobre cuellos de botella, indeterminismo de los agentes, erosión de capacidades internas del equipo, y los incentivos sesgados de quienes venden estas herramientas. El artículo generó bastante conversación. Y entonces llegó el reto que, en retrospectiva, me merecía completamente.

“Eso que dijiste que no funciona, queremos implementarlo. Y eres responsable de hacerlo funcionar.”

Hermoso. Nada como que te sirvan una cucharada de tu propia medicina a temperatura ambiente. Mi trabajo es hacer que las cosas pasen, así que lo tomé como un reto profesional y personal. Me puse a investigar en serio (papers, no demos de diez minutos con un repositorio limpio que nunca ha visto producción en su vida). Lo que encontré cambió bastante mi perspectiva, no porque estuviera completamente equivocado, sino porque estaba criticando algo que nunca había implementado realmente.

Este artículo es el resultado de esa experiencia.

El diagnóstico era correcto. El paciente era otro.

En mi artículo anterior argumenté que el cuello de botella del SDD se trasladaba a quien escribe las especificaciones. Que necesitabas a tus perfiles más caros produciendo documentos detallados antes de que la IA pudiera hacer algo útil, y que en ese punto era más eficiente que esa misma gente escribiera directamente el código.

El argumento tiene un problema de base: asume que los desarrolladores escriben las specs manualmente.

No es así como funciona cuando está bien implementado. Los problemas que describí en mi artículo anterior son los problemas del vibe coding, que es básicamente pedirle al agente “implementa esta feature” y rezar para que el resultado sea coherente con el resto del sistema. No son los problemas del SDD con un sistema de gobernanza real. Yo estaba criticando las consecuencias de la ausencia de estructura, no las consecuencias de la metodología.

La diferencia entre vibe coding y SDD bien implementado no es de herramienta. No es de usar openspec o spec-kit y derivados. Es de arquitectura. Y esa distinción es la que la mayoría de los artículos sobre el tema siguen sin hacer.

Qué es el Agentic Governance Framework (y por qué SDD solo no alcanza)

El término “Agentic Governance” ya existe en la literatura técnica, pero en un sentido diferente: la mayoría de los frameworks actuales lo tratan como un problema de seguridad y compliance, controles sobre lo que los agentes pueden acceder o ejecutar en producción. Eso es importante, pero no es de lo que estoy hablando.

Lo que construí durante esta investigación es algo más específico: un Agentic Governance Framework (AGF) orientado al proceso de desarrollo de software. No es solo SDD. SDD describe cómo escribir especificaciones para que la IA genere código. El AGF define quién toma cada decisión, en qué momento, con qué información, y cómo queda registrada esa decisión antes de que se escriba una sola línea de código. SDD es una parte del AGF, no al revés.

La premisa central es simple: humanos gobiernan, IA desarrolla. El desarrollador deja de ser quien construye el sistema y pasa a ser quien gobierna el agente que construye el sistema. Ese cambio de rol no es cosmético. Tiene implicaciones concretas en cómo se organiza el trabajo, qué habilidades se necesitan, y cómo se distribuye la responsabilidad cuando algo sale mal.

El flujo de trabajo paso a paso

Lo que sigue es el proceso que logré hacer funcionar. Lo describo con el nivel de detalle que me hubiera gustado encontrar cuando empecé a investigar.

Paso 1: Foundation

Antes de una especificación, antes de una decisión de arquitectura, antes de hablar de tecnologías, existe un documento que responde tres preguntas: qué se va a construir, por qué, y qué se espera que logre. Le llamo foundation.md y vive en el repositorio, no en un slide que nadie va a volver a abrir.

El proceso no es que yo me siente a escribir ese documento. El agente conduce una conversación conmigo, haciendo las preguntas necesarias hasta tener suficiente contexto para generarlo. Yo doy una idea inicial (“quiero construir una herramienta CLI para gestionar plantillas de microservicios”). El agente pregunta, profundiza, cuestiona si lo que digo tiene sentido. Cuando la conversación termina, el agente escribe el documento. Yo reviso y apruebo.

Ese foundation es el ancla de todo lo que viene después. Cada decisión futura debe ser coherente con él.

Paso 2: Architecture Decision Records (ADRs)

Los ADRs no son una idea nueva. Son documentos que registran las decisiones de arquitectura de un proyecto: qué lenguaje se usa, qué framework, qué base de datos, qué patrones de diseño, y (lo más importante) por qué se eligió eso en lugar de las alternativas.

Lo que agrega el AGF es un flujo conversacional para generarlos. En lugar de que un arquitecto se siente solo a escribir un ADR, el proceso ocurre en tres momentos: primero una sesión de exploración donde el agente hace preguntas y puede cuestionarte si la decisión que estás tomando tiene sentido dado el foundation, luego la generación de un borrador que yo reviso e itero, y finalmente el registro formal del ADR aprobado en el repositorio.

La estructura de carpetas va tomando esta forma:

arch/
├── adrs/
│   ├── ADR-000-lenguaje-y-runtime.md
│   ├── ADR-001-arquitectura-en-capas.md
│   ├── ADR-002-inyeccion-de-dependencias.md
│   └── README.md
└── drafts/

El README.md funciona como índice. El agente tiene instrucciones explícitas de consultar ese índice antes de tomar cualquier decisión de implementación.

Paso 3: Agent Generated Decision Records (AGDRs)

Acá está el mecanismo que más me sorprendió durante mi proceso de experimentación, y que resuelve uno de los problemas más serios del vibe coding.

Durante la implementación, el agente inevitablemente va a encontrar situaciones donde no hay un criterio definido en los ADRs. Por ejemplo, el proyecto usa Go y tiene un ADR sobre convenciones de cómo construir un cliente para una API REST, pero aparece un caso de edge que el ADR no cubre. En vibe coding, el agente simplemente toma una decisión arbitraria, genera código, y sigue. Esa decisión queda enterrada en el código sin ninguna documentación, y la próxima vez que el agente enfrente una situación similar puede tomar una decisión diferente e inconsistente.

Con el AGF, el agente está instruido para hacer algo diferente: genera un documento (el AGDR) explicando qué quiere hacer y por qué, y hace una pausa. La implementación no avanza hasta que un humano toma una de tres decisiones: aprobar (el agente puede continuar), rechazar (el agente debe replantearse la decisión), o promover (la decisión es suficientemente importante para convertirse en un ADR formal que va a gobernar todo el proyecto de ahora en adelante).

arch/
├── adrs/          (decisiones aprobadas por humanos)
├── agdrs/         (decisiones generadas por el agente, pendientes de revisión)
└── drafts/

Esto hace que haya un responsable humano identificable para cada decisión significativa del proyecto. Cuando algo sale mal en producción, el trail de decisiones existe, es legible, y tiene un nombre asociado. Eso cambia completamente la dinámica de responsabilidad dentro del equipo.

Paso 4: Especificaciones (aquí entra el SDD clásico)

Recién en este punto empieza el SDD propiamente dicho. Por cada feature o cambio, el flujo pasa por tres momentos:

Exploración: el agente entra en modo de análisis. Hace preguntas sobre el cambio que se quiere implementar, lo examina desde múltiples ángulos, y puede señalar conflictos con decisiones de arquitectura existentes antes de que nadie haya escrito una sola línea de código.

Propuesta: el agente genera tres documentos. El spec.md describe qué se va a construir y qué comportamiento se espera. El design.md describe exactamente cómo se va a construir: qué archivos se van a modificar, qué archivos nuevos se van a crear, qué estructuras de datos se van a definir, con fragmentos de código ya escritos para las partes más complejas. El tasks.md descompone todo eso en pasos mecánicos y secuenciales.

Implementación: en una sesión completamente nueva (sin contexto residual de conversaciones anteriores), el agente lee la especificación aprobada y ejecuta. El diseño ya fue revisado y aprobado por un humano. El agente no necesita tomar decisiones creativas en esta fase, solo seguir instrucciones.

specs/
├── README.md
└── archive/
    ├── cmd-new/
    │   ├── spec.md
    │   ├── design.md
    │   └── tasks.md
    └── autenticacion-jwt/
        ├── spec.md
        ├── design.md
        └── tasks.md

Cuando la implementación está completa y verificada, la especificación se archiva. Cada feature completada tiene su historia documental completa.

Por qué esto resuelve el problema del code review que mencioné antes

En mi artículo anterior argumenté que revisar código ajeno es más difícil que escribirlo, y que ese sería el nuevo cuello de botella. Sigo pensando que eso es cierto para el vibe coding.

Con el AGF, yo no estoy revisando código. Estoy revisando el design.md antes de que se escriba una sola línea. Ese documento me dice exactamente qué archivos van a cambiar, qué estructuras nuevas van a aparecer, y el razonamiento detrás de cada decisión. Si ese diseño está alineado con los ADRs y tiene sentido para el problema que se está resolviendo, el código resultante va a ser correcto. Si no está bien, lo rechazo y refinamos el diseño, que es un documento de texto, no un diff de trescientas líneas en cinco archivos distintos.

El costo de corrección cae dramáticamente porque los errores se detectan en la fase más barata del proceso.

El repositorio no es solo código. Es una base de conocimiento institucional.

Esto es algo que no aparece en casi ninguna conversación sobre SDD y que creo que es uno de los argumentos más sólidos para adoptar este framework.

En Data Governance, los principios fundamentales son trazabilidad, ownership y auditabilidad: poder rastrear cada dato desde su origen, saber quién tomó qué decisión sobre él y cuándo, y poder auditarlo en cualquier punto del tiempo. Es exactamente lo que el AGF produce para las decisiones de arquitectura y desarrollo.

Cuando un desarrollador nuevo se incorpora al equipo, puede leer los ADRs y entender en una tarde por qué el sistema está construido como está, sin necesitar que nadie le cuente la historia oral del proyecto. Cuando algo falla en producción, el trail de decisiones existe y es legible. Cuando el equipo quiere evaluar si una tecnología tiene sentido, puede consultar el historial de decisiones similares tomadas en proyectos anteriores.

Y hay algo más que recién estoy empezando a explorar: toda esa data estructurada en markdown es perfectamente indexable. Una especificación de autenticación bien escrita en un proyecto es reutilizable en el siguiente. Los ADRs de un equipo pueden compartirse como biblioteca de patrones aprobados en toda la organización. Se puede construir un índice semántico sobre el historial completo de decisiones y tener un agente que responda preguntas sobre por qué el sistema funciona como funciona, sin necesidad de buscar manualmente. El repositorio deja de ser un lugar donde vive el código y pasa a ser una memoria institucional del equipo.

Los trade-offs honestos

No vine a vender nada, así que hay que ser directo sobre lo que este framework no es.

No es más rápido. Lo que un desarrollador con experiencia resuelve en cinco minutos escribiendo código, este flujo de trabajo puede hacer que le tome treinta. Para bugs menores o cambios triviales, el AGF puede ser pesado. Y sin embargo, no hay termino medio, para que esto funcione correctamente y se produzca un historial de decisiones consistente, no puede haber trabajo manual sobre el código. Todo debe pasar por el proceso definido de exploración, generación de diseño e iteraciones sobre especificaciones. El valor del framework crece con la complejidad del sistema y la longevidad del proyecto. Para un script descartable, es overkill.

Consume recursos de forma significativa. Las fases de exploración, generación de diseño e iteraciones sobre especificaciones gastan tokens. Mi límite de uso diario se alcanza todos los días. Es un costo operativo real que hay que presupuestar antes de decidir adoptar este enfoque. Ya estoy explorando formas de optimizar ese consumo, pero por ahora es lo que hay.

El riesgo de dependencia es real. Después de varias semanas trabajando con este flujo, volver al ciclo clásico de escribir código se siente pesado. El contraste de productividad es lo suficientemente grande como para que el equipo no quiera volver atrás. Eso es un riesgo que hay que gestionar conscientemente, especialmente si el contexto de la organización puede requerir operar con herramientas diferentes en el futuro.

Lo que sí da este framework, en cambio: un historial de decisiones auditado, documentación que se construye sola con cada iteración, y código cuya calidad mejora progresivamente porque el agente acumula contexto sobre el proyecto a través de los ADRs. Las primeras especificaciones generan código correcto. Las especificaciones de la décima iteración generan código correcto con comentarios ultra precisos y consistentes con las convenciones que el propio proyecto fue definiendo. Eso no pasa en el vibe coding; incluso me atrevería a decir que no pasa con equipos de desarrolladores humanos sin un proceso de capacitación y mentoría muy fuerte.

El verdadero valor del AGF no está en entregas más rápidas. De hecho, comparado con otros métodos que prometen velocidad inmediata, este framework es más lento al principio. Pero eso es por diseño.

Lo que sí promete es que, con el mismo esfuerzo durante la misma cantidad de tiempo, acabes entregando más valor. El código que sale en la semana uno es correcto. El código de la semana diez es correcto y mejora progresivamente en calidad porque el agente acumula contexto sobre el proyecto a través de los ADRs. Cada decisión de arquitectura documentada hace que las siguientes especificaciones sean más precisas, más coherentes, y requieran menos iteraciones.

Lo normal es que a medida que un proyecto envejece, se ralentiza: la deuda técnica se acumula, las decisiones pasadas generan rozamiento con las nuevas, y el onboarding de gente nueva se vuelve más costoso. Con el AGF, pasa lo opuesto. El proyecto se vuelve más estable porque las decisiones están bien definidas y documentadas. El rozamiento disminuye. Los nuevos desarrolladores (IA o Human) entienden el sistema en horas, no en meses. La productividad sigue subiendo incluso después de un año de desarrollo.

Velocidad inicial no es lo mismo que productividad sostenible. Este framework está diseñado para lo segundo.

Lo que esto cambia en el rol del desarrollador (y lo que no)

Esta es la parte más difícil de escribir porque todavía no tengo una respuesta completamente formada. Pero creo que es la parte más importante del artículo.

El trabajo sigue siendo el mismo en términos cognitivos: investigar, entender el dominio, tomar decisiones, asumir responsabilidad sobre los resultados. Pero la distribución del tiempo cambia radicalmente. La fase de implementación, que antes consumía la mayor parte del tiempo, ahora ocurre sin intervención humana directa. Lo que queda en manos del desarrollador es el gobierno del proceso: decidir qué se construye, bajo qué restricciones, con qué criterios de calidad, y aprobar cada decisión significativa antes de que se ejecute.

Eso requiere un perfil diferente al del desarrollador clásico. No se gobierna un agente de IA con intuición acumulada de años escribiendo sintaxis. Se gobierna con criterio arquitectónico, con capacidad de evaluar trade-offs, y con suficiente entendimiento de cómo funcionan los modelos como para diseñar instrucciones que produzcan comportamiento predecible y consistente.

Para los CTOs y líderes técnicos que están evaluando si adoptar IA en su proceso de desarrollo: la pregunta más importante no es si la IA puede generar código de calidad con buenas especificaciones (si puede). La pregunta es si tienen en el equipo personas con el criterio para gobernar ese proceso, no solo para escribir prompts, sino para tomar decisiones arquitectónicas con consecuencias reales, firmarlas, y asumir responsabilidad cuando algo falle.

Si la respuesta es sí, el AGF tiene sentido. Si la respuesta es “vamos a ver cómo le va al agente solo”, lo que van a tener es vibe coding con documentación decorativa. Y para eso ya hay suficientes consultoras cobrando tarifas de transformación digital.

Eso es todo lo que tengo por ahora. Los prompts, comandos, y estructura completa del framework los voy a publicar en un repositorio público cuando esté listo para compartirlo. Pero la metodología está acá, y si alguien quiere empezar a experimentar con estos principios antes de eso, ya tiene suficiente para arrancar.