Why AI coding agents need an architecture compiler (and I built one)

#ai #architecture #python #mcp

The problem nobody talks about

AI coding agents write code fast. Too fast. Within a few sessions you end up with:

Utility functions calling into feature modules
Feature logic embedded in CLI entry points
Circular dependencies 3 layers deep
Database clients instantiated inside pure functions

No linter catches this. No formatter fixes it. The codebase works -- but it's slowly becoming unmaintainable, and the agent helping you has no structural feedback to course-correct.

What I built

Atomadic Forge is an architecture compiler. Point it at any Python or JavaScript repo and it:

Scouts -- maps every symbol, tier, dependency, language
Wires -- finds every import that violates the composition law
Certifies -- assigns a score 0-100 with a SHA-256 receipt
Enforces -- auto-fixes violations in-place, dry-run safe

It runs as an MCP server -- your agent in Cursor or Claude Code can call certify, wire, recon, enforce, and 25+ other tools directly.

The 5-tier monadic composition law

Every file belongs to exactly one tier. Tiers compose upward only.

a0_qk_constants/     Zero logic. Pure data: constants, enums, TypedDicts.
a1_at_functions/     Pure stateless functions. Only imports: a0.
a2_mo_composites/    Stateful classes, clients, registries. Imports: a0+a1.
a3_og_features/      Features assembled from composites. Imports: a0-a2.
a4_sy_orchestration/ CLI, entry points, top-level wiring. Imports: a0-a3.

Real output

$ forge certify --project ./my-ai-built-app

{
  "score": 47,
  "issues": [
    "a1 imports from a3: utils.py -> feature_pipeline.py (7 occurrences)",
    "circular dependency: auth_client <-> user_service",
    "a4 contains 340 lines of business logic (belongs in a2/a3)"
  ]
}

$ forge enforce --apply --source ./src

{
  "score": 91,
  "pre_violations": 34,
  "post_violations": 3,
  "auto_fixed": 31
}

Install

pip install atomadic-forge
forge certify --project .
forge wire --source ./src --suggest-repairs

MCP config:

{
  "mcpServers": {
    "atomadic-forge": {
      "command": "forge",
      "args": ["mcp", "serve", "--project", "/your/project"],
      "env": { "FORGE_API_KEY": "your-key" },
      "type": "stdio"
    }
  }
}

Numbers

944 tests -- unit, integration, MCP protocol, stdio loop
29 MCP tools standard / 35 tools Forge Deluxe
Python and TypeScript/JavaScript support
Live demo: forge.atomadic.tech -- scan any public repo free
Open source: github.com/atomadictech/atomadic-forge

Drop questions in the comments -- I read every one.

DEV Community