How to use Claude Code to modify a codebase you did not write

You've just inherited a codebase. No docs, no tests, the original author is gone, and there's a bug in production. Sound familiar?

This is where Claude Code earns its keep. In this guide I'll walk through the exact three-phase workflow we use at the agency when a client hands us an unknown repo: audit → safe edit → verify loop.

What you'll need

• Claude Code installed and authenticated (claude --version)
• Git access to the repository
• About 30 minutes the first time, much faster after that

Phase 1 — Audit the codebase

Before touching a single line, you need a mental map. Ask Claude Code to build one for you.

claude "Give me a plain-English tour of this repo. What is the entry point, what are the main layers, and where does data flow from the user to the database?"

Claude Code will read the directory tree, open key files, and return a structured summary. Save it.

Next, surface the landmines:

claude "List every place where user input touches the database without obvious sanitisation. Show file name and line number."

Do the same for authentication boundaries, third-party API calls, and anything labelled TODO or FIXME. Now you have a triage list.

Pro tip: Pipe the output into a markdown file — claude "audit this repo" > audit.md — and commit it. Future you will be grateful.

Phase 2 — Safe edit workflow

The goal here is to make changes that are easy to review and easy to revert. Claude Code has a built-in safe-edit mode that shows diffs before applying them.

2.1 Open a feature branch

git checkout -b fix/inherited-bug

Never work on main on a repo you don't fully understand.

2.2 Describe the bug, not the fix

This is the most important rule. Instead of:

# ❌ Don't do this
claude "change line 47 in auth.js to use bcrypt instead of md5"

Do this:

# ✅ Do this
claude "Users can log in with any password after a failed attempt. Find the root cause and propose a minimal fix."

By describing the symptom, you let Claude Code read the surrounding context, spot related issues you'd miss, and produce a fix that fits the existing code style.

2.3 Review before applying

Claude Code will propose a diff. Read it. Every line. If something looks wrong, push back in natural language:

claude "That fix looks right but it changes the error message format. Keep the original error messages."

Iterate until you're happy, then apply:

claude --apply

Phase 3 — Verify loop

A fix that breaks something else isn't a fix. Close the loop with tests.

3.1 Ask Claude Code to write the test first

claude "Write a test for the auth bug we just fixed. It should fail on the original code and pass on the patched code."

If the repo has no test framework, Claude Code will suggest one. Let it scaffold the setup — it takes two minutes.

3.2 Run the full suite

npm test  # or whatever the project uses

If tests fail, paste the error output back to Claude Code:

claude "The tests are failing with this error: [paste error]. What went wrong?"

This is the loop: fix → test → diagnose → fix again. Most bugs resolve in two or three iterations.

3.3 Final audit

Before opening a PR, do one last scan:

claude "Review the diff in this branch and flag anything that looks unintentional or risky."

It catches the small things — a stray console.log, a hardcoded API key you accidentally kept, a function that's now unused.

Common pitfalls

Pitfall	Why it happens	What to do instead
Claude edits the wrong file	Ambiguous instructions	Name the file explicitly
Fix works locally, breaks in CI	Environment differences	Ask Claude to check env assumptions
Audit misses a hidden entry point	Unusual project structure	Tell Claude about any non-standard conventions upfront

Wrapping up

The pattern — audit → safe edit → verify — works on any inherited codebase regardless of language or framework. Claude Code's value here isn't magic; it's the ability to hold an entire codebase in context while you direct the investigation.

Start with the audit. Everything else follows from understanding what you're working with.

---

Have a war story about inheriting a gnarly codebase? Reply to this tutorial — we feature the best ones in the newsletter.