The more code AI agents write, the faster your codebase can turn into a mess nobody understands. Developer Josh Swerdlow published a manifesto-style guide arguing that teams need explicit structural rules before letting AI loose on their repos, not after the damage is done.
The core problem: one AI agent producing sloppy code is manageable. Three or four agents, each building on each other's output with no shared standards, compounds bad patterns at a rate human teams never experienced. Swerdlow's answer is a classification system that sorts every function and data structure into clear categories with strict rules.
Semantic Functions: Small, Pure, Testable
The first category is what Swerdlow calls "semantic functions" - minimal building blocks that take inputs, return outputs, and do nothing else. Think quadratic_formula() or retry_with_exponential_backoff(). No side effects, no hidden state. They should be obvious enough to not need comments and simple enough to unit test completely.
This matters for AI-generated code specifically because agents tend to write functions that do too many things at once. Forcing the "semantic" constraint means every AI-generated utility stays small enough for a human to verify at a glance.
Pragmatic Functions: The Messy Orchestration Layer
The second category handles real-world complexity. A function like provision_new_workspace_for_github_repo() calls multiple semantic functions, deals with external services, and will probably change next quarter. Swerdlow's rule: accept that these functions are messy, but document the surprising behaviors, not the obvious ones. A comment explaining an unexpected retry or a non-obvious ordering dependency is useful. A comment restating what the function name already says is noise.
The biggest risk he identifies is semantic functions slowly morphing into pragmatic ones through "just one more feature" additions. AI agents are especially prone to this because they optimize for making the current request work, not for long-term architecture.
Models That Make Wrong States Impossible
The third piece is data modeling. Instead of a User object with a dozen optional fields where half the combinations are invalid, use precise types like UnverifiedEmail and BillingAddress that encode their constraints in the type system. Use branded types (wrapping a generic UUID in a DocumentId type, for example) so the compiler catches mistakes before runtime does.
This is where AI agents struggle most. Ask an agent to "add a field" and it will happily tack an optional property onto an existing model, creating exactly the kind of ambiguous state that causes bugs three months later.
Swerdlow packages these principles as an installable agent skill (npx skills add theswerd/aicode) for Cursor, which is a smart distribution choice. Rather than hoping developers read a blog post and remember the rules, the skill injects the constraints directly into the AI agent's context.
The guide does not address the harder organizational question: how do you enforce these patterns across a team where different people configure their AI agents differently? A shared skill file helps, but code review still has to catch violations. Still, having a named vocabulary for these categories (semantic vs. pragmatic, branded types vs. bare primitives) gives teams something concrete to point at during review, which is more than most shops have right now.