Field note · May 12, 2026

The AI-Ready Codebase

A year ago, AI in your codebase meant autocomplete. Today it means a coworker — Claude Code, Cursor, Copilot — that opens PRs, fixes bugs, refactors, ships features. Some of your engineers have already noticed. The output difference is jarring: a senior engineer with agents on a task shipping three or four PRs in the time it used to take to ship one.

But here's what doesn't show up in the demos. The same AI agent works five times better in some codebases than in others — same model, same task, completely different outcome. The difference isn't the agent. It's the codebase. On an unhealthy one, AI multiplies the debt already there.

We call this AI readiness. It's the property of a codebase that determines whether an AI agent can get useful work done inside it. And right now, most engineering orgs are not ready.

An AI-ready codebase is a codebase where conventions, tests, types, architecture context, build steps, and roadmap information are available inside the repo so AI agents can make changes, verify them, and avoid relying on undocumented team knowledge.

This is the framework we use to score it.

What "AI-ready" actually means

When a human engineer joins your team, they ramp up. They read code, ask questions, get burned by an undocumented gotcha, find the right Slack thread, and slowly build a mental model. After two weeks they're useful. After two months they're shipping at full speed.

An AI agent has none of that runway. It gets one chance per task. It reads what's in front of it, predicts what to do, writes it, runs it, and either succeeds or doesn't. There is no second day. There is no Slack to search. There is no senior engineer to nudge it back when it goes off course.

So an AI-ready codebase is one where everything an agent needs to do useful work is in the repo, in a form it can read. Conventions are written down, not in people's heads. Types describe what functions actually do. Tests verify the agent's work without a human in the loop. Modules are small enough to fit in a single context. The roadmap is in git, not in a Notion someone forgot to share.

This is the same thing that makes onboarding new humans fast. AI readiness is the same property as engineering hygiene, measured against a stricter judge.

The business outcome is simple. In an AI-ready codebase, your senior engineers — augmented by agents — ship at a multiple of what they used to. In a codebase that isn't, you get the demos but not the productivity. The agents try to help and produce slop your team has to clean up. The senior engineers, who could have been writing the next thing, end up reviewing AI mistakes instead.

Why most engineering orgs aren't ready

We've audited dozens of codebases. The same four patterns show up everywhere. Each one starts as a symptom you'll recognise as a founder. There's a name underneath.

"Senior devs say it's faster to write it themselves than to tell the AI what to do." This is the most common signal. Translation: your engineering conventions live in your senior engineers' heads. The agent doesn't know the patterns. The senior does. So the senior gives up on the agent and writes the code. You pay for senior time and you get senior output. The leverage that AI promised never lands.

"Onboarding a new engineer takes two or three weeks." What humans need to ramp up is the same thing AI agents need to operate: context. If the README is out of date, the architecture lives in a Confluence page from 2023, and the actual answer to "how does auth work here" is "ask the one person who built it," then both humans and agents fail at the same boundary. You'll feel this as slow hiring leverage. Agents feel it as zero leverage.

"PRs break production every other week." If your tests are flaky, your linters skip the gnarly parts, and your CI is a suggestion, then you don't have a working contract on what the code is supposed to do. Humans cover for this gap with code review and tribal knowledge. AI agents don't. They write code, run the tests, see green, and trust the result. If the tests don't actually verify the behavior, the agent ships broken code with confidence.

"One engineer went on vacation and shipping stopped." This is knowledge silos showing up as a business risk. The same silos block AI agents — except agents don't even know who to ask. If critical context lives in one person's head and not in the repo, neither human onboarding nor agent throughput is fixable without addressing that first.

Each of these is a symptom of the same problem: your codebase assumes you'll always have the same team. AI agents — and any new humans — break that assumption.

The Mavka AI-Readiness Scorecard

We score seven signals across a codebase in 72 hours. Each one moves the needle independently. A codebase doesn't have to score perfectly on all seven to start seeing leverage — but the bottom two will usually block the top five.

1. Conventions are codified, not tribal

What it is: Your team's patterns — naming, error handling, file structure, state management — are written down or, better, enforced by linters and type rules. They are not "ask the senior."

Business symptom when missing: PRs from new hires (and from AI agents) get rewritten in code review. Productivity per engineer plateaus and your senior reviewers become the bottleneck.

Why AI needs this: Agents predict code patterns from what they see in the repo. With tribal conventions, they guess. They guess wrong.

2. Tests are the contract

What it is: Critical paths are covered by tests that fail fast and unambiguously when behavior breaks. The test suite is the spec that protects production.

Business symptom when missing: "PRs break production every other week." You hire senior engineers as a flaky-test compensation layer.

Why AI needs this: Agents verify their own work by running tests. Flaky or absent tests mean agents either ship slop with confidence or stop and ask a human to validate — defeating the leverage entirely.

3. Types are the spec

What it is: Public interfaces are typed. There's no any soup, no untyped blobs masquerading as data. A function's signature tells you what it does and what it returns.

Business symptom when missing: New features take longer than estimated because no one's sure what data is flowing where. Bugs cluster around the boundaries between systems.

Why AI needs this: Agents read types to figure out what's safe to do. Weak types force the agent to guess, and guessing is where it hallucinates.

4. Context lives in the repo, not in heads

What it is: Architecture diagrams, decision records, and component-level READMEs explain why the code is the way it is. New engineers can answer "why was this built this way" without scheduling a meeting.

Business symptom when missing: Senior engineers spend a third of their week explaining the codebase to the rest of the team.

Why AI needs this: Agents have zero organisational memory. If the "why" isn't in the repo, the agent will reinvent it — often wrong, and often expensively.

5. Modules are small and named for what they do

What it is: Files and directories have a single clear purpose. Functions are short. Boundaries between modules are explicit and visible from the outside.

Business symptom when missing: Touching one thing breaks three others. Estimates are unreliable. Refactors get postponed indefinitely because no one knows what they'll set off.

Why AI needs this: Agents work within a finite context window. A god-class doesn't fit, and even if it did, the agent can't reason about it. Small, well-named modules let the agent load exactly the surface it needs.

6. Build is fast and reproducible

What it is: A fresh checkout runs locally in minutes. Tests run in seconds. Deploy is one command. CI passes are real, not approximate.

Business symptom when missing: Engineers wait. Engineers context-switch while they wait. Velocity dies in the slow build, and nobody can quite point at where it went.

Why AI needs this: Agents iterate in tight loops — write, run, observe, fix. A twenty-minute build cycle turns a five-minute task into an hour. The leverage you bought disappears into waiting.

7. The roadmap is in the repo

What it is: Issues, RFCs, and feature specs are version-controlled and link to the code they describe. Decisions about what to build next are not buried in Slack threads.

Business symptom when missing: You answer the same "what are we building" question every standup. New engineers — and new agents — start with no plan they can execute against.

Why AI needs this: Agents can plan and execute multi-step work only if the work is described in a form they can read. A roadmap in someone's head isn't actionable. A roadmap in git is.

How we measure it — and what you get

We score these seven signals across your repo in 72 hours. The output is a one-page report: where you stand on each signal, what the business impact of the gaps is, and the top three fixes that will unlock the most velocity for your team.

It is not a refactor. It is the diagnostic that tells you whether you have a refactor problem, a process problem, or a hiring problem. Most of the time, the bottleneck you assumed was "we need to hire two more engineers" turns out to be one of these seven signals — and fixing it costs a fraction of the headcount you were about to approve.

If you're watching your engineering team get further behind every quarter — or you've watched competitors ship circles around you and can't figure out why — the answer is usually one of these seven signals.