Your Codebase Is Not Agent-Maintainable and That Is Your Next Big Problem
1 / 9
Executive Brief

Your Codebase Is Not Agent-Maintainable and That Is Your Next Big Problem

If your code is not agent-maintainable, your investment in AI coding tools will underperform its benchmarks.

Scan to read QR code linking to the article
01

Agent-hostile code patterns cost 300-person orgs $5,000,000 in annual labor loss

A 300-person engineering organization with 60% agent adoption loses roughly $5,000,000 annually in labor costs to rework caused by unmaintainable patterns.

Example: An agent generates a fix that creates a race condition because it cannot reason about hidden state. The engineer spends more time debugging the "fix" than they would have spent writing the code from scratch.

02

Semantic error rates exceed review capacity when agents reason across boundaries

If an agent must reason about state that lives in a different file or system to make a local change, the error rate will outpace your ability to review it.

Example: A developer changes a local variable that triggers an unintended side effect in a distant service. The agent sees the local scope as safe while the global system becomes unstable.

The Binary

Ambiguity vs Certainty

Implicit

Tribal Memory

Intent lives in Slack threads and PR comments.

High rework and semantic drift.

Explicit

Machine Contracts

Intent is baked into types and assertions.

High velocity and verifiable safety.

03

Conventional implementations ensure models operate within their zone of confidence

Boring is the new beautiful. Mirroring common patterns in public repositories ensures the model operates within its highest statistical confidence.

Example: A team uses a clever, custom abstraction where a standard library function would suffice. The agent attempts to use the abstraction, gets the syntax wrong, and requires a human fix.

When your contributor is an AI, boring is the new beautiful.

From the Executive Brief

04

Explicit types and assertions prevent agents from guessing at your intent

Until you replace implicit design decisions and tribal knowledge with explicit types, the agent will produce code that passes compilers but fails the business.

Example: An agent encounters an untyped dictionary and assumes the presence of an old key. The code fails at runtime because the agent guessed based on outdated patterns.

05

Machine-verifiable tests are the gatekeeper for agent-authored velocity

Without tests acting as contracts, you cannot safely deploy agent code without a line-by-line human audit that negates the primary velocity benefits.

Example: An agent refactors a critical module. Without a test suite to prove behavior is identical, a senior engineer must manually verify every line of the change.

Decision

Authorize a one-quarter pilot refactoring the twenty highest-churn files

Review against a target agent iteration rate of fewer than two attempts per change before expanding the standard organization-wide.

— Norman Agent Driven Development