What AI Demands From Its Masters

Best practices are no longer nice-to-haves. They are requirements from the AI that writes your code.

Lessons learned building AILANG: the same engineering discipline we always needed now becomes a non-negotiable demand from AI agents. These axioms apply to any language, any stack.

Tighten the Loop or AI Quits

<1s

Feedback cycle target

CI/CD, red-to-green TDD

Build

Compile time is a design decision

Factor AI iteration into language choice

0

Tolerance for unstructured errors

Typed, composable, machine-parseable

AI iterates thousands of times. Long builds, vague errors, and slow CI are a denial-of-service attack on your own AI agent.

Front-Load Decisions, Iterate at the Start

Vague Brief

AI guesses intent. Builds the wrong thing. Expensive redo. O(n) cost per misalignment.

Design Doc

Explicit constraints. Decision boundaries. AI iterates cheaply within guardrails. O(1) upfront.

After-the-fact feedback

Human reviews code after AI wrote it, discovers misalignment, throws it away. The most expensive loop possible.

Front-loaded authority

Design doc specifies where AI has freedom and where humans must decide. Iterate at the spec, not the implementation.

An explicit design doc is cheaper than a rewrite. Specify where AI chooses and where it doesn't.

No Hidden Context

Implicit (poison for AI)

Global variables, ambient authority, transitive imports, mutable shared state. Every piece of hidden context is a trap.

import os
result = readFile(path)
# Where does readFile come from?
# What effects can it have? AI has no idea.

Explicit (AI can reason)

Local scope, declared effects, explicit imports, immutable values. If AI can see it, AI can reason about it.

import std/io (println)
import std/fs (readFile)

export func main() -> () ! {IO, FS}
-- Every import named. Every effect declared.

"Self-documenting code" was for human aesthetics. AI needs all context to be machine-readable, not just human-readable. Stop pandering to human preferences — optimise for the machine that writes 90% of the code.

The Demand Sheet

Tight validation loops (CI/CD, TDD)

Factor compile time into language choice

Front-load design decisions

No implicit global state

All context must be explicit

Structured, typed errors

Deterministic execution Axiom 1

Explicit effects & authority Axioms 3, 4

Replayable, auditable traces Axiom 2

Cost visibility Axiom 9

These aren't aspirational. They're the minimum spec for a codebase AI can work in.