{"slug": "how-i-prevented-claude-code-from-breaking-my-architecture-with-18-tests-that-run", "title": "How I Prevented Claude Code from Breaking My Architecture with 18 Tests That Run in 0.4 Seconds", "summary": "The author uses 18 static structure tests, running in 0.4 seconds, to prevent AI coding assistants like Claude Code from violating critical architectural boundaries in a complex FastAPI/IoT system. The key example shows a test that uses Python's AST module to check that the `IngestionService` never imports SQLModel or SQLAlchemy, enforcing a zero-ORM hot path rule that would otherwise be broken by AI-generated refactoring. These pre-commit \"fitness function\" tests catch violations immediately without needing a running server or database, protecting the system's architectural integrity during AI-assisted development.", "body_md": "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.\n\nThe 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.\n\nLet me show you the kind of thing that happens without protection.\n\n## The Problem\n\nMy 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.\n\nIn a typical session, I asked Claude Code to \"refactor the IngestionService to be more consistent with the rest of the codebase.\"\n\nGenerated result:\n\n``` python\n# services/ingestion.py — generated by Claude Code\nfrom sqlmodel import Session  # ← CRITICAL VIOLATION\nfrom core.database import get_session\n\nclass IngestionService:\n    async def ingest(self, payload, trace_id):\n        async with get_session() as session:  # ← destroys hot path\n            session.add(SensorReading(**payload.dict()))\n            await session.commit()\n```\n\nTechnically 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.\n\nClaude 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.\n\n## The Solution: Architecture Fitness Tests\n\nThe 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.\n\nNot runtime tests. **Static structure tests**— AST analysis of Python source, zero external dependencies, zero running server needed.\n\nThe full suite runs in**0.4 seconds**. Pre-commit, not post-deploy.\n\n## A Concrete Example\n\nThe most important test in my system:\n\n```\n# tests/test_architecture_fitness.py\n\ndef test_ingestion_service_never_imports_sqlmodel(self):\n    \"\"\"\n    The IngestionService is the Hot Path. SQLModel (SQLAlchemy) must\n    never appear here. This is the most critical boundary in the system.\n    \"\"\"\n    if not INGESTION_SERVICE.exists():\n        pytest.skip(f\"IngestionService not yet created at {INGESTION_SERVICE}\")\n\n    violations = []\n    forbidden = {\"sqlmodel\", \"sqlalchemy\", \"SQLModel\", \"AsyncSession\"}\n\n    for imp in _get_imports(INGESTION_SERVICE):\n        module = imp[\"module\"]\n        names = imp[\"names\"]\n        if any(module.startswith(f) for f in forbidden):\n            violations.append(imp)\n        if any(name in forbidden for name in names):\n            violations.append(imp)\n\n    assert not violations, _format_violation(\n        violations,\n        \"IngestionService imported SQLModel/SQLAlchemy.\\n\"\n        \"  Fix: Use asyncpg raw SQL only in services/ingestion.py.\\n\"\n        \"  This is the Dual-Path contract. The hot path has zero ORM overhead.\"\n    )\n```\n\nThe `_get_imports`\n\nfunction uses Python's stdlib `ast`\n\nmodule to parse the file without executing it:\n\n``` php\ndef _get_imports(filepath: Path) -> list[dict]:\n    tree = ast.parse(filepath.read_text(encoding=\"utf-8\"))\n    imports = []\n    for node in ast.walk(tree):\n        if isinstance(node, ast.ImportFrom):\n            module = node.module or \"\"\n            imports.append({\n                \"module\": module,\n                \"names\": [alias.name for alias in node.names],\n                \"line\": node.lineno,\n                \"file\": str(filepath),\n            })\n    return imports\n```\n\nZero external imports. Zero server. Zero database. Just Python.\n\n## The 8 Boundaries I Test\n\nMy 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\n- IngestionService never imports SQLModel\n- Agents never write directly via ORM\n- Routers never call IngestionService directly**2. Hot Path Integrity**- IngestionService uses only raw SQL strings, never query builders\n- Hot path tables never defined as SQLModel models**3. Event Contracts**- Redis Stream publishes use the canonical\n`DomainEvent`\n\nenvelope - MQTT workers validate with Pydantic before publishing**4. Async Enforcement**- No synchronous HTTP clients (\n`requests`\n\n) in routers - No\n`time.sleep()`\n\nin IngestionService - Worker handlers are\n`async def`**5. Trace ID Contract**-\n`IngestionService.ingest()`\n\naccepts`trace_id`\n\nas a parameter - All domain events include\n`trace_id`**6. Redis Keyspace Convention**- No bare Redis keys without a namespace prefix\n-\n`checkpoint:{id}`\n\n,`stream:{name}`\n\n,`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\n\n## The Result in Production\n\nWhen I give Claude Code full permission to refactor any file, the cycle is:\n\n```\nClaude Code generates code\n        ↓\npytest tests/test_architecture_fitness.py -v\n        ↓ (0.4 seconds)\nRed → Claude Code fixes\n        ↓\nGreen → commit\n```\n\nThe 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.\n\nAfter adding these tests, all architectural violations disappeared from code reviews. Claude Code started generating compliant code automatically because the `CLAUDE.md`\n\ncontext file explicitly describes what the tests verify.\n\n## CLAUDE.md — The Second Mechanism\n\nThe tests are enforcement. `CLAUDE.md`\n\nis prevention.\n\nIt'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:\n\n```\n## Hard Boundaries (Enforced by tests/test_architecture_fitness.py)\n\n### 1. The Dual-Path Contract\n\nservices/ingestion.py → asyncpg ONLY\n  ✅ await pool.acquire() → await conn.execute(\"INSERT INTO ...\", ...)\n  ❌ from sqlmodel import Session\n  ❌ session.add() / session.commit()\n  ❌ time.sleep() — use await asyncio.sleep()\n```\n\nThe combination of failing tests + explicit documentation creates an environment where AI can refactor freely with structural guarantees.\n\n## Final Numbers\n\n```\nFull suite:          18 tests\nExecution time:      0.42 seconds\nDependencies:        0 (stdlib Python + pytest only)\nViolations caught\nbefore adding tests: 12+\nViolations after:    0\n```\n\n## Conclusion\n\nAI-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.\n\nArchitecture Fitness Tests are the answer. They're not hard to write — Python's `ast`\n\nmodule 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.\n\nIf you're building a distributed system with AI-assisted development, these tests are the first thing you should write — not the last.\n\n*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*", "url": "https://wpnews.pro/news/how-i-prevented-claude-code-from-breaking-my-architecture-with-18-tests-that-run", "canonical_source": "https://dev.to/pedromurinelo/how-i-prevented-claude-code-from-breaking-my-architecture-with-18-tests-that-run-in-04-seconds-1f1o", "published_at": "2026-05-21 12:22:35+00:00", "updated_at": "2026-05-21 12:32:34.373236+00:00", "lang": "en", "topics": ["large-language-models", "developer-tools", "artificial-intelligence", "enterprise-software"], "entities": ["Claude Code", "Cursor", "FastAPI", "asyncpg", "LangGraph", "MQTT", "pgvector", "SQLModel"], "alternates": {"html": "https://wpnews.pro/news/how-i-prevented-claude-code-from-breaking-my-architecture-with-18-tests-that-run", "markdown": "https://wpnews.pro/news/how-i-prevented-claude-code-from-breaking-my-architecture-with-18-tests-that-run.md", "text": "https://wpnews.pro/news/how-i-prevented-claude-code-from-breaking-my-architecture-with-18-tests-that-run.txt", "jsonld": "https://wpnews.pro/news/how-i-prevented-claude-code-from-breaking-my-architecture-with-18-tests-that-run.jsonld"}}