Cómo mantener la sincronización en arquitecturas con IA

Sincronización Arquitectónica: Código, Especificaciones y Agentes de IA

Tiempo estimado de lectura: 4 min

Sincronización Arquitectónica: Código, Especificaciones y Agentes de IA. Si un Product Manager cambia algo hoy, ¿el resto del sistema se adapta mañana? La respuesta habitual es no. Y con agentes de IA escribiendo código, ese desajuste ya no es un fallo aislado: es una bomba de tiempo.

El problema es simple y profundo: el código evoluciona en commits. Las specs siguen en un README. Los hotfixes saltan directo al trunk. Los agentes generan decisiones en chats y desaparecen con el log. Resultado: intención sin rastro, comportamiento sin documentación y deuda técnica que crece en silencio.

Resumen rápido (lectores con prisa)

La sincronización entre spec, tests y código es crítica cuando agentes de IA participan. Convierte decisiones efímeras en artefactos rastreables en el momento del commit. Usa aprobación humana para validar cambios que afectan gobernanza y negocio.

El Triángulo: Spec, Tests, Código

Piensa en spec, tests y código como los tres vértices de un triángulo. Tradicionalmente trabajábamos en una línea: spec → código → tests. Con IA esto falla. La implementación revela nuevas decisiones que deben volver a la spec y a los tests. Si no, todo se desincroniza.

El verdadero trabajo de ingeniería hoy no es escribir más código. Es mantener ese triángulo alineado. Si mejoras el vértice del código, la spec y las pruebas deben moverse al mismo tiempo. Si no lo hacen, la arquitectura entra en drifting y el proyecto se vuelve inmanejable.

Señales que indican desincronización

• Commits que no referencian cambios en la spec.
• PRs que pasan tests unitarios pero rompen invariantes de negocio.
• Conversaciones con agentes sin registro estructurado.
• Falta de trazabilidad entre decisión y autoría.

Si reconoces cualquiera de estas, ya estás en modo emergencia controlada.

Plum: la plomada para decisiones

Plum es la herramienta que propone convertir decisiones efímeras en artefactos rastreables. No es un generador de código; es una plomada digital que alinea intención y ejecución.

Cómo funciona, en cuatro pasos

1. Al hacer commit, Plum revisa los diffs y los traces del agente.
2. Extrae decisiones técnicas (qué se decidió, por qué).
3. Presenta esas decisiones para aprobación humana.
4. Si las apruebas, actualiza la spec y reporta gaps entre spec, tests y código.

Plum genera además un archivo .jsonl con cada decisión: la pregunta, la respuesta, quién la aprobó y en qué rama quedó. Eso convierte la intención en un artefacto auditable.

Por qué eso importa para equipos reales

• Auditabilidad: Ya no dependes del recuerdo del autor del commit.
• Gobernanza: Puedes diferenciar decisiones humanas de sugerencias de un LLM.
• Recuperabilidad: Si un PM cambia una regla, puedes medir el impacto y forzar actualizaciones en spec/tests.
• Escalabilidad: En equipos con múltiples agentes o muchos desarrolladores, reduce choques de integración.

Limitaciones prácticas hoy

• Plum, en su versión inicial, está acoplado a pytest para análisis de coverage. Si tu stack usa otro runner, la integración requiere trabajo.
• Funciona mejor cuando la spec va por delante del código. Backfilling de specs desde bases legacy masivas sigue siendo difícil.
• Los LLMs pueden sugerir decisiones razonables pero sin visión de negocio a largo plazo. La aprobación humana no es opcional.

Patrón operativo recomendado

1. Escribe spec antes de generar código. Hazla lo más concreta posible.
2. Cubre casos límite en tests automáticos. No confíes en el “lo arreglamos después”.
3. Usa Plum o una herramienta equivalente para capturar decisiones en el momento del commit.
4. Ejecuta un pipeline de sync: spec ↔ tests ↔ código. Fallas: bloqueo del merge hasta que todo esté alineado.
5. Mantén el .jsonl como fuente de verdad para auditorías y retroalimentación del producto.

Casos prácticos y referencias

Los equipos que han escalado Spec-Driven Development reutilizan suites de tests maduras (CPython, Bash). Ejemplos relevantes:

• Repositorios y tests de CPython
• Experimentos de Anthropic sobre agentes y compiladores
• Proyectos de Vercel con reimplementaciones instrumentadas

No es trivial. Requiere inversión en especificaciones y disciplina en procesos. Pero sin eso, delegar en agentes solo acelera la creación de un monolito incomprensible.

Cierre con criterio

Si quieres que un cambio de producto active el resto del sistema de forma fiable, no te obsesiones con generar más código. Obsesiónate con capturar decisiones. Haz que tus specs sean artefactos vivos. Instrumenta los traces de los agentes. Automatiza la sincronía. Convierte la intención en datos auditable.

Instala la plomada. Pruébala en una rama pequeña. Verás cómo las discusiones pasan de “qué falló” a “qué decidimos y por qué”. Esa es la arquitectura que realmente escala cuando la IA entra en la ecuación.

Dominicode Labs

Para equipos interesados en experimentar con patrones de sincronización y captura de decisiones, Dominicode Labs ofrece recursos y experimentos relacionados que pueden servir como continuación lógica a este enfoque.

FAQ

• ¿Qué es la desincronización arquitectónica?
• ¿Qué hace Plum?
• ¿Cómo integrar esto en mi pipeline?
• Limitaciones al usar Plum
• ¿Qué conservar del proceso?
• ¿Qué hago si detecto deuda técnica por agentes?

¿Qué es la desincronización arquitectónica?

La desincronización ocurre cuando spec, tests y código divergen: decisiones implementadas no reflejadas en la spec o tests, cambios en tests que no documentan intención, o commits sin trazabilidad. Resulta en comportamiento no documentado y deuda técnica creciente.

¿Qué hace Plum?

Plum revisa diffs y traces del agente al hacer commit, extrae decisiones técnicas, las presenta para aprobación humana y, si se aprueban, actualiza la spec y reporta gaps entre spec, tests y código. Además genera un archivo .jsonl con registro auditable de cada decisión.

¿Cómo integrar esto en mi pipeline?

Incorpora la captura de decisiones en el paso de commit: ejecutar revisión automática de diffs y traces, bloquear merges si el sync falla, y mantener el registro .jsonl como fuente de verdad. Preferible integración con runners de tests compatibles (ej. pytest para la versión inicial de Plum).

Limitaciones al usar Plum

En su versión inicial está acoplado a pytest para análisis de coverage; la integración con otros runners requiere trabajo. Funciona mejor con specs que preceden al código y requiere aprobación humana para decisiones de negocio.

¿Qué conservar del proceso?

Conserva la disciplina de escribir specs antes de código, cubrir casos límite en tests, capturar decisiones en cada commit y mantener el .jsonl como registro auditable.

¿Qué hago si detecto deuda técnica por agentes?

Identifica los commits o decisiones sin trazabilidad, prioriza backfilling de specs y tests para las áreas críticas, y aplica bloqueo de merges hasta que el triángulo spec‑tests‑código vuelva a alinearse.