# Your First Week With an Inherited Messy Codebase

> How to get your bearings in an inherited messy codebase without breaking production: run it locally, map it, find what's actually used, ship one safe change.

Published: 2025-04-10 · Source: https://subxcat.com/articles/messy-codebase-first-week · Author: SUBXCAT

You've inherited a project. A freelancer, an agency or an AI assistant with someone at the wheel built it, there are no docs, and there are already users. Getting your bearings in an inherited messy codebase within a week is realistic, as long as you don't try to read all of it. Reading code file by file is like learning a city from its street index. You need to walk it.

The rule for week one: you don't improve anything. You look, take notes and run things. Changes to production only if something is on fire.

## Day 1: run it locally

Until the project runs on your machine, everything else is guesswork. Clone the repository and try to start it the way a newcomer would. Write down every step where you got stuck: which Node or Python version it wants, which environment variables, where the keys come from, which database to create.

Two things matter immediately:

- Your local copy must not point at the production database. If `.env` contains the production database URL, swap it for a local or test one before the first run.
- Email, payments and other external services should be in test mode or switched off locally. Otherwise one click on "send" reaches real people.

By the end of the day you should have a running project and a rough guide to starting it. That's already more than existed before.

## Day 2: draw a map

Now go top-down. Open the folder structure and answer these questions:

- where the entry point is: what starts first;
- where the routes are: which pages and API endpoints exist;
- where the data model is: tables, schemas, migrations;
- which external services are called, and from where.

A useful trick is to list the database tables and, next to each, note which files read and write it. Project search (`grep -rn "orders"` or your editor's search) gets you there faster than reading. You'll end up with a rough one-page diagram. It will be wrong in places, which is fine; you'll correct it as you go.

An AI assistant helps here: ask it to describe what a folder or module does. Then check every claim against the code, because it will confidently describe things that aren't there.

## Day 3: walk the main flows

Pick the three or four actions people use the product for: sign-up, purchase, creating the core thing. Do each one in the UI and trace the request through the code alongside: button, handler, API, database, response.

This is where it becomes clear which parts are alive and which are just lying around. Note the oddities: permission checks only in the UI, a price that arrives from the browser, two nearly identical handlers. Don't fix anything yet. Just the list.

## Day 4: find what's actually used

In projects that grew fast, a noticeable share of the code is unused: old pages, abandoned experiments, three versions of the same component. To tell living code from dead:

- check server logs and analytics for which routes get called and which don't;
- search the whole project for usages of a function or component;
- look at a file's git history: when it was last touched and why;
- ask whoever came before you, if they're still reachable.

Delete nothing. Just mark it in your notes as "looks unused, verify".

## Day 5: first safe change

If there isn't one already, set up a separate test environment where you can deploy a change and look at it without touching users. Then make one small, obviously safe change, like fixing a typo in copy or updating a comment, and take it all the way to production.

The point isn't the change, it's testing the process: how the project builds, how it ships, how to roll back. Better to learn that a deploy takes forty minutes and needs a manual step while fixing a typo than during an urgent fix on Friday evening.

## The inherited messy codebase, one week later

A working local copy, instructions for running it, a one-page map, the main flows with their paths through the code, a list of suspicious spots and a tested deployment path. That's the foundation for a README and for deciding what to fix first.

## In short

- You understand an inherited messy codebase faster by running it and walking flows than by reading files in order.
- First, cut your local copy off from the production database and live services.
- Map the entry point, routes, tables and external services on one page.
- Tell living code from dead with logs, usage search and git history, but don't delete anything yet.
- Your first change should test the deployment process, not the code.

If you want a second pair of eyes on a project you've inherited, SUBXCAT does this kind of walkthrough with your team.