Inheriting a Messy Codebase: A 90-Day Plan

The previous team is gone. The documentation is a README that describes a system that no longer exists. There are three deployment scripts and nobody knows which one is real. And you have been asked, by Friday, to add a feature.

Inheriting a messy codebase is one of the most common situations in software, and one of the most badly handled. The instinct is to either freeze—too scared to touch anything—or to declare the whole thing garbage and pitch a rewrite. Both are wrong. There is a disciplined middle path, and it fits in ninety days.

The goal of these ninety days is not to make the code beautiful. It is to convert fear into control.

Days 1–30: Understand Before You Touch

The single biggest mistake with an inherited codebase is changing things before you understand them. The first month is for building a map, not for improving the territory.

Get It Running Locally, Reproducibly

Before anything else, you must be able to run the system from a clean machine following written steps. If it takes you three days and undocumented tribal knowledge to get it running, that is your first finding and your first fix. Write down every step as you go. A codebase you cannot reliably start is a codebase you cannot safely change.

Trace the Critical Paths

Do not try to read every file. Pick the two or three flows that make the business money—the signup, the checkout, the core transaction—and trace each one end to end, from the request that arrives to the database rows that change. Draw them. These paths are where risk lives and where your understanding will pay off first.

Find the Landmines, Don’t Defuse Them Yet

As you explore, keep a running list: the hardcoded credentials, the function that everything depends on, the part everyone warned you about. Resist the urge to fix them now. You are cataloguing risk, not remediating it. You do not yet know enough to change safely.

By day 30 you should be able to run the system, explain how it makes money, and name its scariest parts. That is control beginning to form.

Days 31–60: Build a Safety Net

Now that you understand the system, you make it safe to change. This month is about instrumentation and tests—the equipment that lets you work without holding your breath.

Add Tests Around What You’re About to Touch

You will not achieve full test coverage on an inherited codebase, and you should not try. Instead, add characterisation tests around the specific areas you need to modify: tests that capture what the code currently does, so that when you change it, you know immediately if you broke something. This is the seatbelt you fasten before driving.

Make the System Observable

If a request fails in production right now, can you tell why? On most inherited systems the answer is no. Add structured logging to the critical paths, wire up basic error tracking, and put a simple dashboard on the metrics that matter. You cannot fix what you cannot see, and inherited systems are usually flying blind.

Fix the Deployment Story

Sort out which deployment script is real, document it, and ideally automate it so that shipping is boring and repeatable. A scary, manual, once-per-quarter deploy process is where inherited codebases go to rot, because nobody dares release, so fixes pile up. Making deployment safe unlocks everything else.

Days 61–90: Ship Value and Pay Down Debt Deliberately

With understanding and a safety net in place, the final month is about delivering the feature you were asked for—and using that work to leave the code better than you found it.

Ship the Feature Through the Safety Net

Now you deliver. Because you have tests around the area, observability on the paths, and a reliable deploy, the change that felt terrifying on day one is routine. You ship, you watch the dashboards, and nothing catches fire. That is the whole point of the previous sixty days.

Refactor Only Along the Way

The temptation, once you feel confident, is to launch a grand cleanup. Resist it. Refactor only the code you are already touching for a real reason—leave each area a little cleaner as you pass through it. This “improve as you go” discipline pays down debt steadily without the enormous risk of a big-bang rewrite that delivers no new value.

Write the Document You Wish You’d Had

Finally, write down what you learned: how to run it, the critical paths, the landmines, the deployment process. Not a novel—a page or two that means the next person, possibly you in six months, does not start from zero.

The Rewrite Trap

At some point in the first month you will be certain the whole thing should be rewritten. Almost always, this is a mistake. A rewrite discards not just the messy code but every hard-won fix and edge case buried in it, and it stops all new value for months while you rebuild things that already worked. The messy code is ugly, but it encodes real business knowledge. The ninety-day plan lets you tame it in place, keep shipping, and only rewrite the specific pieces that genuinely deserve it—if any.

Inherited chaos is not a verdict on your abilities. It is a starting position. Understand, make safe, then improve—in that order.

---