Cómo sincronizar especificaciones, pruebas y código en el desarrollo
DominicodeEl Triángulo del Desarrollo Dirigido por Especificaciones: cómo evitar gestionar un proceso de programación que superó la capacidad de manejo de un solo hombre. Ni siquiera de un equipo; de un solo hombre..
Tiempo estimado de lectura: 5 min
- Ideas clave:
- El triángulo fundamental: especificación, tests y código deben mantenerse sincronizados.
- Los agentes aceleran implementación pero introducen decisiones trazables que deben registrarse.
- Herramientas como Plum extraen decisiones de diffs y traces para actualizar la spec y generar artefactos auditable.
- Procesos claros (captura de traces, aprobación humana, sync en CI) son necesarios para evitar deuda técnica acelerada.
El triángulo es simple y brutal: especificación, tests y código. Si uno se despega, el proyecto se rompe. So welcome: este artículo explica por qué el Spec‑Driven Development dejó de ser una ecuación lineal y cómo convertir ese triángulo en una práctica gobernable cuando agentes de IA escriben código.
Resumen rápido (lectores con prisa)
Qué es: Un enfoque que trata a la especificación, la suite de tests y el código como un triángulo que debe permanecer sincronizado.
Cuándo usarlo: Cuando agentes (LLMs/automations) o equipos múltiples generan cambios rápidos y necesitas trazabilidad.
Por qué importa: Para evitar deuda técnica acelerada y pérdida de intención por decisiones no documentadas.
Cómo funciona (resumen): Captura diffs y traces, extrae decisiones, confirma con humanos y sincroniza spec↔tests↔código.
El triángulo: Spec, Tests, Código — So welcome: por qué no basta con una spec
So welcome: si piensas que subir una spec y soltar agentes en ella es todo lo que hace falta, estás confundiendo velocidad con control. La spec define qué debe pasar. Los tests validan. El código implementa y descubre cosas. Pero la implementación introduce decisiones —humanas y de IA— que permanecen en los traces. Si no capturas esas decisiones, la spec se queda atrás y el sistema deriva. Resultado: managing a coding process that grew beyond one man’s ability to manage. Not even a team, one man.
¿Por qué esto importa hoy?
- Porque los agentes aceleran la implementación.
- Porque la implementación revela ambigüedades que la spec no anticipó.
- Porque los hotfixes y cambios urgentes suelen entrar directo al código y no a la spec.
Si no sincronizas, la velocidad se vuelve deuda técnica exponencial.
Señales que te indican que el triángulo está roto
- Commits frecuentes sin cambios en la spec.
- Pull requests que corrigen tests porque la spec no reflejaba decisiones recientes.
- Conversaciones largas con el agente donde se tomaron decisiones y nadie las documentó.
- Cobertura de tests alta en líneas, baja en intención (las pruebas no cubren los requisitos del producto).
Estas señales son tangibles. Úsalas. Git te cuenta qué cambió. Los traces de los agentes (chats, prompts, respuestas) contienen las decisiones. Los tests te dicen qué se ejecuta. Cruza esas fuentes y tendrás diagnóstico.
Plum — la plomada que mide la verticalidad del triángulo
No es teoría: existen herramientas prácticas. Plum (sí, como plomada) busca las decisiones en los diffs y en los traces y las convierte en artefactos verificables. Flujo resumido:
Plum: Flujo resumido
- Ejecutas commit.
- Plum lee los diffs y analiza los traces del agente.
- Extrae decisiones, las dedupea y te pide aprobación.
- Actualiza la spec (Markdown) según lo aprobado.
- Ejecuta sync y te muestra brechas spec↔tests↔código.
Genera además un archivo .jsonl con el historial de decisiones: pregunta, decisión, autor (humano/LLM), rama, timestamps. Eso pasa de “intención perdida en Slack” a “artefacto auditable en el repo”.
Plum: Instalación mínima
Instalación mínima: pip install plum-dev. (Limitación actual: integrado con pytest; funciona mejor cuando la spec está por delante del código.)
Prácticas para mantener el triángulo en sincronía
- Escribe la spec como un contrato de comportamiento, no como un manifiesto aspiracional. Casos de borde incluidos.
- Prioriza la suite de tests como activo estratégico: invierte en pruebas que describan la intención, no solo en asserts unitarios.
- Trata los traces de agente como código: captúralos, régistralos y asócialos a commits.
- En cada PR generado por agente: exige la checklist de decisiones aprobadas y la actualización del spec.
- Añade pruebas de invariantes sistémicas (property tests) que detecten regresiones causadas por cambios locales.
- Diseña módulos con contratos estables para permitir paralelismo de agentes sin colisiones.
Qué no esperar de los agentes (y por qué necesitas humanos
- No esperes que un LLM mantenga la visión de producto a largo plazo. Puede sugerir cambios documentales, pero la validación de negocio es humana.
- No esperes que arreglen deuda técnica sistémica solos. Pueden parchar, pero no rediseñar la arquitectura sin dirección.
- No esperes que la spec se actualice mágicamente: necesita decisiones aprobadas y trazables.
Checklist rápido para equipos que van a integrar agentes
- Tener specs en Markdown rastreables en repo.
- Tener suite de tests ejecutable en CI (pytest u otro).
- Integrar captura de traces de agentes (logs/JSON).
- Añadir herramienta de reconciliación (ej. Plum) en el pipeline local/CI.
- Forzar aprobación humana de decisiones extraídas antes de merge.
- Ejecutar sync spec↔tests↔código en cada PR.
Cierre (acción clara)
Si tu equipo ya usa agentes y no tiene un proceso de reconciliación entre spec, tests y código, estás acelerando la creación de un legado ilegible. Haz esto hoy: instala plum‑dev, apunta la herramienta a tu spec y a tus tests, y corre plum sync en tu CI. Si no puedes hacerlo aún, al menos comienza a registrar las decisiones en cada PR. No es glamour. Es gobernanza. Y sin eso, la velocidad que prometen los agentes solo te dará más problemas.
Haz clic aquí para empezar: pip install plum-dev y corre plum init en un repo con spec y pytest.
Para equipos que integran agentes y workflows de automatización, una continuación natural es explorar recursos y prácticas en Dominicode Labs, donde se agrupan experimentos y herramientas relacionadas con reconciliación de specs, capture de traces y pipelines de pruebas.
FAQ
- ¿Qué es el “triángulo” en Spec‑Driven Development?
- ¿Por qué los agentes rompen la sincronía entre spec, tests y código?
- ¿Qué hace Plum exactamente?
- ¿Cómo debo tratar los traces de agentes?
- ¿Qué requisitos mínimos necesito para integrar este flujo?
- ¿Quién debe aprobar las decisiones extraídas por herramientas automatizadas?
¿Qué es el “triángulo” en Spec‑Driven Development?
Es la idea de que especificación, tests y código forman un conjunto interdependiente. Si cualquiera de los tres se desincroniza, el proyecto corre riesgo de perder intención y acumular deuda técnica.
¿Por qué los agentes rompen la sincronía entre spec, tests y código?
Porque aceleran la implementación y toman decisiones durante el desarrollo (en prompts, chats, respuestas) que a menudo no quedan reflejadas en la spec ni en los tests, creando discrepancias trazables en diffs y commits.
¿Qué hace Plum exactamente?
Plum analiza diffs y traces de agentes, extrae decisiones, las dedupea, solicita aprobación y actualiza la spec en Markdown. También genera un archivo .jsonl con el historial de decisiones para auditoría.
¿Cómo debo tratar los traces de agentes?
Captúralos y regístralos como artefactos vinculados a commits; trátalos como código: deben estar versionados, asociados a PRs y revisados por humanos para extraer decisiones verificables.
¿Qué requisitos mínimos necesito para integrar este flujo?
Specs en Markdown rastreables, suite de tests ejecutable en CI (por ejemplo pytest), captura de traces (logs/JSON) e integración de una herramienta de reconciliación en el pipeline.
¿Quién debe aprobar las decisiones extraídas por herramientas automatizadas?
Siempre un humano con responsabilidad de producto o arquitectura. Las herramientas extraen y proponen; la validación de negocio y la aprobación final deben ser humanas.