Your Legacy Codebase Is Not AI-Ready Just Because You Bought an AI Coding Tool

The AI coding conversation is getting more realistic.

The early story was simple: give a tool like Claude Code, Cursor, Devin, Replit Agent, Lovable, or another coding agent a task, and it will generate software faster than a human team could do alone.

That story is not completely wrong. AI-supported development can be genuinely useful. It can help with prototypes, tests, refactors, documentation, migrations, internal tools, and repetitive implementation work.

But the more interesting discussion on X right now is about a harder problem:

Why do AI coding agents often look impressive on greenfield projects and then become much less reliable inside real, older codebases?

That question matters for serious companies.

Most valuable software is not a blank repository. It is a product with customers, edge cases, business rules, integrations, permissions, old migrations, operational habits, and years of decisions that were never fully written down.

If a team buys an AI coding tool and points it at that environment, the tool has not entered a clean engineering lab. It has entered a living system.

And living systems need context.

The issue is not only the model

One current thread around Claude Code put the point bluntly: the problem is often not the model, but the architecture around the work.

That is the right frame.

When an AI agent fails inside an existing product, the obvious reaction is to blame the tool. Sometimes that is fair. Models still make mistakes. They miss details, overfit to nearby files, invent patterns, remove important edge cases, and confidently change things they do not understand.

But in many real codebases, humans struggle for the same reason.

The architecture is unclear. The domain language is inconsistent. The setup instructions are outdated. Tests cover the happy path but not the business risk. Important behaviour lives in a service nobody wants to touch. A senior engineer knows why a strange condition exists, but that explanation is not in the code, tests, documentation, or issue tracker.

An AI agent cannot reliably respect knowledge that the organisation has never made explicit.

That is why “AI-ready” is not mainly a tooling label. It is a property of the software system.

A codebase becomes AI-ready when a competent agent, under human supervision, can understand the task boundary, inspect the relevant context, run the right checks, and propose a change that reviewers can evaluate without archaeology.

That is not magic.

It is maintainability.

Greenfield demos hide the real difficulty

AI coding tools shine in greenfield demos because greenfield projects are forgiving.

There is no existing customer data model to preserve. No legacy integration with a supplier portal. No hidden permission rule for one important account type. No years of inconsistent naming. No deployment process that depends on a manual step. No sales commitment that explains why the “wrong” behaviour is actually deliberate.

In a clean demo, the tool can create the architecture as it goes.

In a real product, the architecture is already there, even if nobody likes it.

That difference changes everything.

In a new repository, an agent can create a dashboard, API route, database schema, and test suite in one coherent pass. In a ten-year-old system, the same request may require understanding old data, a billing edge case, a role model, a migration path, and the reason the previous team avoided a simpler implementation.

The agent may still produce code.

The question is whether the code belongs in the product.

For founders, CTOs, and product owners, this is the practical dividing line. AI does not remove the need to understand the system. It increases the value of making the system understandable.

Technical debt becomes an AI adoption blocker

Technical debt used to be mostly an internal engineering complaint.

It slowed delivery. It made changes harder. It increased onboarding time. It raised incident risk. But because customers could not directly see it, it was easy to postpone.

AI changes that calculation.

When a codebase is messy, an AI agent can generate more messy code faster. It can repeat local inconsistencies, copy outdated patterns, add dependencies where a platform abstraction already exists, or miss the one test that would reveal the real risk.

The result is not always catastrophic. More often, it is subtle:

pull requests become harder to review;
small changes touch too many files;
generated code looks plausible but ignores domain rules;
reviewers spend more time explaining context than evaluating solutions;
teams stop trusting the agent and return to manual work;
the organisation concludes that AI “does not work for us.”

Sometimes the tool is the wrong fit.

But often the codebase is simply not ready to give the tool useful context.

This is a more constructive diagnosis, because it creates a path forward. The answer is not to wait for perfect AI. The answer is to make the software easier to work with.

That helps humans immediately and agents later.

What makes a codebase agent-ready?

An agent-ready codebase is not a perfectly modern codebase. That bar is unrealistic and usually not worth chasing.

It is a codebase where change is legible.

That means a developer, reviewer, or AI agent can answer basic questions without guessing:

where does this business rule live?
which module owns this responsibility?
what is the safe way to run the system locally?
which tests prove the important behaviour?
what data can be used in development?
which dependencies are approved?
what must never be changed without review?
where are architecture decisions recorded?
how does a change move from branch to production?

These are ordinary engineering questions. AI adoption simply makes them urgent.

At McDougall Digital, this is how we think about AI-supported development for serious products. The goal is not to make the team dependent on a specific tool. The goal is to create a delivery environment where good tools can help without turning the product into a pile of unreviewable guesses.

Start with maps, not rewrites

Many teams hear “legacy codebase” and immediately imagine a large rewrite.

That is usually the wrong starting point.

A rewrite may be necessary in specific cases, but most AI-readiness work should begin with mapping, not replacing.

