Why AI Agents Keep Breaking Your Code (And What to Do About It)

#claudecode #ai #programming #productivity

Picture this: you write a requirement. Clear, specific. The agent reads it, does exactly what you wrote — and breaks three things you never mentioned.

Not because the agent is bad at its job. Because the spec was written for a human reader, not a machine.

Human developers tolerate ambiguity. They fill gaps from experience. They ask before doing something irreversible. AI agents don't work that way — they fill gaps with whatever their training data suggests. Sometimes that's fine. Sometimes it destroys an afternoon.

After hitting this wall enough times, I stopped trying to write better prompts and started thinking about the spec format itself.

The real problem: spec formats haven't evolved

IEEE 830. ISO/IEC 29148. GOST 34.602. All written decades before AI coding agents existed. All designed for a human reader who can tolerate a certain level of "you know what I mean."

Agents don't know what you mean. They know what you wrote.

The gap between those two things is where most rework happens.

What I built: ANSS

ANSS (AI-Native System Specification Standard) is a spec format where AI agents are treated as first-class readers — not an afterthought.

Here's what changed in my workflow after adopting it: instead of 5–7 back-and-forth iterations to get an agent to do something right, I'm down to 2–3. Agents started surfacing contradictions in my own specs before writing a single line of code. That alone saved me hours I didn't know I was losing.

The four mechanisms that actually matter

1. Three-layer markup

Every section gets a tag:

[D] Domain        — WHAT to build   → Product Owner, PM
[E] Engineering   — HOW to build    → Developer, Architect
[A] Agent         — HOW agent does it → AI agents (read this first)

Agents read [A] sections first. Everything they need to operate without guessing lives there.

2. Invariants

INV-001: No external npm packages
Cannot: add require() of npm modules
Reason: app must run without npm install
Check: no node_modules imports in server.js

The Check field is what makes this different from a comment. It's a verifiable rule. Before invariants, I wrote "keep the codebase minimal" — an agent once interpreted that as license to add three npm packages. Invariants eliminate that interpretation space.

3. Agent Review

Before writing anything, the agent audits the spec:

Find contradictions between sections
Identify missing edge cases
Check Acceptance Criteria completeness
Verify no invariant conflicts

Hard rule: more than 3 problems found → stop and ask. Do not proceed.

The first time an agent told me "I found 5 contradictions in your spec" before writing a line of code, I realized how many hours of rework I'd been generating for myself.

4. Change Specification

Current State → Desired State → What NOT to change → Impact → Rollback

"What NOT to change" is the section that doesn't exist in any classic spec format. It's the most useful thing I've added to my workflow.

Three levels

CORE        15–20 pages   Bots, SaaS, APIs, automations (80% of projects)
EXTENDED    40–60 pages   Security, compliance, detailed testing
ENTERPRISE  Full standard Banks, regulated industries, AI platforms