The legacy codebase the agent couldn't read

I pointed a capable agent at a ten-year-old codebase expecting magic, and got a confident vandal instead. This is the field note on why the agent couldn't read code that I could, and what finally let it help.

The inheritance

The codebase was old, large, and effectively undocumented — a decade of decisions, workarounds, and "don't touch that" knowledge, none of it written down. I'd half-inherited it myself and was still finding my way. So I did the obvious thing: handed the agent a change and let it loose, assuming it would read the code and figure it out the way it does on my own projects.

Why the agent kept guessing wrong

It didn't figure it out. It guessed, confidently, and the guesses were wrong in a particular way. It "simplified" a gnarly date calculation — and broke a timezone fix that had taken someone a week in 2019. It "cleaned up" a redundant-looking check — which was guarding against a malformed input that still showed up in production. Every change looked like an improvement and was a regression.

The agent wasn't being stupid. It was reading the only thing available to it — the code — and the code doesn't explain itself.

The tacit knowledge nowhere in the code

That was the lesson, and it took me embarrassingly long to see. The thing the agent needed wasn't in the codebase at all. It was tacit knowledge — the why behind the weird query, the reason for the redundant check, which parts were load-bearing and which were dead. That knowledge lived in people's heads and in a couple of long-departed contributors' memories. The agent couldn't read what was never written. This is the trap every guide to agents in legacy code warns about: legacy carries knowledge the agent simply cannot reach.

Stuart Leo

The agent could read every line and still misunderstand the code, because the part that mattered was never in the lines.

Writing down what only the old hands knew

So I stopped expecting the agent to infer the unwriteable and started writing it down. Each time I worked out why something was the way it was — asking the one person who remembered, reading old tickets, archaeology — I captured it as a gotcha or a decision in a contextbase, right next to the code it explained.

The timezone fix got a note. The malformed-input check got a note explaining what it guarded. The fragile module got a "here be dragons" with the reasons.

When it finally clicked

Once the agent was reading those notes before touching that code, it stopped vandalising. It left the timezone fix alone because the note told it why. It preserved the check because the note explained the input. The same agent that had been a confident vandal became genuinely useful — not because it got smarter, but because it could finally read the reasoning, not just the code.

An agent can't read what the codebase never wrote down — the fix was capturing the tacit knowledge, not a better model.

Start here: see how to add a contextbase to a legacy project, document a codebase with an agent, or read the method.