Inheriting a Dev Project: How to Not Blow It in the First Two Weeks

At Rock Agile, we do this a lot. Someone hands us a codebase they didn't write. The original developer is gone. The documentation is stale. The tests may or may not run. The business owners want progress soon, ideally last week. This is one of the specific things we're hired for, and after years of doing it, I've learned there's a shape to the work that keeps you out of trouble.

The shape has one non-negotiable at the front: you have to check yourself before you touch anything.

Start with your mindset, not the code

Developers are naturally judgmental. We look at somebody else's code and our first instinct is to see what's wrong with it. Sometimes the code deserves the judgment. More often, we're just missing context the original developer had, and our judgment is going to blind us to what the code is actually doing.

There's a Henry Ford story I keep coming back to. Ford would take job candidates to dinner. If they seasoned their food before tasting it, he wouldn't hire them. He wasn't afraid of change, he changed things constantly, but he wanted leaders who would understand what was on the plate before they started rearranging it.

The principle transfers to software. Understand what the code is doing, and why, before you decide it's wrong. Prejudgment on an inherited codebase is the single most common mistake I see, and it usually looks like premature refactoring or optimization on parts of the code we haven't earned the right to change yet.

Curiosity works better than judgment. Come in expecting to be surprised by what you find.

Understand what the software is supposed to do

Before you dig into how it works, understand what it's for.

The best case is a product owner who can walk you through the business logic. If you have them, use them. Ask why the software exists, what problem it was originally built to solve, and how that problem has evolved. Understand the constraints that shaped the original architecture, even the ones that no longer apply.

If the product owner isn't available, the next best source is any developer who worked on it before. Ask what was tried, what worked, what didn't, and what problems keep coming back. Repeated bugs and repeated attempts to fix the same thing usually point to something structural that the previous team knew about but couldn't get to.

If nobody is available, the code has to teach you. That's slower, but not impossible.

Get a working environment before anything else

Before you form opinions about the code, get it running. Bootstrap it. Run the tests. Click through the features. Take notes on what works and what doesn't. Test in multiple environments if you can. Differences between platforms are often where the most interesting bugs live.

The specific move I make early on a Rails inherited project: find the biggest files. That's usually where the core domain lives, or where things went wrong. Read the dependency graph next. The Gemfile tells you what problems the original team decided to outsource, and outsourcing decisions age faster than internal code.

Set a timer on rabbit holes. Early in my career I gave myself five minutes on any tangent while getting a new project running. That habit still runs in the background now. I'm faster at recognizing which threads are worth pulling and which aren't. It's a discipline worth building.

Work with the existing decisions before you change them

Now you know what the software is for and how it runs. Only now should you start considering changes.

Software development is trial and error, and it's a lot more of an art than most engineers admit. My rule for inherited projects is to prioritize working with the previous team's choices before replacing them. Sometimes the choices are wrong (plenty of them will be) but you'll spot the actually-wrong ones faster if you're not fighting the whole codebase at once. And sometimes what looked wrong at first glance turns out to have been the right call for constraints you didn't know about.

When you do start making changes, keep them small and reversible. The goal in the first weeks is to build enough understanding of the codebase that you can commit to bigger changes with confidence.

Take notes obsessively

I cannot overstate this. Write down what you tried, what worked, what didn't, and what confused you. This is partly for your future self: a month from now, when something breaks, you'll want to know what you were thinking today. But it's also for whoever comes after you. Somebody will inherit this project from you eventually. The notes you take now become the documentation they'll wish existed.

Share your findings

Software isn't a solo sport. Share what you've learned with the client, with your team, with anyone else who touches the system. Other people will see things you missed. That's what makes the process work.

The through-line

The pattern is: discovery before decisions. Every step above is really about earning the right to change the code. The developers who blow up inherited projects skip the discovery. They come in confident, refactor too much too soon, and then can't tell whether their changes broke something existing or exposed a bug that was always there. The developers who inherit projects well are the ones who move slower at the start and faster later, because by the time they're touching things aggressively, they know what they're touching.

---

If you're looking at a legacy codebase you inherited, or one your team inherited, that's the kind of work we do. We come alongside your team, do the discovery work, and either help you build on what's there or rescue what needs rescuing. If that sounds relevant, get in touch.