pytest-archon: ejecuta tus reglas de arquitectura para frenar la deuda de comprensión

El problema actual no es que la IA escriba código mal compilado, sino que escriba código que funciona pero que viola las fronteras arquitectónicas de tu sistema. Cuando un agente de código genera 500 líneas que pasan los tests funcionales pero acoplan un servicio de facturación con autenticación de usuarios, el código se fusiona sin que nadie lo detecte. Esto crea lo que el autor denomina "Deuda de Comprensión": la brecha creciente entre la velocidad de escritura y la capacidad del equipo para entender cómo funciona el sistema.

De la documentación a la ejecución

La práctica habitual de "mejorar la documentación para que la IA entienda las reglas" es insuficiente. Los agentes de IA toman el camino de menor resistencia; si una capa de servicio es lenta o compleja de usar, la evitarán aunque la documentación lo prohíba. Como los revisores humanos tienen cada vez más dificultad para auditar miles de pull requests generados por IA, la deriva arquitectónica pasa desapercibida.

La alternativa propuesta es la Arquitectura Ejecutable. En el ecosistema Java, herramientas como ArchUnit han hecho esto durante años. Para Python, surge pytest-archon. En lugar de leer reglas en un wiki, se definen como pruebas pytest que fallan el build si se violan.

Un ejemplo concreto: en un monolito modular de comercio electrónico, se establece que el dominio billing nunca debe importar de shipping. El código de prueba se parece a esto:

from pytest_archon import archrule

def test_billing_is_isolated_from_shipping():
    (
        archrule("billing_isolation")
        .match("ecommerce.billing*")
        .should_not_import("ecommerce.shipping*")
        .check("ecommerce")
    )

Cuando el agente de IA intenta importar ecommerce.shipping.calculator dentro de billing.invoice, la prueba falla en el pipeline de CI/CD. El error es explícito: la regla se ha violado. Este mensaje de error retroalimenta al propio agente de IA (vía Aider o scripts de CI), permitiendo que corrija el import problemático sin intervención humana.

Estrategias para blindar el diseño

Instalar estas herramientas es solo el primer paso. Para que funcione, las fronteras deben ser duras, no convenciones suaves. Se deben eliminar las arquitecturas basadas solo en carpetas y establecer módulos con límites claros, usando import-linter o pytest-archon como barreras físicas. El camino de menor resistencia para la IA debe ser también el más correcto arquitectónicamente.

Además, hay que limitar la complejidad automatizada. Si la IA genera código espagueti dentro de un módulo, la prueba de arquitectura no lo detendrá si técnicamente respeta los imports. La deuda de comprensión no se elimina con tests de imports, sino con una combinación de fronteras estrictas y revisión de la complejidad interna, incluso cuando el código es generado automáticamente.