Using Claude Code on a codebase you just joined

Claude is useful when you are new to a codebase. It can explain what code does, trace data flows, and answer questions about how things connect. But it can also write changes that break implicit conventions you don't know about yet.

Here's how to use it in a way that helps without creating problems.

Use Claude to read, not write, for the first week

Before you understand the codebase, use Claude as a reader and explainer. "What does this function do?" "Where does this data come from?" "Why might this be structured this way?" These are safe — Claude isn't changing anything, and the answers help you build a mental model faster.

Asking Claude to make changes before you understand the patterns means it might follow patterns that don't match the team's conventions. You won't know until someone reviews your code.

The architecture question

Early on, give Claude the relevant part of the codebase and ask: "Describe how this system is organized. What are the main modules, what are their responsibilities, and how do they communicate?" Claude's answer won't be perfect, but it gives you a starting model to refine. Much faster than reading every file manually.

CLAUDE.md for team conventions

If the team has a CLAUDE.md, read it. If they don't, create one after your first week — add the conventions you've noticed. File structure, naming patterns, error handling approach, testing style. This makes Claude's output consistent with what already exists.

If you create a CLAUDE.md for a team repo, get it reviewed by someone who's been there longer. Your observation of the conventions might have gaps.

For your first real change

Find a simple, isolated change — a bug fix, a small extension to existing functionality. Ask Claude to implement it. Before committing: compare the style of the changes to the surrounding code. Does the naming match? Does the error handling match? Does the abstraction level match?

If it doesn't, ask Claude: "Rewrite this to match the style of [specific nearby file or function]." Claude can pattern-match against specific examples better than against abstract style descriptions.

Questions that help

• "How is authentication handled in this codebase? Show me the relevant code."
• "If I need to add a new API endpoint, what existing endpoint should I model it after?"
• "What is this file's role? What depends on it?"
• "What would break if I changed this function's signature?"