The AI Coding Manifesto: Why Intentional Architecture Matters More Than Ever

"The Only Thing That Sloppifies a Codebase Faster Than 1 Coding Agent Is a Swarm of Them"

As AI coding agents increasingly write production code, a critical question emerges: what should AI-generated code actually look like?

A new manifesto published at aicode.swerdlow.dev addresses this with a clear-eyed thesis: without intentional guardrails, AI agents will rapidly degrade code quality in ways that compound over time.

The Core Problem

AI coding agents are phenomenally productive — they can generate hundreds of lines of correct-looking code in seconds. But their optimization function is completion, not maintainability. Left unchecked, agents tend to:

• Create monolithic functions that work but are unreadable
• Duplicate logic across files because context is fragmented
• Add unnecessary complexity to handle edge cases
• Skip the architectural decisions that human engineers make instinctively

The Solution: Semantic Functions

The manifesto's key proposal is a two-tier function architecture:

Semantic Functions

The building blocks of a codebase. A good semantic function should be:

• Minimal — does one thing, takes in what it needs, returns what's needed
• Self-documenting — the name and signature tell you everything
• Side-effect free (unless side effects are the explicit goal)
• Unit-testable — well-defined inputs and outputs

Examples range from simple (quadratic_formula()) to complex (retry_with_exponential_backoff_and_run_y_in_between()).

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

Pragmatic Functions

Wrappers around semantic functions that handle messy real-world flows:

• **provision_new_workspace_for_github_repo(repo, user)**
• **handle_user_signup_webhook()**

These are expected to change over time and tested via integration tests.

The Key Principles

1. Code should be self-documenting — If you need a comment, the code isn't clear enough
2. Functions should be minimal — Prioritize correctness over cleverness
3. Data flow should be explicit — Functions take what they need, return what's necessary
4. Complexity should be decomposed — Break messy flows into chains of semantic functions
5. Tests should match the tier — Unit tests for semantic, integration for pragmatic

Why This Matters Now

Before AI agents, bad code accumulated slowly — one developer at a time, constrained by typing speed and review processes. With agents:

• Code can be generated orders of magnitude faster than it can be reviewed
• Multiple agents can work simultaneously, creating conflicting patterns
• The cost of fixing architectural debt is deferred but amplified

Practical Implications

The manifesto is available as an installable skill for AI agents:

npx skills add theswerd/aicode

This means you can literally give your coding agent these guidelines, creating a shared standard for what "good" AI-generated code looks like.

The Bigger Picture

This is part of a broader industry reckoning with AI-generated code. As tools like Claude Code, Codex, Copilot, and Cursor become standard developer tools, the question shifts from "can AI write code?" to "should we let AI write code this way?"

The answer, according to this manifesto: yes — but with intentional constraints that prioritize long-term codebase health over short-term output volume.

The manifesto is concise, practical, and immediately actionable — exactly the kind of guidance the industry needs as AI coding goes mainstream.

Source: aicode.swerdlow.dev