Why AI-Generated Code Needs Architecture Standards (and How We Solved It)

#ai #opensource #python #architecture

Ask Claude, GPT, or Cursor to generate a REST API. You get a project. Ask again — you get a completely different structure. Different folders, different patterns, different conventions. Do it five times, maintain all five. Good luck.

This is the reality of AI-assisted development in 2026: the code works, but there's no consistency. Every generated project is a snowflake. And when your team has to maintain ten snowflakes, the speed advantage of AI disappears fast.

We built AgentGuard to fix this.

What AgentGuard Actually Does

AgentGuard is an open-source Python library that sits between your AI agent and the code it generates. It acts as an architecture layer — enforcing consistent patterns, folder structures, and conventions through what we call archetypes.

An archetype is essentially an architecture template: it defines how a project should be structured, what patterns to follow, and what conventions to respect. Think of it as a blueprint that your AI agent must follow when generating code.

The key difference from scaffolding tools like Cookiecutter: AgentGuard doesn't just create files. It works through your AI agent via MCP (Model Context Protocol), guiding the generation process step by step — skeleton first, then implementation, then validation.

pip install rlabs-agentguard

No API keys required. MIT license.

The Problem in Practice

Here's a real scenario we recorded for our demo series. We have a Note Manager API — a Flask app crammed into a single app.py file. 280 lines. Everything mixed together:

Routes, business logic, and database access in one file
Raw SQL embedded inside route handlers
Authentication with MD5 (yes, really)
Global variables for sessions and cache
No types, no tests, hardcoded secrets

It works. It runs. It's also unmaintainable, untestable, and a security risk.

This is what AI generates when you just say "build me an API" without architectural guidance. And it's what most teams end up with when they adopt AI coding tools without a strategy.

How AgentGuard Fixes It

AgentGuard operates in phases. When your AI agent receives a prompt like "generate a Note Manager API," AgentGuard intercepts through MCP and runs the generation through a structured pipeline:

1. Skeleton — Defines the complete project structure before writing a single line of code. Folders, files, responsibilities, layer boundaries.

2. Implementation — The agent generates code file by file, following the patterns defined in the archetype. Hexagonal architecture means domain logic is separated from infrastructure. Repository pattern means database access has a clean interface.

3. Validation — AgentGuard checks that the generated code actually follows the archetype's rules. Wrong layer dependency? Missing interface? It catches it.

The result: instead of a 280-line spaghetti file, you get a clean hexagonal API with separated layers, proper auth, typed models, and tests. Same functionality, completely different maintainability.

The Marketplace

The AgentGuard Marketplace currently hosts 61+ archetypes covering common patterns:

API backends — hexagonal architecture with FastAPI/Flask
CQRS services — command/query separation with event sourcing
React SPAs — component structure with state management patterns
Documentation templates — ADRs, PRDs, dev guides
Microservice scaffolds — with proper boundaries and contracts

Any team can create and publish their own archetypes. Your company's architecture standards, packaged as reusable templates that any AI agent can consume.

MCP: Why It Matters

AgentGuard uses MCP (Model Context Protocol) as its integration layer. This means it works with any AI agent that supports MCP — Claude, Cline, Cursor, Windsurf, and more.

Your IDE agent connects to the marketplace, searches for archetypes, downloads them, and applies them — all automatically. No copy-pasting configuration files. No manual setup per project.

# In your AI agent (Claude, Cline, etc.):
"Using AgentGuard with the api_backend archetype, 
 generate a Note Manager REST API with FastAPI, 
 SQLite, JWT auth, and hexagonal architecture"

The agent handles the rest.

See It in Action

We recorded a demo series showing every step, from installation to migrating real spaghetti code:

Episode	What it covers	Link
Explainer (EN)	What is AgentGuard? — 4 min overview	Watch
Explainer (ES)	¿Qué es AgentGuard? — explicación en español	Watch
Ep.01	Installation & Setup — pip install to running in 4 min	Watch
Ep.02	Project from Scratch — empty folder to working API	Watch
Ep.03	Auto Documentation — ADR, PRD, Dev Guide generated	Watch
Ep.04	Spaghetti → CQRS — 280 lines of chaos to clean architecture	Watch

The migration demo (Ep.04) is the most compelling: same app, same functionality, before and after. The spaghetti app runs, we migrate it live with AgentGuard, and the result runs with the same API contract but clean architecture underneath.

The Stack

For the demos we used:

LLM: Qwen 3.5 (running locally via Ollama — no cloud dependency)
Agent: Cline in VSCode
QA layer: AgentGuard MCP server
Environment: Clean Windows Sandbox

This is intentional. We wanted to show that AgentGuard works with local models, not just cloud APIs. If a local 7B model can follow architectural patterns through AgentGuard, any model can.

Who Is This For?

Tech leads and architects who want their team's AI-generated code to follow company standards. Instead of writing a 50-page architecture guide that nobody reads, package your standards as an archetype. The AI follows it automatically.

Solo developers who want consistency across their own projects. Same patterns, same structure, every time. Six months from now, you'll actually understand the code your AI generated today.

Teams adopting AI coding tools who are discovering that "fast code" and "maintainable code" are not the same thing. AgentGuard bridges that gap.