Everyone is vibe coding.
What you actually need is friction.
AI lets you build at 200 mph until you slam into the architectural wall. Generating code is cheap—maintaining messy AI spaghetti is ruinously expensive. Alum injects automated architectural friction, stopping AI code rot before it kills your startup.
The Anatomy of an AI Code Collapse
Why every AI app feels effortless on Monday and impossible to change by Friday.
The Vibe-Coding High
You type prompts into Cursor or Claude. Code flows like water. The prototype works in 3 hours. You feel invincible.
The Hidden Creep
Files swell to 800 lines. The AI writes 5-level nested if/else statements and passes raw strings everywhere with zero encapsulation.
The Refactoring Wall
Fixing one button breaks authentication. The AI hallucinates, undoes its own code, and you want to throw the project away and restart.
The Alum Cure
Alum rejects messy code immediately at commit time. It forces the AI to refactor itself into clean, decoupled micro-modules on the fly.
The Anti-Captivity Mandate: Stop Renting Your Architecture
The mega-labs want you to believe that "bigger context windows and frontier reasoning models will fix your messy code." This is cognitive feudalism.
When your codebase has 1,500-line God objects and tangled dependencies, lightweight models choke. You become permanently captive to expensive frontier models ($20/M tokens) just to make a routine bug fix. If they raise prices, rate-limit you, or experience downtime, your project dies.
Alum breaks the trap: By mechanically enforcing micro-functions (<15 lines) and bounded Value Objects, every unit of your code fits cleanly into small, fast context windows. You can run, maintain, and evolve your entire system using hyper-efficient, commodity models like Gemini 3.5 Flash or local 8B LLMs for pennies.
You must adhere strictly to the Alum architectural invariants: 1. Max 1 level of indentation per function (use early-return guard clauses; never use the 'else' keyword). 2. Wrap raw primitives (strings, numbers) in semantic value classes or types. 3. Keep all functions under 15 lines and classes under 60 lines. 4. Adhere to Tell, Don't Ask: expose behavior, never raw state or public getters. 5. If any rule is violated, immediately refactor into decoupled helper objects before returning code.
Object Calisthenics & AST Invariants
for High-Acuity Engineering.
Derived from Jeff Bay's ThoughtWorks axioms and AST static analysis. Alum acts like chemical alum precipitating impurities from turbid water—eliminating primitive obsession, mock theater, and Demeter violations at the AST parser boundary.
The 9 Mathematical Laws of Alum
Evaluated directly against the Abstract Syntax Tree (AST) at commit and CI time.
| # | Law Name | AST Invariant | Architectural Rationale |
|---|---|---|---|
| 01 | One Level of Indentation | MethodDeclaration depth ≤ 1 |
Eliminates cyclomatic complexity. Forces extraction of nested conditionals into cohesive helper methods. |
| 02 | Don't Use "ELSE" | ElseStatement count == 0 |
Forces early-return Guard Clauses and polymorphic dispatch. Prevents bifurcated state bugs. |
| 03 | Wrap All Primitives | No raw string or number fields |
Eliminates Primitive Obsession. Encapsulates validation and domain invariants in Value Objects (e.g., EmailAddress, Money). |
| 04 | First-Class Collections | Classes containing arrays hold 0 other state | Collection manipulation logic belongs to the collection aggregate, not smeared across domain services. |
| 05 | One Dot Per Line | PropertyAccess depth ≤ 1 |
Strict Law of Demeter. Talk only to immediate friends (a.b()), never transitively (a.b.c.d()). |
| 06 | Don't Abbreviate | Identifier.length > 2 (except i, j) |
Self-documenting ubiquitous language. Code is read 100x more frequently than it is written. |
| 07 | Keep Entities Small | Function < 15 lines; Class < 60 lines | Guarantees micro-cohesion and fits entire methods into immediate human or LLM attention windows. |
| 08 | Max 2 Instance Variables | PropertyDeclaration count ≤ 2 |
Forces strict decomposition of monolithic God classes into small, composed aggregates. |
| 09 | No Getters or Setters | GetAccessor | SetAccessor == 0 |
"Tell, Don't Ask." Objects expose behavioral commands, never raw state. Eliminates anemic domain models. |
The Detroit-School Test Engine (alum-spec)
Zero mocks. Zero spies. Zero AST monkey-patching. Just pure state contracts.
setup()
Prepares isolated, stateful in-memory fakes. Zero shared mutable state across test boundaries.
run(context)
Executes the domain action and returns the entire resulting world as a plain observable object.
expect: structural diff
Evaluates actual vs expected in a unified diff. Partial matching by default; expectStrict() for security DTOs.
Architectural Guardrails, Invariant Enforcement, and Verification Cages
Software systems decay when architectural constraints exist only as human conventions. In human teams and autonomous agentic coding workflows, unconstrained development leads to two systemic failure modes: the "one-shot" defect and "regression ping-pong".
1. The Two Failure Modes of AI Coding
When autonomous coding agents attempt to fix complex defects without mechanical boundaries, they fall into regression ping-pong, where resolving one failing test causes another to fail, leading to repetitive or unhelpful modifications.
Furthermore, a 2025 study examining 251 agent-generated patches that successfully passed the SWE-bench Full test suite revealed that 63.75% of the fixes were suspicious. In 32.67% of cases, solutions leaked directly into issue descriptions, or weak assertions allowed incomplete patches to pass without satisfying original requirements.
2. The Anti-Captivity Argument
We cannot leave it to frontier closed models to define what is feasible or create permanent dependency on them for project continuation. When code is allowed to sprawl into unstructured, 2,000-line spaghetti files, companies become completely dependent on mega-lab reasoning models.
By strictly enforcing micro-functions (<15 lines), zero nesting (≤1 depth), and wrapped primitives, Alum ensures every module fits into minimal context windows. This enables full maintenance and development using fast, cost-effective commodity models (such as Gemini 3.5 Flash) or local open-weights LLMs.
3. Living Fitness Functions & Via Negativa
Top-tier engineering organizations prevent structural drift by converting architecture into executable code:
# Architectural Guardrails Invariant (Semgrep / Alum AST)
rules:
- id: block-direct-db-access-in-domain
severity: ERROR
message: "Business models must use Repository interfaces rather than calling database drivers directly."
paths:
include: ["src/domain/**"]
patterns:
- pattern-either:
- pattern: import psycopg2
- pattern: import sqlalchemy4. Ratcheting Quality Gates
A mechanical ratchet ensures that system quality metrics can advance or hold steady, but can never decline. Existing debt is recorded into a baseline; any new violation halts continuous integration.