How to Take Over a Client's Existing Codebase with Claude Code

What Taking Over an Existing Codebase Actually Means

Taking over a client's existing codebase means you are inheriting someone else's decisions - their file structure, their naming, their shortcuts under deadline - and you are on the hook for it the moment you touch it. Unlike a greenfield build where Claude Code starts from an empty folder and your own conventions, here the system already has behavior in production, real users depending on it, and history you were not present for. Your job is not to judge that history. It is to understand it fast enough to change it safely.

Most builders default to treating an inherited codebase like a greenfield project with extra steps - skim the files, start writing the feature the client asked for, fix things as they break. That works on a small script. It does not work on anything with real users, and it is the single fastest way to turn a client who trusted you enough to hand over their system into a client who regrets it.

Why Rebuilding From Scratch Is the Wrong Default

The instinct when you inherit messy code is to propose a rewrite. Claude Code makes rewrites fast, so the temptation is real - it would genuinely be less frustrating to start clean than to untangle someone else's structure. Resist it as the default. A working system, however ugly, encodes thousands of small decisions about edge cases, user behavior, and business rules that nobody wrote down anywhere else. A rewrite throws all of that away and re-discovers it the hard way, usually in production, usually as a client complaint.

There are legitimate cases for a rewrite - the stack is genuinely dead, the architecture cannot support what the client needs next, the cost of continuing to patch it exceeds the cost of starting over. But that is a conclusion you reach after you understand the system, not a shortcut you take because reading someone else's code is less fun than writing your own.

The Read-Map-Patch Method

The Read-Map-Patch method is how I approach any codebase I did not write, before I quote anything beyond the first pass. It is three steps, in order, and skipping a step is where the risk comes from.

1. Read. Open the project in the Claude Code desktop app and have it walk the structure with you before you touch anything - ask it to summarize the folder layout, identify the entry points, and flag any files that look like configuration or secrets. Read the commit history if it exists. You are building a mental model, not fixing anything yet.
2. Map. Turn what you found into a short written document - the actual architecture (not what the client thinks it is), the external services it depends on, and anything that looks fragile or undocumented. This map is deliverable one. Hand it to the client even before you write code. It proves you did the work and gives them something no one else in their business currently has.
3. Patch. Make the smallest possible change that proves you can ship into this system safely - a small bug fix, a minor visible improvement, something low-risk with a clear before and after. Only after that lands cleanly do you scope the larger work the client actually hired you for.

Red Flags to Check Before You Quote the Job

Some of what you find in the Read pass should change your price, your timeline, or whether you take the job at all. Check for these before you commit to anything.

• No version control, or a git history that starts three months ago with a single commit called 'initial' - you are looking at code with no real record of how it got this way.
• Secrets or API keys committed directly into the code instead of environment variables. This is a security problem you now own the moment you touch the repository, and it needs fixing before anything else.
• Dependencies that are years out of date, or a stack the client cannot even name accurately. Outdated dependencies mean you may spend real time just getting the thing to run locally before you can do any billable work.
• No separation between a test environment and production - meaning every change you make is, by default, live. This alone should raise your price or your timeline, because your margin for error just dropped to zero.

Price a Codebase Takeover Differently Than a Greenfield Build

A codebase you did not write carries a real, unpriced risk that a greenfield build does not: you do not yet know what you do not know. Quoting it exactly like a fresh build ignores that risk and it is how builders end up underpaid for the actual hours a takeover requires.

The two-stage structure is the fix: charge for the Read and Map steps as a standalone, paid discovery engagement with its own deliverable - the map document - before you quote the larger build. Clients who resist paying for discovery are telling you something important about how the rest of the relationship will go.

Set Up Claude Code on an Inherited Project on Day One

Before any client work starts, spend the first session in the Claude Code desktop app getting the project properly set up for the fact that you did not build it. This is not optional overhead - it is what makes every session after this one faster and safer.

1. Open the project folder directly in the desktop app rather than starting a fresh chat with pasted snippets - Claude Code needs the real file tree to reason about dependencies correctly.
2. Create a CLAUDE.md file and have Claude Code draft the first version from its own read of the codebase - the stack, the conventions it detected, and anything it flagged as risky. Correct it with what you learn from the client, and keep it updated as you go.
3. Ask it to identify anything that looks like it is silently duplicated - two places doing the same job slightly differently is the most common source of a bug you introduce by fixing the one you happened to find.
4. Get a local environment running before you touch production. If that alone takes real effort, that effort belongs in your quote, not absorbed as free setup time.

Take Over Your Next Inherited Codebase Without the Guesswork

The next time a client hands you a system someone else built, resist the urge to start writing on day one. Run the Read pass, write the map, ship one small proven patch, and price the discovery separately from the build. It takes longer to start. It takes far less time to finish without breaking something the client depended on.