Claude Code with a codebase you didn't write: the setup that works
Using Claude Code on your own project is one thing. Using it on code you inherited — legacy systems, acquired repos, someone else's "temporary" solution that became permanent infrastructure — is a different challenge.
The agent is good at reading code. It's less good at understanding the implicit decisions embedded in code that's been evolving for years.
The context dump problem
You can't paste 50,000 lines of legacy code as context. You have to curate. And curating means understanding the code well enough to know what matters — which is exactly what you're hoping the agent will help you figure out.
The way I've gotten around this: instead of pasting code, I ask the agent to read specific files and tell me what it understands. Then I correct the misunderstandings.
"Read routes/auth.js and tell me what it does, what dependencies it has, and what would break if I removed it."
The agent's summary tells me two things: what it understood correctly (good, I can build on that), and what it got wrong (important, because it would have worked from that wrong assumption without this step).
Before touching anything
Before writing a single line of code in a legacy codebase, I ask:
"Read the last 20 git commits. Tell me what areas of the code have been changing and what the apparent direction of development is."
"What are the files that appear most in these commits? What does that suggest about where the active development is happening?"
"What patterns do you see in how errors are handled? How are API calls made? How is state managed?"
These three questions give the agent a working model of the codebase's conventions before it starts making changes. Without them, it imports its own conventions. With them, it's more likely to match the existing ones.
The two categories of legacy code
Weird-for-a-reason code: Unusual patterns that exist because of a specific constraint that isn't obvious from reading the code. Rate limit handling that looks overcomplicated is usually weird for a reason. Authentication flows that don't follow standard patterns are usually weird for a reason.
Weird-for-no-reason code: Accumulated decisions made quickly under pressure that nobody cleaned up. This is most legacy code.
The agent can't tell these apart reliably. I ask explicitly: "Is there anything in this file that seems unusual or non-standard? For each unusual thing, can you think of a reason why it might have been done this way?"
The answers aren't always right, but they surface the places to investigate.
The conservative first task
For any new legacy codebase, my first Claude Code task is always narrow and low-risk. Add a test for existing behavior, not new behavior. Extract a well-understood function to a separate file. Write documentation for how an existing endpoint works.
The goal isn't the output of the first task. It's to see how the agent operates in this specific codebase. What patterns does it use? What assumptions does it make? Does it respect the existing conventions?
After one or two conservative tasks, I have much better calibration for what the agent will do on more complex work.
From running Claude Code in multiple codebases, including some I didn't write.
Top comments (0)