Can AI actually work in your company's software? It's an audit question now

Whether an AI agent can work in your systems has become an audit question. Two years ago it wasn't one at all.

Earlier this year I was asked to evaluate a company's web estate, scoring it against the usual columns: performance, security, maintainability, cost. This time there was a new column, and it ended up mattering more than most of the old ones: can an AI agent actually work here?

For a decade-old WordPress estate built on a visual page-builder and thirty-odd plugins, the answer was no. The content lived in shortcode soup inside a database. The logic lived in plugins that generated markup nobody had ever read. One plugin existed purely to make certain screens responsive inside a webview, which in 2026 is a quality any decently written front end has for free. When I pointed capable AI tooling at the estate, the same tooling that writes production code for me every week elsewhere, it had nothing to hold on to.

Could it have been forced? Probably. With enough scaffolding (custom retrieval layers, hand-written maps of plugin behaviour, careful guardrails) you can get an agent limping along in almost anything. But scaffolding like that is expensive to build and brittle to maintain, and the time is better spent making the system legible, which improves life for every human and every tool that touches it afterwards. That was the recommendation.

So "AI-hostile codebase" went into the audit as a first-class pain category, sitting alongside missing error tracking, and I meant it every bit as seriously.

In brief

• "AI-hostile" is a scoreable property of software: an audit can tell you whether AI agents can work in your systems at all.
• Agents work by reading your code, configuration, documentation and naming. A system too illegible for agents is already slowing down the humans who work in it.
• Making software AI-friendly is ordinary engineering applied incrementally — clear boundaries, honest naming, real documentation — not a rewrite.
• Two companies with identical headcount are no longer equivalent when one can delegate real work to agents and the other can't.

What AI-hostile means

Modern AI tools, the ones your engineers are already using whether you've sanctioned them or not, work by reading your systems. They read code, configuration, documentation, naming. When those are consistent and self-describing, an agent can navigate them much the way a good new hire does, except it takes minutes rather than months.

The best way I know to picture legibility is a building. In a legible system there are corridors, signage, rooms that are what the door says they are. In an illegible one, half the rooms are reached through crawlspaces that one former contractor knew about, and the wiring runs through walls nobody has opened in years. People can still work in the second building. They just work slowly, carefully, and only in the rooms they trust.

An agent in that second building doesn't work slowly. It doesn't work at all. The failure modes are recognisable from any due-diligence exercise: behaviour that lives in a database instead of in code, the same concept carrying five different names, documentation that exists only in a departed contractor's memory, markup generated by tools nobody has looked inside.

The detail that should get a CEO's attention is that your people are in the same building. Slow onboarding, fragile releases, "don't touch that module" folklore: these are the human symptoms of the same illegibility, and behind each one is a specific person, the developer who inherits the system next, working carefully in the rooms they trust. That cost was always on your books, spread thin enough to ignore. What has changed is the size of the consequence. A legible codebase used to make your team perhaps 20% faster. Now it decides whether an entire class of tooling works for you at all, which means two companies with identical headcount are no longer remotely equivalent when one of them can delegate real work to agents and the other can't.

This is not a rewrite pitch

The lesson from my work on a large health platform this year is that AI-friendliness is mostly old virtues with a new payoff, applied incrementally. Some examples, straight from the ticket history.

One ticket asked us to refactor a core feature "to be friendly and optimised for both humans and agents". That's the actual wording, and it describes a restructure rather than a rewrite: clear module boundaries, consistent naming, behaviour in code rather than in someone's head. Human reviewers got through it faster, and agents can now extend it safely.

Another produced a component registry that doubles as a map for agents. A single, boring, machine-readable file describing what components exist and how they relate, so any tool or new developer landing in any of our codebases can orient itself without archaeology.

And an AI code review caught a release-breaking omission that several humans, me included, had looked straight past. A file everyone assumed was deployed had never been included, and I held the release overnight on the strength of the flag. The tool could tell something was missing because the surrounding code was structured well enough to show what should have been there.

None of it required new philosophy, and I find that reassuring rather than disappointing. Clear structure, real documentation, honest naming and tests were always how you looked after the people who inherit your systems. The same care now extends to the agents working alongside them, and it pays out both ways.

Questions worth asking your team

You don't need to read code to find out where you stand.

Ask your team what an AI agent could safely do in your codebase today, and where it would get lost. Ask which parts of the product nobody fully understands any more. And when you evaluate a platform, a plugin or an agency's deliverable, ask whether anyone has checked how legible it is to an agent, because the price of anything you buy includes every change that will ever need making to it.

If the answers are shrugs, that tells you where you stand too. None of the fixes are moonshots, either; in my experience the returns arrive quickly because most of it is work the codebase needed anyway.

Mobile-friendliness followed this same path fifteen years ago, and "invisible to Google" before that: a novelty concern that became a standing requirement. Agent-legibility is doing it now. The teams that treat it as ordinary engineering, while it still is ordinary engineering, will barely notice the transition. That's rather the point.