Executable Architecture: Stopping AI‑Generated Code Sprawl in Python Projects

AI‑driven code generators have moved from occasional snippets to large, production‑ready contributions that can silently cross domain boundaries. The result is a new form of technical debt—comprehension debt—where the code works but the team’s mental model of the system erodes. Practitioners must replace static documentation with enforceable, test‑driven architecture to keep builds trustworthy and designs understandable.

Why Documentation No Longer Suffices

Traditional guidance suggests improving documentation so an AI can “understand” architectural rules. In practice, the AI will still seek the shortest path to a functional outcome, even if that path bypasses documented layers. Human reviewers, overwhelmed by the volume of AI‑generated pull requests, cannot reliably catch every boundary violation. Consequently, architectural drift becomes invisible until it accumulates into comprehension debt.

Executable Architecture with pytest-archon

In the Java world, ArchUnit provides runtime checks for architectural constraints. The Python ecosystem now offers a comparable tool, pytest-archon, which lets teams codify boundaries as test cases. The workflow is straightforward:

1. Install the package: pip install pytest-archon
2. Create a test module (e.g., test_architecture.py) that declares rules using the archrule builder.
3. Run the tests as part of the normal pytest suite.

A minimal rule set for a modular monolith might look like this:

from pytest_archon import archrule

def test_billing_is_isolated_from_shipping():
    (archrule("billing_isolation", comment="Billing must not know about shipping")
        .match("ecommerce.billing*")
        .should_not_import("ecommerce.shipping*")
        .check("ecommerce"))

def test_domain_models_are_pure():
    (archrule("pure_domain", comment="Domain models must not import infrastructure")
        .match("ecommerce.*.models")
        .should_not_import("sqlalchemy*")
        .should_not_import("boto3*")
        .check("ecommerce"))

When an AI agent adds a direct import from ecommerce.shipping.calculator into the billing module, the corresponding test fails, and the CI job aborts.

CI/CD Integration and Feedback Loop

Embedding the architectural tests into the CI pipeline turns them into fitness functions. A typical flow is:

• The AI agent opens a pull request.
• The CI runner executes pytest, including the pytest-archon suite.
• If a rule is violated, the build fails with an assertion message that pinpoints the offending import.
• The failure output is fed back to the AI’s context (e.g., via Aider or a custom script), allowing the agent to regenerate code that respects the declared boundaries.

This loop removes the need for manual architectural review and ensures that every merge satisfies both functional and structural requirements.

Related CloudNinjas coverage: DevOps.

What This Means For Practitioners

Teams that rely on AI‑assisted development should adopt the following practices:

1. Define hard architectural constraints as executable tests rather than prose.
2. Integrate those tests into every CI run so violations block merges automatically.
3. Configure the AI feedback channel to consume test failures and iterate without human intervention.
4. Periodically audit the rule set to keep it aligned with evolving domain boundaries.

By treating architecture as code, organizations can preserve the shared mental model, prevent comprehension debt, and keep AI‑generated contributions safe and maintainable.