Stop AI code sprawl before it destroys your software design

While AI code generators help teams ship faster than ever, that speed brings a hidden killer: Comprehension Debt. As soon as an AI produces functionally correct code that violates your domain boundaries, the team loses its mental model of the system. Here, I’ll show how to switch from passive documentation to Executable Architecture using Python-based testing tools like pytest-archon and CI/CD pipelines.

The most dangerous thing an AI coding agent can do is generate code that works.

If a junior developer writes poor code, it breaks the build or staging environment. The team catches it, reverts it, and discusses it. But if an AI coding agent produces 500 lines of functionally correct and bug-free code that subtly violates your system’s boundaries, it merges without issues.

“The most dangerous thing an AI coding agent can do is generate code that works.”

Gradually, the AI connects your billing service to the user authentication component. It gives your presentation layer database access. It wires dependencies in a way that works but violates the design assumptions of human developers who maintain the system.

Technical debt has given way to something far more pressing — Comprehension Debt: the growing gap between how fast code gets written and how well the human team understands its architecture. The problem isn’t messy logic; it’s a lost mental model. That happens when the team no longer knows why the codebase exists.

If you view AI as a mere machine for faster typing, the architecture has started to degrade. To endure in the era of AI-driven coding, architecture enforcement must shift — from documentation to Executable Architecture.

The illusion of documentation

The accepted guidance for AI-assisted development is: “Make better documentation so the AI understands the rules.”

This is a fallacy. Documentation will become obsolete. If your AI agent finds an easier way to reach its objectives by skipping a service layer, it will take it. And since human reviewers increasingly struggle to review thousands of AI-generated pull requests, these detours slip through code review undetected.

“You cannot depend on human beings to detect architectural drift. You have to trust the CI/CD pipeline.”

You cannot depend on human beings to detect architectural drift. You have to trust the CI/CD pipeline.

If your architectural boundaries matter, check them the same way you’d check any business requirement. We need fitness functions that fail the build when an AI agent violates a boundary condition.

Introducing executable architecture in Python

In the Java ecosystem, tools such as ArchUnit have traditionally enforced architectural boundaries. In Python, tools like pytest-archon do the same job.

Consider a concrete example. You’ve built a modular monolith for an e-commerce application and established strict boundaries:

The Billing domain should never import from the Shipping domain.

Domain model code should not import from infrastructure (AWS SDK, SQLAlchemy, etc.).

You task the AI agent with adding shipping cost calculations based on the user’s billing tier. Without thinking about the architecture, the AI imports the Shipping Calculator directly into the billing service. Test passes. The application works. But the architecture fails.

Here’s how pytest-archon prevents the agent from doing that.

Step 1: Install the dependency

First, install the architectural testing dependency.

Python pip install pytest-archon

Step 2: Define the architectural rules as tests

Instead of finding the rules on the Wiki page, we define them as pytest features. We create a test_architecture.py file in the test folder.

Python from pytest_archon import archrule def test_billing_is_isolated_from_shipping(): """ Ensure the billing module never imports shipping logic. This prevents the AI from creating tight coupling between distinct domains. """ ( 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(): """ Ensure domain models only depend on standard libraries or pydantic. Prevents the AI from leaking infrastructure (DBs, APIs) into the core logic. """ ( archrule("pure_domain", comment="Domain models must not import infrastructure") .match("ecommerce.*.models") .should_not_import("sqlalchemy*") .should_not_import("boto3*") .check("ecommerce") )

Step 3: Close the agent feedback loop

Then, once the AI agent pushes its pull request, pytest runs automatically as part of the CI workflow. Regardless of how well the AI agent generates code that calculates the Shipping fee, the build will immediately fail with something similar to this:

text FAILED tests/test_architecture.py::test_billing_is_isolated_from_shipping - AssertionError: Rule 'billing_isolation' violated: ecommerce.billing.invoice imports ecommerce.shipping.calculator

A human reviewer doesn’t have to track down the entire import tree manually. Most importantly, the best engineering teams never rely on humans for this.

Once again, we feed the output of these failing pytest tests directly back into the AI agent’s context window using Aider or custom CI/CD scripts, and the AI can fix architectural problems without human help.

Strategies for avoiding Comprehension Debt

Running architectural tests alone is not enough. Here’s how to shield your team from Comprehension Debt:

1. Hard boundaries vs. soft conventions

AI agent obeys hard constraints but not soft suggestions. Get rid of sloppy folder-based architecture and establish clear module boundaries instead. Use tools like import-linter or pytest-archon to block forbidden imports with physical barriers. The path of least resistance must be the most architecturally sound.

2. Limit automated complexity

Well-defined APIs and boundaries are good, but not enough to let you off the hook for messy, complex implementation. If AI creates spaghetti code in your billing module, causing downtime from race conditions at 3 AM, a human engineer will still need to maintain and understand that codebase.

For this purpose, run architectural tests alongside cyclomatic complexity gatekeepers such as Ruff, Radon, or SonarQube as part of your CI pipeline. Set hard limits on complexity to force AI to decompose huge functions into smaller ones.

3. Examine the interfaces, not just the implementation

In code reviews of AI-generated PRs, the developer’s mind is a precious resource. Stop looking at each line, trying to decipher loops and variable assignments. Look at what changes the system from the outside. Instead, are there new dependencies? Did the PR expose new API endpoints? Did it change the data schema? If not, your mental model remains intact.

Conclusion

AI coders are very strong, but they have one big flaw — they are very pragmatic. The maintainability of your code doesn’t interest them — they care only about completing the task you assign them.

“AI coders are very strong, but they have one big flaw. They care only about completing the task you assign them.”

If you try to control your system design by relying on the human factor only, you will drown in Comprehension Debt sooner or later. It’s not a question of slowing down your AI implementation process— it’s a question of making your environment more resistant.

You don’t need to study every line of AI-generated code. You just need to create a cage for this AI.

The post Stop AI code sprawl before it destroys your software design appeared first on The New Stack.