Add a contextbase to a legacy codebase

Everything written about building with agents assumes a clean start. Real work usually isn't — it's a codebase that's been alive for years, with undocumented decisions, load-bearing workarounds, and knowledge that lives only in the heads of whoever's still around. Point an agent at that and it confidently misunderstands, because the code is all it can read, and the code doesn't explain itself.

The fix is a contextbase — but you don't build it the way you would for a new project. You grow it into the legacy, incrementally, where the work is. Here's how.

Why legacy breaks agents (undocumented everything)

A greenfield project's context is small and fresh in your mind. A legacy codebase's context is enormous and mostly gone — retired in someone's head, lost to turnover, never written down. The code records what it does, never why.

That "why" is what an agent most needs and least has. Why is this query structured so oddly? (It's working around a bug fixed three years ago.) Why does this module avoid that library? (A licensing call nobody remembers.) The agent can't see any of it, so it treats the workaround as a mistake and "fixes" it — reintroducing the original bug. Brownfield codebases break the usual assumptions precisely because legacy behaviour and contracts are rarely documented.

Don't document it all — start where you're working

The instinct is to launch a big documentation project — map the whole system before letting an agent touch it. Don't. It's enormous, it's boring, most of it you'll never need, and it'll be stale before it's finished.

Instead, start where you're actually working. The module you're about to change is the module worth understanding and capturing first. Document the change you're making, not the system you inherited.

Stuart Leo

Don't document the whole legacy codebase. Document the part you're touching — and let coverage grow toward the parts that matter.

This keeps the effort proportional to the value. The well-trodden paths get a contextbase fast — the dead corners nobody touches stay undocumented, which is fine, because nobody touches them.

Capture decisions and gotchas as you touch code

The mechanism is the same one that powers a fresh contextbase, just applied as you go:

• When you (or the agent) work out why something is the way it is, write it down as a decision.
• When you hit a trap — the workaround, the fragile bit, the surprising behaviour — write it down as a gotcha.
• When you change something, leave a session brief so the next session inherits what you learned.

Each one is a piece of the tacit knowledge made explicit — and the agent reads it before it next touches that code, so it stops misunderstanding.

Let the agent help write it

You don't have to write all this yourself. The agent that just explored the module to make a change can draft the explanation — what this part does, how it connects, what's notable. You review and correct it (the agent will misread intent in places), then commit it. That's how you document a codebase with an agent: it drafts, you verify, the contextbase grows.

The contextbase grows with the work

Do this for a few weeks and something quietly shifts. The parts of the codebase you work in most have a contextbase. The agent stops reintroducing old bugs because the gotchas are written down. New people onboard to those areas in hours. And you never ran a big documentation project — the context accreted around the work, exactly where it pays off.

You don't document a legacy codebase all at once — you grow a contextbase one change at a time.

Start here: see how to document a codebase with an agent, the field note on a codebase the agent couldn't read, or read the method.