'The Only Thing That Sloppifies a Codebase Faster Than 1 Coding Agent Is a Swarm of Them': A Manifesto for AI-Era Code Quality

The Warning

"The only thing that sloppifies a codebase faster than 1 coding agent is a swarm of them."

This arresting line opens aicode — a manifesto and practical guide for maintaining code quality in the age of AI coding agents. Published by theswerd, the document argues that AI-generated code demands more intentional architecture, not less.

The Core Thesis

As AI coding agents (Claude Code, Cursor, Codex, Copilot) increasingly write production code, a new risk emerges: the accumulation of subtly misaligned code that looks correct but erodes the codebase over time.

The manifesto proposes a framework for how code written by AI should be structured, and it's available as an installable skill for AI agents:

npx skills add theswerd/aicode

Two Types of Functions

The framework distinguishes between two patterns:

Semantic Functions

The building blocks of a codebase. Rules:

• Minimal — Do exactly one thing
• Self-documenting — No comments needed; the function name describes what it does
• Take all inputs, return all outputs — No hidden dependencies or side effects
• Highly unit-testable — Well-defined inputs and outputs
• Composable — Can wrap other semantic functions

Examples range from quadratic_formula() to retry_with_exponential_backoff_and_run_y_in_between<Y, X>(x, y).

"Even if these functions are never used again, future humans and agents going over the code will appreciate the indexing of information."

Pragmatic Functions

The complex processes of the codebase. Rules:

• Wrap semantic functions — Organize complexity, don't create it
• Used in few places — If reused heavily, break down into semantic functions
• Integration-tested — Not unit-tested; tested in the context of app functionality
• Expected to change — These are the volatile layer

Examples: provision_new_workspace_for_github_repo(repo, user) or handle_user_signup_webhook().

Key Principles

1. Code Should Be Self-Documenting

"Semantic functions should not need any comments around them, the code itself should be a self-describing definition of what it does."

This isn't just about readability — it's about machine readability. AI agents that generate or modify code need to understand intent from structure, not comments that may become stale.

2. Data Flow Should Be Explicit

"How you split logic into functions and shape the data they pass around determines how well a codebase holds up over time."

Every function should make its inputs and outputs explicit. No hidden state mutations. No "this function modifies something three calls up the stack."

3. Indexing Information

Well-named functions serve as an index into the codebase's capabilities. Future developers (human or AI) can discover functionality through naming, not through grep-and-hope.

Why This Matters Now

Before AI coding agents, code quality was limited by developer discipline and review processes. The rate of code creation was bounded by human typing speed and cognitive load.

With AI agents:

• Code creation is 10-100x faster
• Review becomes the bottleneck
• Subtle misalignments accumulate faster
• The "slop" problem is real — code that works but doesn't fit the architecture

The manifesto argues this makes intentional architecture more important, not less. When an AI can write 1,000 lines in minutes, the question isn't "can we write it?" but "should this exist in our codebase, and if so, where?"

The Installation Play

Making this available as a skill for AI agents (npx skills add theswerd/aicode) is a clever move:

1. Agents can enforce the rules while writing code
2. Consistent style across AI-generated and human-written code
3. Living documentation that evolves with the framework
4. Reduces review burden — pre-aligned code needs less scrutiny

Critique

The framework is sensible but risks being prescriptive without context. Not every codebase benefits from strict semantic/pragmatic separation. The manifesto acknowledges this implicitly — pragmatic functions exist specifically for messy reality — but the tone sometimes leans toward purity.

That said, for teams that have adopted AI coding agents and are watching their codebases expand rapidly, the core insight is valuable: AI agents need architectural guardrails, not just prompt instructions.

Source: aicode.swerdlow.dev