Be intentional about how AI changes your codebase

TL;DR Highlight

A guide presenting concrete code writing principles — Semantic Function design, Pragmatic Function design, type-safe model design, and more — to prevent codebases from silently rotting as AI coding agents rapidly generate code.

Who Should Read

Backend and fullstack developers or team leads who use AI coding agents (Cursor, Copilot, etc.) daily and worry about codebase quality degradation.

Core Mechanics

Semantic Functions are functions whose names and signatures fully communicate their intent and constraints — making them easier for AI agents to use correctly without reading the implementation.
Pragmatic Functions handle side effects, I/O, and state mutations in clearly bounded, explicit ways — preventing AI agents from inadvertently scattering side effects across the codebase.
Type-safe model design — using discriminated unions, branded types, and exhaustive pattern matching — creates guardrails that catch AI-generated errors at compile time rather than runtime.
The guide argues that 'AI-resistant code' is code that's explicit, strongly typed, and well-named enough that even an AI agent generating code around it is unlikely to introduce subtle bugs.
These principles aren't new — they're established software engineering best practices — but their value is amplified in AI-assisted development where code generation speed outpaces human review speed.

Evidence

The author shared before/after code examples where applying these principles to a codebase measurably reduced the frequency of AI-generated bugs in adjacent code.
Commenters with TypeScript backgrounds found the type-safe model design section particularly compelling — several noted that discriminated unions are underutilized even in human-written code.
Some pushback: applying all these principles rigorously adds overhead and might slow down initial development, even if it helps quality long-term.
The observation that 'good code is good code regardless of who wrote it' resonated — the principles aren't special-cased for AI, they're just good engineering.

How to Apply

Audit your codebase for functions with side effects scattered throughout — refactor these to be explicit and contained as a first step toward AI-resistant code.
Introduce discriminated unions for state that has multiple distinct modes (loading/error/success patterns) — this prevents AI agents from conflating states.
Write function signatures as contracts: if a function should never receive null, encode that in the type system rather than relying on documentation.
When reviewing AI-generated code, specifically check: are side effects contained? Are types explicit? Are function names accurate to behavior? These are the most common AI failure modes.

Code Example

snippet

// Brand Type example (TypeScript)
type DocumentId = string & { readonly __brand: 'DocumentId' };
type MessagePointerId = string & { readonly __brand: 'MessagePointerId' };

function getDocument(id: DocumentId) { /* ... */ }

const msgId = 'abc123' as MessagePointerId;
// getDocument(msgId); // ❌ Compile error: prevents incorrect type usage

// Semantic Function example
function retryWithExponentialBackoff<T>(
  fn: () => Promise<T>,
  maxRetries: number,
  baseDelayMs: number
): Promise<T> {
  // Only takes inputs, only returns outputs, no side effects
}

// Add skills to AI agent with npx
// npx skills add theswerd/aicode

Terminology

Discriminated UnionA type that can be one of several variants, each tagged with a unique discriminator — enables exhaustive pattern matching and eliminates impossible states.

Branded TypeA type that's structurally identical to a primitive but logically distinct — e.g., UserId vs. ProductId, both strings but not interchangeable.

Exhaustive Pattern MatchingA pattern where the compiler verifies that all possible variants of a type are handled, preventing missing-case bugs.

Side EffectAny action a function takes beyond returning a value — modifying state, writing to a file, making a network call, etc.