Podcast: Adiós al código espagueti, cómo SDD-Harness pone orden al desarrollo con IA

El Caos del Desarrollo Agéntico no Controlado

El desarrollo tradicional con IA suele basarse en el "ensayo y error" directo sobre el código. El programador le pide cambios al agente, este modifica los archivos de forma destructiva y, si algo falla, se inicia un bucle de correcciones ciegas.

SDD-Harness detiene este comportamiento obligando a los agentes a operar bajo un marco de ingeniería riguroso. En lugar de permitir que la IA improvise, el kit establece un flujo donde el diseño de software es el verdadero conductor del desarrollo, asegurando que cada cambio sea predecible, testeable y completamente auditable.

La Anatomía de un Ciclo SDD: Los 7 Agentes Especializados

Para garantizar que el software se construya con rigor, el kit organiza el trabajo en ciclos iterativos liderados por un equipo de 7 agentes agénticos especializados que actúan en una secuencia ordenada de pasos:

1. sdd-orchestrator: El director de orquesta. Recibe la solicitud del usuario, evalúa la viabilidad, inicializa el ciclo de desarrollo y coordina al resto del equipo.
2. sdd-functional: Analiza la especificación desde la perspectiva del negocio, definiendo las historias de usuario y los criterios de aceptación en un archivo functional.md.
3. sdd-planner: Traduce los requerimientos funcionales en un backlog técnico de tareas atómicas estructurado en tasks.json.
4. sdd-architect: Define los contratos de API, el modelo de datos y los diagramas de secuencia antes de codificar, asegurando la consistencia en api.json.
5. Implementadores (Backend / Frontend): Agentes dedicados puramente a la codificación. No pueden improvisar; su único trabajo es escribir código que cumpla de forma exacta con los contratos del arquitecto y el backlog del planner.
6. sdd-reviewer: El inspector de calidad. Realiza análisis estático, corre tests, valida esquemas JSON y calcula la telemetría de tokens del ciclo antes de autorizar el cierre.
7. sdd-steward: El conserje del kit. Opera fuera del ciclo de software, encargándose de las tareas administrativas, la salud general del entorno, la actualización de dependencias y el diagnóstico del repositorio.

Los Tres Modos de Acoplamiento (Integración Cero Fricción)

Uno de los principales desafíos al adoptar un framework es la fricción en la infraestructura existente. SDD-Harness se adapta a cualquier topología de proyecto mediante tres modos de inicialización ejecutados con el comando harness init:

• Nx Monorepo: Diseñado para arquitecturas a escala empresarial que administran múltiples aplicaciones y librerías de código compartido bajo una misma infraestructura modular.
• Standalone: Ideal para aplicaciones independientes, estructurando el arnés directamente en la raíz de un repositorio único de manera ágil.
• Configure SDD (Legacy/Existente): A través de harness configure sdd, el kit de gobernanza se inyecta en un desarrollo ya existente sin alterar una sola línea de código de tu aplicación. El arnés se encapsula en la carpeta /sdd y los agentes heredan y respetan las tecnologías y patrones que ya venías utilizando.

Los 4 Gates de Gobernanza: El Escudo de Calidad

La disciplina del kit se mantiene gracias a cuatro barreras de calidad automatizadas (Governance Gates) que validan cada etapa del desarrollo:

1. SPEC GATE (El Contrato de Diseño)

Antes de que un agente pueda tocar un archivo de código, este checkpoint verifica de forma estricta una lista de 10 puntos de control de diseño. Si falta algún documento del ciclo (como el backlog técnico en tasks.json o la aprobación manual del desarrollador), el desarrollo se bloquea inmediatamente.

2. CONTEXTO GATE (Adiós a los Conflictos de Fusión)

En entornos donde múltiples desarrolladores o agentes trabajan en paralelo, los conflictos de código son constantes. El Contexto Gate obliga a la IA a documentar sus cambios mediante fragmentos de contexto incrementales y aditivos en formato Markdown (sdd/context/.../updates/). Estos archivos se asocian directamente al ciclo de la especificación activa, evitando la sobreescritura destructiva de contextos globales.

3. MEMORIA GATE (Aprendizaje Continuo)

Cada ciclo de desarrollo genera aprendizajes técnicos. El Memoria Gate captura estas lecciones y las registra en bitácoras de sesión (memory/journal/) que luego se destilan en un archivo centralizado de lecciones aprendidas. De este modo, los agentes que inicien nuevas tareas leerán esta memoria compartida y jamás cometerán el mismo error técnico dos veces.

4. FIX GATE (El Bypass Controlado)

Cuando surge un problema crítico en producción, pasar por el flujo de diseño de los 7 agentes puede ralentizar la solución. El FIX GATE es un protocolo ágil diseñado para registrar arreglos rápidos bajo prefijos de severidad técnica específicos:

• [HOTFIX]: Para incidentes críticos que bloquean producción (Severidad Alta).
• [BUGFIX]: Para errores confirmados en entornos de prueba (Severidad Media).
• [FIX]: Para correcciones generales.
• [IMPROVEMENT]: Para mejoras menores de rendimiento o interfaz (Severidad Baja).

Este bypass tiene un límite estricto de escala: si el cambio afecta a más de 5 archivos o altera el contrato de API central en api.json, el sistema bloquea el bypass y exige iniciar un ciclo de especificación estándar. Todo fix queda auditado cronológicamente en el índice sdd/fixes.json.

Telemetría Financiera y el Visor de Documentación Local

Para los líderes de tecnología (CTOs) y Project Managers, la mayor ventaja de SDD-Harness radica en su transparencia. Al ejecutar:

pnpm sdd:docs

Se despliega un visor de documentación interactivo, bilingüe y 100% offline construido puramente en JS vanilla. El visor realiza un sondeo silencioso cada 4 segundos, actualizando el estado de tus tareas, ciclos y fixes en tiempo real sin recargar la página ni perder tu posición de scroll. Su característica estrella es la capa de telemetría de costos. Al cruzar los consumos de tokens registrados por el agente sdd-reviewer con las tarifas por millón de tokens configuradas en sdd/pricing.json (estructuradas con namespaces de proveedores multimodelo, por ejemplo, claude/sonnet o gemini/pro), el visor genera gráficos financieros interactivos. Estos gráficos contrastan de manera realista el costo agéntico real frente al costo tradicional estimado en base a las horas de desarrollo humano estimadas en tu backlog, permitiéndote auditar el retorno de inversión (ROI) de tu equipo de IA en tiempo real.

El Viaje de Hermes: De la Idea al Backlog

Como broche de oro para el flujo creativo, el kit incluye el flujo Hermes (harness idea). Al invocarlo, el desarrollador puede plasmar una idea de negocio en lenguaje natural. El sistema (apoyado por la skill sdd-hermes y el asistente sdd-steward) analizará la viabilidad del concepto, propondrá un stack técnico óptimo, estructurará el backlog inicial y dará luz verde al ciclo SDD bajo la gobernanza estricta del framework. Con SDD-Harness, el desarrollo asistido por IA deja de ser una caja negra impredecible y se convierte en lo que siempre debió ser: una línea de ensamblaje de software disciplinada, transparente y de altísima calidad.