The first thing an inherited codebase needs is not improvement — it's a map. Until someone can say what the system is, what it talks to and where the risk sits, every change is a guess, and the temptation to rewrite is really just a way of avoiding the reading.
When a developer looks at an unfamiliar codebase and recommends starting over, they're often being honest about their own position rather than about the code. Reading someone else's system is slow, unglamorous work, and rewriting is more predictable to estimate.
But the existing code, however ugly, encodes years of small corrections — the edge case someone hit in month three, the workaround for a provider's undocumented behaviour, the validation added after a support ticket. A rewrite discards all of it and rediscovers it one incident at a time.
What services exist, what they talk to, which third parties are load-bearing, and what would happen if each one went away.
The schema, what's actually populated versus vestigial, and which tables are touched by something on a schedule.
Auth, payments, migrations, anything with a cron. Every inherited codebase has a handful, and knowing them changes how everything else is approached.
Usually the least documented part, and often the thing that's actually blocking you.
Effort spent on the left column buys very little. Effort on the right prevents incidents.
Yes. I start by understanding the system before changing anything — dependencies, data model, auth, deployment, and the parts that are load-bearing. Then I’ll tell you what I found before I start editing.
Usually not. Rewriting is the most expensive option and it’s rarely the one the code actually calls for. I’d rather find the specific things that are broken and fix those.
Less than you’d think. A repository or a deployed URL, some idea of what’s broken, and access to whatever is failing — logs, the hosting dashboard, an error message. If you don’t have all of that, send what you do have and I’ll tell you what else I need.
The service
You've inherited something — from a contractor, a co-founder, a previous team, or an AI session six months ago. It runs, mostly. Nobody can tell you how, and everyone is nervous about touching it.
Working is not production ready. Twelve checks: backups, authorization, secrets, error visibility, rate limits and rollback — and what each costs if skipped.
Read
10 min read
Inherited code nobody understands? A five-day method: map it before changing it, find the load-bearing parts, then decide what to touch and what to leave.
Read
9 min read
Sometimes it needs an engineer.
Send the messy version. That’s usually the useful version.