How I Prevented Claude Code from Breaking My Architecture...

I spent the last few weeks building a production boilerplate for AI Agent and IoT systems. FastAPI, asyncpg, LangGraph, MQTT, pgvector — a complex stack with very specific architectural boundaries that cannot be violated.

The problem: I was using Claude Code and Cursor to accelerate development. And they are brilliant. But they are also completely agnostic to the architecture you have in your head.

Let me show you the kind of thing that happens without protection.

The Problem

My system has one critical rule: the IngestionService must never import SQLModel or SQLAlchemy. It's the hot path for IoT telemetry ingestion — asyncpg raw SQL only, zero ORM overhead. This separation is intentional and documented in 20 pages of ARCHITECTURE.md.

In a typical session, I asked Claude Code to "refactor the IngestionService to be more consistent with the rest of the codebase."

Generated result:

# services/ingestion.py — generated by Claude Code
from sqlmodel import Session  # ← CRITICAL VIOLATION
from core.database import get_session

class IngestionService:
    async def ingest(self, payload, trace_id):
        async with get_session() as session:  # ← destroys hot path
            session.add(SensorReading(**payload.dict()))
            await session.commit()

Technically correct. Architecturally catastrophic. Write latency jumps from 0.8ms to 4–6ms. At 5,000 messages per second, that's the difference between a system that holds under load and one that collapses.

Claude Code doesn't know this. It can't. The architecture lives in my head and in a text document it may or may not have read before generating the code.

The Solution: Architecture Fitness Tests

The idea isn't new — Martin Fowler writes about "fitness functions" in Building Evolutionary Architectures. But the application to AI-assisted development is very concrete: if the model is going to have full refactoring permission, you need tests that fail immediately when an architectural boundary is crossed.

Not runtime tests. Static structure tests — AST analysis of Python source, zero external dependencies, zero running server needed.

The full suite runs in 0.4 seconds. Pre-commit, not post-deploy.

A Concrete Example

The most important test in my system:

# tests/test_architecture_fitness.py

def test_ingestion_service_never_imports_sqlmodel(self):
    """
    The IngestionService is the Hot Path. SQLModel (SQLAlchemy) must
    never appear here. This is the most critical boundary in the system.
    """
    if not INGESTION_SERVICE.exists():
        pytest.skip(f"IngestionService not yet created at {INGESTION_SERVICE}")

    violations = []
    forbidden = {"sqlmodel", "sqlalchemy", "SQLModel", "AsyncSession"}

    for imp in _get_imports(INGESTION_SERVICE):
        module = imp["module"]
        names = imp["names"]
        if any(module.startswith(f) for f in forbidden):
            violations.append(imp)
        if any(name in forbidden for name in names):
            violations.append(imp)

    assert not violations, _format_violation(
        violations,
        "IngestionService imported SQLModel/SQLAlchemy.\n"
        "  Fix: Use asyncpg raw SQL only in services/ingestion.py.\n"
        "  This is the Dual-Path contract. The hot path has zero ORM overhead."
    )

The _get_imports function uses Python's stdlib ast module to parse the file without executing it:

def _get_imports(filepath: Path) -> list[dict]:
    tree = ast.parse(filepath.read_text(encoding="utf-8"))
    imports = []
    for node in ast.walk(tree):
        if isinstance(node, ast.ImportFrom):
            module = node.module or ""
            imports.append({
                "module": module,
                "names": [alias.name for alias in node.names],
                "line": node.lineno,
                "file": str(filepath),
            })
    return imports

Zero external imports. Zero server. Zero database. Just Python.

The 8 Boundaries I Test

My system has a 7-layer architectural contract. The tests cover the most common violations AI generates:

1. Layer Isolation — Import Guards

MQTT workers never import LangGraph
IngestionService never imports SQLModel
Agents never write directly via ORM
Routers never call IngestionService directly 2. Hot Path Integrity
IngestionService uses only raw SQL strings, never query builders
Hot path tables never defined as SQLModel models 3. Event Contracts
Redis Stream publishes use the canonical DomainEvent envelope
MQTT workers validate with Pydantic before publishing 4. Async Enforcement
No synchronous HTTP clients (requests) in routers
No time.sleep() in IngestionService
Worker handlers are async def 5. Trace ID Contract
IngestionService.ingest() accepts trace_id as a parameter
All domain events include trace_id 6. Redis Keyspace Convention
No bare Redis keys without a namespace prefix
checkpoint:{id}, stream:{name}, cache:{type}:{id} 7. Migration Integrity
Zero DDL statements in application code 8. Full Dependency Topology
Validates the complete forbidden import matrix in a single pass

The Result in Production

When I give Claude Code full permission to refactor any file, the cycle is:

Claude Code generates code
        ↓
pytest tests/test_architecture_fitness.py -v
        ↓ (0.4 seconds)
Red → Claude Code fixes
        ↓
Green → commit

The model can never violate architectural boundaries without me knowing immediately. Not because it's adversarial — but because it optimises for local consistency, not global contracts.

After adding these tests, all architectural violations disappeared from code reviews. Claude Code started generating compliant code automatically because the CLAUDE.md context file explicitly describes what the tests verify.

CLAUDE.md — The Second Mechanism

The tests are enforcement. CLAUDE.md is prevention.

It's a file at the repo root that Cursor and Claude Code read before generating code. It contains the contracts in explicit language with ✅ correct vs ❌ wrong examples:

## Hard Boundaries (Enforced by tests/test_architecture_fitness.py)

### 1. The Dual-Path Contract

services/ingestion.py → asyncpg ONLY
  ✅ await pool.acquire() → await conn.execute("INSERT INTO ...", ...)
  ❌ from sqlmodel import Session
  ❌ session.add() / session.commit()
  ❌ time.sleep() — use await asyncio.sleep()

The combination of failing tests + explicit documentation creates an environment where AI can refactor freely with structural guarantees.

Final Numbers

Full suite:          18 tests
Execution time:      0.42 seconds
Dependencies:        0 (stdlib Python + pytest only)
Violations caught
before adding tests: 12+
Violations after:    0

Conclusion

AI-assisted development is genuinely transformative for productivity. But it creates a new category of risk: silent architectural drift. The model optimises for what it sees, not for what the global architecture requires.

Architecture Fitness Tests are the answer. They're not hard to write — Python's ast module does all the heavy lifting. And the return is immediate: full freedom to use AI on refactoring tasks without anxiety about what might have been broken.

If you're building a distributed system with AI-assisted development, these tests are the first thing you should write — not the last.

The complete boilerplate (FastAPI + asyncpg + LangGraph + MQTT + pgvector + Prometheus + Grafana) with the 18 tests, the CLAUDE.md, and a 20-section ARCHITECTURE.md is available at murinelo.gumroad.com/l/pdmfvr

推荐订阅源

DEV Community