The first useful step is to make the existing system visible:

the main modules and their responsibilities;
the data flows that matter;
the integrations that carry business risk;
the parts of the codebase that change often;
the areas nobody understands well;
the manual deployment or support steps;
the tests that protect important behaviour;
the missing tests that make changes risky.

This map does not need to be a 90-page architecture document. In fact, it should not be.

For AI-supported delivery, short and current beats long and ceremonial. A few precise documents, kept close to the code, are more useful than an old architecture deck nobody reads.

The best documents are operational:

“How orders move through the system”
“Where permissions are enforced”
“How to run billing changes safely”
“Known dangerous areas”
“Testing expectations for customer-facing changes”
“Architecture boundaries for agents and humans”

These documents help a new engineer. They help reviewers. They help product owners understand risk. They also give AI agents better context.

Add characterization tests before ambitious agent work

One of the safest ways to prepare an old system for AI-assisted development is to add characterization tests.

A characterization test does not claim the current behaviour is beautiful. It records what the system currently does, especially around important business rules and edge cases.

That matters because many legacy systems contain behaviour that looks strange but exists for a reason.

Maybe a discount calculation handles one old contract. Maybe an import process accepts malformed data because a partner system has sent it that way for years. Maybe a permission rule exists because of a past incident. Maybe a manual support workflow depends on an awkward status transition.

If none of that is tested, an AI agent can remove it while “cleaning up” the code.

The agent may even improve readability.

And still break the business.

Good tests give the team a boundary. They allow agents to propose changes while giving reviewers a better signal about what changed. They also make refactoring less political, because the discussion moves from “I think this matters” to “this behaviour is protected.”

Bound the agent’s task

AI coding agents work better when the task is bounded.

“Improve our onboarding flow” is too broad for an existing product.

“Add a required company-size field to the onboarding form, persist it on the account profile, update the admin display, and do not change billing logic” is much better.

For real codebases, task boundaries should include:

the intended product outcome;
the files or modules likely in scope;
the areas explicitly out of scope;
the tests that should be added or updated;
the data and credentials the agent may use;
the review rules for generated changes;
the rollback or release considerations.

This may sound slower than simply asking the agent to start.

In practice, it is faster.

Unbounded agent work creates review debt. Bounded work creates usable output.

The same principle applies to tool permissions. An AI agent does not need access to everything just because it can write code. Existing products should use isolated branches, development data, least-privilege credentials, and clear approval rules for dependency, migration, infrastructure, and security-sensitive changes.

AI-readiness is not only documentation.

It is operational control.

Product judgement still matters

There is a tempting fantasy in AI coding: if the model becomes good enough, product judgement becomes less important.

The opposite is more likely.

As implementation gets cheaper, the cost of choosing the wrong change becomes more visible. A team can generate five versions of a feature, but someone still has to decide which one fits the product, the customer, the architecture, and the business.

In a legacy codebase, this judgement is especially important because the system carries history.

Not every old pattern is bad. Not every inconsistency should be fixed immediately. Not every module deserves investment. Not every AI-generated cleanup is worth the risk.

The useful question is not “can the agent change this?”

The useful question is:

Should this change exist, and what must be true for it to be safe?

That is where experienced product and architecture work matters. AI can accelerate implementation, exploration, and review preparation. It does not take responsibility for the product.

A practical first roadmap

For a team with an existing product, a sensible AI-readiness roadmap could look like this:

Pick one bounded area of the product where change is frequent and risk is manageable.
Map the current architecture and business rules for that area.
Fix local setup so the system can be run and tested reliably.
Add characterization tests around the behaviours that matter.
Document the task boundaries and review rules for AI-assisted work.
Use agents on small, supervised tasks first.
Track where review time goes: missing context, bad tests, unclear ownership, dependency risk, or product ambiguity.
Improve the system based on those findings before expanding to higher-risk areas.

This is not glamorous.

It is effective.

It turns AI adoption from a tool purchase into a maintainability programme with immediate business value.

Even if the preferred coding tool changes next quarter, the work still pays off. Better tests, clearer architecture, cleaner setup, and explicit domain knowledge improve delivery regardless of the model.

The real opportunity

The current X discussion is useful because it moves past the shallow question of whether AI can write code.

Of course it can write code.

The serious question is whether your organisation can give AI enough context, boundaries, and review structure for that code to become dependable product work.

For many teams, especially in the German market, the biggest opportunity is not replacing developers with agents. It is using AI adoption as pressure to finally make important software easier to understand, change, and operate.

That is a much better investment than chasing every new tool announcement.

McDougall Digital helps teams do exactly that: assess where AI-supported development can safely create leverage, clean up the architecture and delivery paths that block it, and turn existing products into systems that both humans and agents can work on with confidence.

The companies that benefit most from AI coding will not necessarily be the ones with the most aggressive prompts.

They will be the ones with the clearest systems.