Skip to content

Why Squeaky Clean?

A 5-minute read on what Squeaky Clean does and why it exists.

The problem

Small-parameter models frequently hallucinate, forcing engineers toward high-parameter alternatives where computational costs scale quadratically with context. Squeaky Clean is an opinionated, semi-deterministic agentic software development tool designed to break this cycle.

LLM codegen also has a Clean Architecture problem. "Write me a Spring Boot service that publishes to Kafka" from a single high-parameter prompt produces a single 200-line file with the controller talking directly to KafkaTemplate, the entity mutating to JSON inline, and zero separation between domain logic and infrastructure. It compiles. It runs. It's unmaintainable the moment you swap Kafka for SQS.

What's missing is architectural discipline: the discipline that says domain entities don't import frameworks; that ports live in the application layer and adapters live in the infrastructure layer; that crossing a bounded-context boundary requires an explicit contract. That discipline is what separates a one-shot demo from code that survives a refactor.

The approach

Squeaky Clean (or Squeaky) capitalizes on the modularity and granularity of Clean Architecture, SOLID principles, and GoF + DDD patterns. By doing so, it maximizes parallelization and wall-clock velocity while minimizing both the "hallucination blast radius" and operational costs.

The framework defines an Architectural DSL to orchestrate atomic, pattern-specialized agents that run efficiently on compact, low-parameter models. The pipeline splits into three layers, each with its own constraints:

  1. PrincipalArchitect (Architect tier). Reads a ProblemSpec and emits a structured ArchitectureSpec as a Squib. Decides bounded contexts, classes per context, layer assignment, dep edges. Deterministic by default.
  2. ImplementClass (ICP tier — Implements Clean Pattern). For each class in the architecture, runs a parallelizable atomic agent. Each ICP specializes in exactly one GoF/DDD pattern (or a Tier C infrastructure category). One file in, one file out.
  3. IntegrateModule + ValidateArchitecture. Assembles the per-class outputs into a runnable project, validates dependency rules, runs the generated test suite, computes metrics.

The Squib between tiers is a frozen, validated grammar (~200 chars per class, machine-checkable), so the cheaper tier rarely has to guess what the more capable tier meant.

Why "Clean" (twice over)

Why "Clean." Clean Architecture keeps software maintainable by holding details — the database, the web, the framework — at the edges. That same discipline has a second payoff as AI enters the loop: leaner compute. LLM inference cost grows super-linearly with context length (attention is O(n²)), and reaching for a higher-parameter model multiplies the curve. Because Clean Architecture decomposes a system into small, bounded contexts, each atomic agent sees one class and one pattern — a ~200-character Squib — so the overwhelming majority of token volume runs on compact models. Fewer tokens on smaller models means measurably lower cost per run today, and — proportionally — lower energy.

Reducing the ecological footprint of AI-assisted development is a goal this open-source project is building toward, not a figure it claims. We measure tokens and cost; energy is proportional to compute, so we speak of it proportionally — and we'll publish a monolithic-vs-Squeaky token ablation before quantifying further.

What you write

A 40-line ProblemSpec JSON. See Author your first ProblemSpec for the full shape.

What you get

A runnable project: src/, tests/, requirements.txt, main.py, plus an eval_report.json with the tests_pass ratio.

What's different

  • Architectural rigor enforced. Domain imports nothing, application imports only domain, infrastructure implements domain ports. The framework's own dependency_rule.py validator catches violations in generated code and in its own source. SOLID + GoF + DDD are the shared vocabulary between agent tiers; the rigid agent contracts keep quality consistent at the cheaper execution tier.
  • Pattern-specialized atomic agents. One pattern per agent. One agent per file. Sub-80-line system prompts. 60 infrastructure agents across 15 categories. Each agent's contract is tight enough that a compact-tier language model satisfies it without supervision.
  • Parallel fan-out across distributed architectures. Architects emit a multi-MODULE plan; agents run concurrently across classes within a module and across modules whose dependencies have resolved.
  • Compact-tier cost. Most token volume routes to compact, low-parameter models; the larger tier is reserved for architectural decisions. Cost and wall-clock figures by problem are on the Benchmarks page.
  • Cross-service contract fidelity. When two services produce/consume the same Kafka topic, the Contract Registry enforces field-shape agreement across language boundaries with case-tolerant validation.
  • Six languages from one spec. Switch target_language to java and you get a Spring Boot project in the same architectural shape, with idiomatic SDK calls and deterministic replay. Per-language test-pass maturity varies — see Benchmarks.

What it's not

  • Not a one-shot LLM call. Squeaky Clean orchestrates dozens of LLM calls per run, parallelized, with prompt caching and a strict per-tier cost budget.
  • Not a substitute for understanding your domain. The framework asks you to declare your bounded contexts in required_bounded_contexts and your acceptance criteria in acceptance_criteria. Garbage spec → garbage generation.
  • Not a code-completion tool. Squeaky Clean produces complete projects from a spec; it doesn't run inside your editor.

What to do next