Inheriting a Codebase You Did Not Write

From the team behind aidrop.it — one workspace to build, host, and keep changing your code.

Somebody leaves. A contractor finishes. A side project turns out to matter. However it happens, you now own code you have never read, and the person who could explain it is not answering.

The instinct is to read it end to end. That is the slowest possible start and it rarely survives contact with the first urgent bug.

A better opening is to establish four things before changing anything: what still runs, what is still true, what is load-bearing, and what nobody should touch yet. An agent is genuinely useful here — but only if you ask it to map the territory rather than to fix things.

Start with what runs, not with what is written

Documentation describes intent at the moment it was written. The running system describes reality now. When they disagree, the running system is right and the document is a historical note.

So the first pass is behavioural. What are the entry points? What does the application talk to — a database, a queue, a third-party API, a cron? What breaks if each of those is unavailable? A dependency you discover by reading is a guess; one you discover by tracing a request is a fact.

Only then read the code, and read it in the order the request travels. Alphabetical file order teaches you nothing about the system's shape.

An agent maps faster than it fixes

Point an agent at an unfamiliar repository and ask for a change, and you get a plausible patch built on assumptions you cannot see. Ask it to describe the system instead, and you get something checkable. Before connecting it, scope its access to the project you are taking over and review the credentials left by the previous maintainer.

Useful questions have verifiable answers: which modules import this one, where is this table written, what happens on failure here, which of these two paths is dead. Each answer can be confirmed in the code, which means a wrong one is caught rather than merged.

The trap is asking for opinions too early. "Is this well structured?" produces confident prose. "What calls this function?" produces a list you can check — the same discipline that keeps an agent's procedure repeatable applies to reading as much as to writing.

Write the map down while it is still surprising

Everything you learn in week one is obvious to you by week four and lost by week twelve. The moment of maximum value for a note is the moment you are still confused by the thing it describes.

Capture three kinds of finding as you go:

• What surprised you. The unexpected coupling, the config that is not where config lives, the workaround with no comment. These are the sharp edges the next person will also cut themselves on.
• What you confirmed and how. "The retry is not idempotent — reproduced on 2026-08-14." A finding with evidence is reusable; a finding without one gets re-litigated. The same standard applies to what the system writes down about itself — see when the log is all you have.
• What you decided not to touch, and why. Otherwise it looks like an oversight and someone helpfully cleans it up.

This is the same record an agent needs on its way in, and it pays for itself the first time a second person — or a second session — starts from it instead of from zero.

Change one thing, deliberately, early

The fastest way to learn where the mines are is to make one small change and ship it properly. Not a refactor — a real, boring, user-visible change, taken all the way through whatever passes for a release here.

That single trip surfaces what no reading reveals: how it is built, what the deploy actually does, what nobody has run in a year, and whether anyone finds out when it breaks. It also makes you someone who has moved the system rather than someone who has read it.

FAQ

How long should the mapping phase take? Days, not weeks, and it should end the moment you can predict what a change will break. Perfect understanding is not the goal; safe movement is.

Can I just have an agent rewrite it instead? Rarely a good trade. A rewrite discards the undocumented behaviour that real users depend on — which is precisely the part nobody wrote down.

What if there are no tests? Add one before your first change, around the behaviour you are about to touch. It is a way of writing down what "working" means, at the point where you finally know.

How do I keep what I learn from evaporating again? Put it where the next reader and the next agent both look, versioned so a correction leaves a trail. That is the problem aidrop.it exists to solve — a project's context outliving the session that discovered it.

Is an unfamiliar codebase different from a legacy one? Only in age. The problem is the same: behaviour whose reasons were never recorded.

Cover: https://unsplash.com/photos/Q9y3LRuuxmg by Maksym Kaharlytskyi on Unsplash. Alt text: An open drawer of an old filing cabinet, packed with handwritten index cards someone else catalogued.