Fair warning, this one is for the engineers. but if you’re a PM, founder, or anyone who has ever seen a “small change” turn into a 2 days fix… you might wanna keep reading. I mean I promise there is a point.
A docker-compose.override.yml, a Terraform module, and an .env.production with six lines nobody can fully explain.
It works. Nobody knows exactly why.
The person who wrote it left two years ago. And the ticket to “clean this up” has been sitting in the backlog since a sprint that no longer has a name, which is honestly poetic in a sad way.
When Nobody Knows Why
For most of my career, the cost of that file was mostly human. Slower onboarding. An extra Slack thread right before a deploy. Two hours every few months trying to remember what a flag does before someone feels comfortable touching it.
Annoying? sure, but still kinda bounded.
Eventually, someone learned the system well enough to become the unofficial config person. New engineers asked them. PMs learned which things were safe to change, and which ones needed an engineer. The team basically built a thin layer of institutional memory on top of the mess, like duct tape but for context.
But now? that cost structure is changing!
Most repositories (frankly all) now have an AI agent with read access, and increasingly, write access. Claude Code, Cursor, Antigravity, or whatever your team has standardized on.
The pitch is pretty simple, give the agent the codebase, give it a task, then watch it figure things out. And yeah, it works surprisingly well. Until it hits the thing nobody owns. Because an agent doesn’t get to skip the config file the way an engineer sometimes can.
A new engineer can ask someone in Slack:
“Why are we setting this variable here?”
The agent can’t.
It has to read the file. Then the override. Then the deployment config. Then the comment from 2022 that says TODO: remove after migration, sitting right next to code that is very clearly still load-bearing.
It has to rebuild the reason something exists from whatever evidence happens to be left behind. And every time it does that, you’re paying for the reconstruction. This is where technical debt starts looking slightly different.
The Cost of Making AI Guess
We have always talked about messy systems in terms of engineering hours. Onboarding takes longer. Changes are riskier. Debugging takes longer but AI adds another cost to the equation. The ambiguity consumes compute.
A clean, well-structured module might take an agent a few hundred tokens to understand. But a tangled system with duplicated configuration, contradictory comments, unclear ownership, and three different ways of doing the same thing can require 10x the tokens just to get enough context to make a change safely. And unlike the engineer who has seen the system 40 times, the agent doesn’t get that “familiartity discount”.
The sad part? Next session, it starts reconstructing the world again. It gets more interesting… The risky part isn’t that the agent gets confused. It’s that it usually doesn’t stop there. It produces something.
Maybe it adds another environment variable instead of fixing the existing one.
Maybe it creates another configuration layer because that feels safer than changing what it can’t confidently explain.
Maybe it keeps a weird abstraction around because it assumes there must be a reason for it.
The patch might be totally reasonable, given what the agent saw. It might also make the whole system slightly worse?!
And that is the piece i think we’re still underestimating.
AI doesn’t remove the cost of ambiguity. It can make ambiguity cheaper to reproduce. A human engineer seeing weird configuration might think:
“This makes no sense. I should find reasons or atleast discsuss this with team”
An agent is more likely to think:
“Given the evidence available, this is probably the safest change.”
Those behaviors aren’t the same. And six months of small, reasonable changes around unclear systems can leave you with two config files nobody owns, instead of one. And the iron? The agent has to understand both.
This isn’t just an engineering problem
This matters for PMs too.
When a team says, “That change is harder than it looks,” there’s often a temptation to treat it like engineering friction.
And frnahly, Sometimes it is.
But sometimes the difficulty is a symptom of the system itself. If changing a seemingly small product behavior means tracing five different layers, digging up an old feature flag, figuring out a variable named after a service that is no longer being used? and remembering why something was deliberately left in place… then that complexity is part of the product’s cost.
It shows up in estimates.
It shows up in delivery risk.
It shows up in how confidently a team can respond to a customer.
And now it shows up in how well AI can help the team work, period.
This creates a slightly awkward implication for product teams.
Some technical debt isn’t really competing with product work the way we’ve historically described it. It might actually be infrastructure for future product velocity.
Removing a duplicate configuration path might not ship a customer-facing feature. But if it turns a two-hour investigation into a fifteen-minute change, it changes what the team can do for every future feature.
Same thing with ownership too. “Who owns this?” sounds like an engineering question until nobody can answer it during a production incident, or during a customer escalation. Ownership is product infrastructure, not just code hygiene.
Legibility becoming a form of leverage
So yeah, this is why I’m getting less interested in the usual argument for cleaning up technical debt.
It isn’t about making the codebase beautiful.
It isn’t even primarily about DX (developer experience
It’s about making the system legible.
AI agents are great at operating on systems they can build a reliable model of. They’re much less useful when the repo has layers of historical decisions that only exist in people’s heads.
The things that make a system easier for LLMs to understand are, conveniently, the same things that make it easier for the rest of us to work in:
One source of truth per concern.
Clear ownership boundaries.
Configuration that has an obvious home.
Comments that explain why something exists, not just what it does.
Old migrations actually removed.
Dead flags actually deleted.
These are boring practices. I know, I know, customers might not notice a brand new thing in this release, but here’s a soft reminder that it was good practice before AI too. The twist in the tale is that now we’ve got another consumer of the system’s structure, and that consumer is literally reading everything.
For years, a messy codebase could survive because a few really senior engineers carried the whole context around in their heads. That was already costly, even then.
Now we’re asking LLMs to operate in that same setup. They don’t come with the institutional memory, they just have the repository. So if you gave an AI agent access to the codebase and it feels slower, more hesitant, or weirdly willing to make changes that are technically fine but kind of questionable, I’d check the system first, before blaming the model.
There may be a config file nobody has owned for two years.
The next time an agent struggles with a change, follow the confusion. Find the file it keeps coming back to. Find the decision nobody can explain. Find where it had to guess.
Then fix that.
Not for the AI. For everyone who has to work in that codebase after you.
That’s all folks!
DevNama is about tech research, product growth, developer productivity, and engineering excellence. Subscribe now to stay in the loop!
If you know someone who might like this read, consider sharing it with them:
Thanks for reading!
— Ibtihaaj