Working in a repo you do not know

An unfamiliar repository used to mean a day of reading before the first safe change. The documentation's position on what replaces that day: "When onboarding to a new codebase, use Claude Code for learning and exploration", and, for teams, "Using Claude Code this way is an effective onboarding workflow, improving ramp-up time and reducing load on other engineers".

The catch this page exists for: the model is also in an unfamiliar repo. It reads faster than you and forgets between sessions, and it will produce confident descriptions of conventions that do not exist exactly as fluently as real ones. The workflow below is built around that asymmetry.

Hour one: interrogate, change nothing

Start in plan mode or a read-only frame and "Ask Claude questions you'd ask a senior engineer": where does request handling live, what is the test strategy, why are there two HTTP clients, what would break if I touched this table. This is the context-is-the-skill muscle applied in reverse: instead of you feeding context, you are extracting it, and each answer tells you what to verify next.

Verify is the operative word. For every structural claim, ask for the file and line. An answer that names src/billing/retry.ts:40 can be checked in ten seconds; an answer that describes "the billing subsystem's philosophy" cannot. The habit is the same one reviewing agent code teaches: trust claims that carry their evidence.

Two artefacts are worth producing before any change:

A map you wrote in your own words. Ask for a tour, then write the five-line summary yourself. The gap between what you can restate and what you merely nodded at is the same retrieval check as ever, and the summary seeds the next session, because the model's own exploration does not survive /clear.

A CLAUDE.md, if the repo has none. You are the person discovering the build commands, the test invocation, the conventions. Ten minutes of writing them down converts your onboarding into every future session's head start — including your own, tomorrow.

The first change: small, planned, verified

The documentation's general advice is at its sharpest in a repo you cannot judge: "Separate research and planning from implementation to avoid solving the wrong problem", with planning most valuable exactly here: "when you're uncertain about the approach, when the change modifies multiple files, or when you're unfamiliar with the code being modified". That is plan-first, selected by circumstance rather than preference.

Pick a deliberately small first change and treat the plan as a test of the map: if the plan touches files your mental model did not predict, the model knows something you do not, or believes something false. Both are findings, both cheap now. Then let the repo's own checks be the referee. An unknown repo's test suite is the one description of intended behaviour that cannot hallucinate; run it before your change to learn what green looks like, and after, to learn what you broke.

The permission posture follows from ignorance: in a repo where you cannot yet judge a diff's blast radius, you are the wrong person to approve broad grants, so keep approvals per-action until the map has survived a few changes.

What goes wrong

The confident tour of a fictional building. A fluent architecture summary with an invented convention in the middle, absorbed as fact on day one, discovered at review three weeks later. Spot-check the tour against files before you build a mental model on it.

Editing during the interview. Exploration mode and change mode blur, and a "small tidy-up while we're here" lands in code whose consumers you have not met.

The big first bite. A cross-cutting refactor as change one, in the exact conditions the docs list as highest-uncertainty. Large refactors have their own page, and step one is knowing the repo.

Trusting green you never saw fail. A passing suite means little until you have seen it catch something — including the possibility that it passes because it tests nothing on your path.

Session two starts from zero. Yesterday's beautifully extracted context evaporated with the window. The map file and the CLAUDE.md are the memory that persists; rebuild from them, not from scratch.

How to check it worked

At the end of day one, close the tools and sketch the request path — entry point, key modules, where the change you are asked for will live — then verify the sketch against the code with fresh eyes. If it holds, the interrogation produced a real map. If it does not, better to find out before the map has three weeks of decisions stacked on it. And check the team effect a week in: the questions you did ask a colleague should be the ones a model could not answer (history, intent, politics), which is the load the docs promised to take off the seniors.