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 do not know about yet.
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 is not 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 do not match the team's conventions.
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 will not 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 do not, create one after your first week — add the conventions you have noticed. File structure, naming patterns, error handling approach, testing style. This makes Claude's output consistent with what already exists.
For your first real change
Find a simple, isolated change. 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?
If it does not, 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?'
The Agent Prompt Playbook has the onboarding question set — the Claude prompts for mapping a new codebase in a day instead of a week. $29.
Top comments (0)