Onboard New Hires with Claude Code Codebase Tours

Give a new hire a destination, not an instruction to “read the repository.” For this onboarding session, aim for three deliverables: a small architecture map, one verified feature trace, and a proposal for a safe first change. Follow the steps together, with the newcomer driving the keyboard and a teammate available to resolve questions.

1. Prepare the repository and access boundaries

Clone the team-approved repository, open its root directory in your terminal, and check your working tree with git status. Read the setup documentation before installing dependencies. Confirm which development services and test credentials the newcomer may use.

Before sharing proprietary code with any model provider or relay, obtain your organization’s approval. Keep production credentials and customer records outside the exercise. Review Claude Code permissions rather than assuming a prompt alone restricts access; its permission system supports controls over tools and file access. ([code.claude.com](https://code.claude.com/docs/en/permissions))

2. Launch an exploration-only session

From the repository root, run claude. Claude Code’s documented onboarding workflow starts here, then moves from a broad overview to specific components. ([code.claude.com](https://code.claude.com/docs/en/common-workflows))

Select Plan Mode for the tour. It supports exploration and planning without source-code edits, making it an appropriate starting point before implementation. ([code.claude.com](https://code.claude.com/docs/en/common-workflows)) Ask: “Help me understand this repository. Do not change files. Start with the README, package manifests, and existing project instructions. List what you inspected and what remains uncertain.”

For approved pay-as-you-go access, consider RelayVano, which works with Claude Code. Sign up for RelayVano if that purchasing approach suits your team, then follow its Claude Code configuration instructions before continuing.

3. Build a five-stop architecture map

Ask: “Create a five-stop tour covering application startup, request handling, business logic, persistence, and tests. For each stop, name an actual file, its responsibility, and the next file I should inspect. Mark anything inferred rather than verified.”

Open each suggested file yourself. If this is a library, CLI, or mobile application, replace request handling with its relevant entry point. Keep the output to one screen rather than requesting an exhaustive directory inventory.

Claude Code supports questions about architecture, data models, authentication, and project-specific terminology. Use those capabilities to resolve one unfamiliar concept at each stop. ([code.claude.com](https://code.claude.com/docs/en/common-workflows)) Record unresolved questions for your onboarding buddy instead of accepting plausible explanations.

4. Trace one real feature end to end

Choose a small feature from an existing ticket or demonstration: loading a profile, parsing an input file, or updating a preference. Avoid starting with the most complex subsystem.

Ask: “Trace this feature from its entry point to its result. Identify validation, authorization if applicable, business logic, storage calls, and error handling. Cite file paths and symbol names. Separate observed behavior from assumptions.”

Follow the symbols in your editor. At each boundary, explain aloud what enters, what leaves, and what can fail. Ask your teammate to confirm any behavior that depends on deployment configuration or an external service.

5. Verify the trace with a focused test

Ask: “Find the nearest existing test for this feature. Explain its fixtures, assertions, and external dependencies. Propose the smallest documented command to run it, but do not execute it yet.”

Compare the proposed command with repository instructions and CI configuration. Inspect any referenced scripts before running it yourself in the approved development environment. Record the command, outcome, and missing setup requirements.

If it fails, preserve the original failure. Ask for an explanation before accepting dependency upgrades, snapshot updates, or configuration changes. Keep environment repair separate from learning the feature.

6. Rehearse a small first change

Pick a mentor-approved task, such as adding a boundary-case test. Ask: “Propose the smallest change for this task. List affected files, an analogous implementation, expected behavior, and verification steps. Do not edit yet.”

Review the plan together. Have the newcomer explain why each file belongs in scope. Only then move into implementation through the team’s normal review process. Reject unrelated cleanup from this first patch.

7. Save a verified handoff note

Write a short onboarding note containing the five-stop map, feature trace, verified test command, and outstanding questions. Include the commit identifier so the next reader knows which revision you explored.

Keep durable project instructions separate: CLAUDE.md supplies project guidance to Claude Code. Add only teammate-reviewed conventions there, not the entire tour transcript. ([code.claude.com](https://code.claude.com/docs/en/memory)) Finish by closing the chat and asking the newcomer to locate the feature and explain its test independently. Use that demonstration to choose the next onboarding session.