Archspec investigate: cómo los LLM detectan conflictos entre servicios antes de escribir código

Un desarrollador verificó si una LLM puede detectar conflictos entre servicios en la etapa de planificación — antes de la primera línea de código. La herramienta es archspec con contratos legibles por máquina `SERVICE_MAP.yaml`, la característica es la reasignación automática de tareas tras la negativa de un freelancer.

Dónde LLM pierde contexto entre servicios

En la primera parte del ciclo, el autor documentó un problema estructural del desarrollo asistido por LLM en sistemas de microservicios. Cada servicio individualmente, el modelo lo describe correctamente — pero cuando una característica pasa por múltiples servicios, el plan se desmorona. La razón: las reglas en los límites entre servicios — estados permitidos, orden de llamadas, restricciones en transiciones — no están registradas en un solo lugar.

Cada servicio se documenta localmente, en aislamiento. La LLM ve cada fragmento por separado, pero no ve el sistema en su conjunto. Los acuerdos entre servicios permanecen implícitos, y el modelo los pasa por alto.

La característica "reasignación de tareas tras negativa de freelancer" es una buena prueba precisamente porque toca múltiples servicios a la vez: cola de tareas, notificaciones, facturación, perfiles de ejecutores. Un error en cualquier transición rompe todo el flujo. Fue en esta característica que el plan falló por primera vez.

Contratos en lugar de Markdown en forma libre

La segunda parte del ciclo presentó archspec — una herramienta que genera un archivo `SERVICE_MAP.yaml` para cada servicio. Esto no es documentación en forma libre para humanos con descripciones narrativas, sino un contrato legible por máquina: restricciones explícitas, transiciones permitidas entre estados, dependencias entre servicios y requisitos de datos en cada transición. La diferencia es fundamental. Markdown en forma libre es texto que una LLM interpreta con suposiciones. `SERVICE_MAP.yaml` es datos estructurados que un modelo analiza de forma determinista. No hay lugar para "alucinaciones" sobre acuerdos implícitos. Elementos clave del contrato:

• Formatos explícitos de entrada y salida para cada servicio
• Transiciones permitidas entre estados de objetos de negocio
• Campos obligatorios para llamadas entre servicios
• Restricciones de lógica de negocio en los límites de servicios

Qué mostró /archspec:investigate

Las condiciones de prueba son estrictas: el mismo prompt, el mismo modelo (Claude Sonnet 4.6), la misma característica. La única diferencia — contratos legibles por máquina encima de `SERVICE_MAP.yaml` en lugar de texto en forma libre.

"El mismo prompt, el mismo modelo.

La pregunta es: ¿detectará el plan esos errores entre servicios antes de que se escriba código," — formula el autor la esencia del experimento.

Con contratos, el modelo detectó conflictos entre servicios ya en la etapa de planificación — exactamente los que la primera vez surgieron solo después de escribir el código. Formalizar límites le dio a la LLM contexto estructurado suficiente para transiciones correctas entre servicios antes de que se escriba la primera línea de implementación. Pero la herramienta tenía limitaciones.

Archspec investigate funciona exactamente tan bien como los contratos mismos sean precisos. Si `SERVICE_MAP.yaml` se queda atrás del código real — el modelo planifica desde un mapa desactualizado y vuelve a fallar.

La implementación en sí también fue verificada por separado contra el plan final: allí también se encontraron puntos donde el código "se desvió" de lo previsto — y esto es una parte honesta de la investigación.

Qué significa esto

El desarrollo orientado a especificaciones con LLM en microservicios funciona — pero requiere contratos explícitos legibles por máquina. Sin ellos, el modelo estructuralmente pierde contexto entre servicios: esto no es una cuestión de calidad del prompt o potencia del modelo. Archspec es una forma práctica de fijar este contexto, la herramienta está disponible en GitHub. La principal limitación: mantener `SERVICE_MAP.yaml` actualizado requiere esfuerzo manual — este es un paso separado que necesita integrarse en el proceso de desarrollo. Sin contratos actualizados, la herramienta crea falsa confianza en lugar de ayuda real.