Taking Over an Unfamiliar Codebase in One Week with Claude Code — A Maintenance Handover Playbook

I once had a project handed to me with the words "You're on this starting tomorrow." The README was outdated, half the tests were red, and somehow production was running. In situations like that, jumping straight into feature work almost always leads to pain a few weeks later.

I've been on both sides of this handover many times, in solo projects and client engagements. With Claude Code in my toolkit now, the process is genuinely shorter than it used to be. But the shortcut isn't "let Claude Code figure it out for you." That approach gives you false confidence. What follows is the one-week protocol I actually use, with the exact prompts.

Day 1 — Drawing the Map Before Opening Any File

On the first day, before opening any individual file in the editor, I have a conversation with Claude Code to get the whole project put into words. The temptation to zoom into details has to be resisted.

Here is the first prompt I run:

Read through this entire repository and answer the following:
 
1. What does this project exist for (value from the user's perspective)?
2. What are the main entry points (startup scripts, API routes, batch jobs)?
3. What external dependencies (DB, API, queue, storage) exist, and in
   which files are they initialized?
4. Where are build and deploy pipelines defined?
5. List exactly three places you read where you couldn't understand the intent.
 
Do not answer from guesses. Always cite file paths and line numbers.

The "do not answer from guesses" line matters. Claude Code is helpful by default — it will produce a plausible answer even when it lacks information. In a handover context, that's the most dangerous failure mode. Forcing citations pre-empts the hallucination risk.

When the answer comes back, I also read those three "unclear" spots with my own eyes. Those become the starting points for Day 2 and beyond.

Day 2 — Nailing Down the Domain Vocabulary

Day 2 is about sorting out the project's private language. What does "User", "Order", or "Invoice" actually mean in this code? If you start adding features before you've pinned down the words, your new code ends up using your old vocabulary inside someone else's, and the codebase loses coherence.

I ask Claude Code:

Build a "domain glossary" from this codebase. Target the main nouns
that appear in models, entities, and DTOs under src/.
 
For each term include:
- Its definition (role in this codebase)
- The main related classes/functions
- Its relationships to other terms (composition, aggregation, reference)
 
Do not use a table. Use Markdown headings and paragraphs.

Asking for paragraphs instead of tables isn't just about rendering quirks — it also tends to produce more thorough explanations, because the model doesn't truncate.

The resulting glossary goes straight into a shared Notion page or docs/domain.md. Months later, when a new contributor joins, that same document helps me as much as them.

Day 3 — Identifying Where You Must Not Touch

Day 3 is the most important day in this protocol. Before writing any new feature, I use Claude Code to surface the places where a naive edit could take down production.

Find all locations in this codebase that fall into any of:
 
A. Initialization with global side effects (module-top-level DB
   connections, singleton creation, env-var reads).
B. Functions that rely on implicit contracts (return shape, error
   types, or exception kinds that callers depend on but aren't
   expressed in the type system).
C. Business-critical functions with no tests, or with very thin tests.
 
For each finding: file path, line number, and one sentence
explaining why it's risky.

Category B is where Claude Code is particularly strong. In TypeScript code that routes through any, or in dynamically typed languages, the agreement between caller and callee is often one shared assumption away from breaking. My rule is: freeze the contract with tests or types first, then change the code.

Day 4 — Making the First Change Within a Safe Radius

Day 4 is when I finally touch the code. But not with features. The order is strict:

1. Write one missing test (pick from Day 3's danger list)
2. If that test surfaces a bug or ambiguity, record it
3. Delete obvious dead code (have Claude Code propose candidates)
4. Add type annotations and docstrings (strictly non-behavioral changes)

Keeping the day to "no behavioral change" edits is what turns ambient anxiety into control. My prompt:

Read function X. Propose refactorings that change the external behavior
in zero ways. Format:
 
- Line(s) before
- Code after
- Justification for why the external behavior cannot change
 
Only propose justifications grounded in this code's context, not
generic "best practice" arguments.

Without that last constraint, you get drowned in generic suggestions (naming conventions, early returns, etc.). Those can wait. This day is for changes with real safety value.

Day 5 — Verifying Dependencies and External Boundaries

Day 5 audits the seams between this code and the outside world. External APIs, databases, queues, and environment variables often behave one way locally and another way in production.

Enumerate every external resource this codebase depends on (API, DB,
queue, env var). For each:
 
1. File path where it's accessed
2. How it's substituted in local development
3. Behavior differences that could exist between local and production
4. Whether timeouts, retries, or circuit breakers are in place
 
Pay special attention to 3 and 4.

This frequently surfaces HTTP clients with no timeout or catch blocks that silently swallow errors. When I find them, I resist the urge to fix them on the spot. Instead, I queue them as issues or TODO-annotated PRs. Trying to fix everything at once collides with downstream code that depends on the current behavior.

Day 6 — Leaving Documentation Seeds

Day 6 is about leaving breadcrumbs for your future self and future teammates. I have Claude Code generate a documentation skeleton and then correct it in my own voice.

Using everything you've learned in our conversation so far, generate
an onboarding document (Markdown) for a new team member.
 
Structure:
1. Project purpose and value
2. Architecture overview (main components and dependencies)
3. Local startup steps
4. Checklists for common tasks (feature add, bug fix, deploy)
5. Files you must read before touching anything
6. Known landmines (from Day 3)
 
I'm the person who just inherited this maintenance, so write in a
tone that is empathetic to a new person's uncertainty.

Section 6 is the non-negotiable one. Normal docs never contain this kind of information, but for someone inheriting a codebase it's the single most valuable section.

Day 7 — Codifying Your Own Operating Rules

The final day is about writing down your own rules for this codebase. If you're on a team, share them for review.

I write these three every time:

• The boundary of my role in this codebase (how far I repair things before escalating to the team)
• Self-check items before requesting review (did I touch any Day 3 danger zone, etc.)
• The top 5 pieces of debt I want to address in the next three months (with priority and rationale)

Writing these down also stabilizes the prompts I use going forward. "Did my change touch any Day 3 danger zones?" becomes a reliable pre-commit prompt.

Operating Rules That Stop You From Trusting Claude Code Too Much

Throughout the week I've leaned heavily on Claude Code, but I always observe three rules:

1. Treat every Claude Code answer as a hypothesis. Open the file and verify.
2. Make it say "I don't know." End prompts with "If you're not certain, say so."
3. Don't stay in one session all day. Context degrades. Break the session once or twice a day and let the summary act as a handoff.

With these rules, Claude Code behaves like "a strong colleague whose work you still verify." Without them, it becomes "a colleague who states plausible falsehoods confidently."

What Remains at the End of the Week

After seven days you have:

• A map of the codebase (Day 1)
• A domain glossary (Day 2)
• A list of danger zones (Day 3)
• A log of small improvements (Day 4)
• An inventory of external boundaries and known issues (Day 5)
• An onboarding document (Day 6)
• Your personal operating rules (Day 7)

With this collection, the first-week anxiety shrinks dramatically. I also run a compressed version (2–3 days) on my own projects whenever I return to them after a break. Code I wrote three years ago is no different from someone else's code to me today.

If you're staring down an unfamiliar codebase, start with the Day 1 prompt. One week later, what's in your hands won't be an unknown codebase anymore — it will be one you can touch.