Claude Code Developer Onboarding: Cut New Engineer Ramp-Up to 2 Weeks

New engineer onboarding is not just handing over a laptop. It is the process that gets a teammate from “I can open the repo” to “I can ship a small, reviewable change without breaking team rules.” The slow parts are usually repeated setup questions, a large codebase, unclear review expectations, and hidden tribal knowledge.

Claude Code should not replace mentors. Its best role is to give new engineers a safe working scaffold: project instructions in CLAUDE.md, a repeatable setup script, permission rules, a first-task checklist, a review request template, and a CI path they can understand. In plain terms, the codebase is the whole application source, a PR is a pull request for review, and CI is the automated build and test system that checks changes before merge.

Use official docs as the source of truth because Claude Code behavior can change. Start with Claude Code setup, the CLI reference, memory management, and settings. For related ClaudeCodeLab material, see codebase navigation, code review with Claude Code, and CLAUDE.md templates.

flowchart LR
  A["Day 1: setup"] --> B["Day 2: codebase map"]
  B --> C["Day 3-5: first task"]
  C --> D["Week 2: PR review"]
  D --> E["Retrospective and docs update"]

Start with CLAUDE.md

CLAUDE.md is the project memory Claude Code reads for shared instructions. For onboarding, keep it operational. New engineers need commands, boundaries, and escalation rules more than philosophy.

cat > CLAUDE.md <<'EOF'
# Project instructions for Claude Code

## Goal
Help new engineers make small, reviewable changes without bypassing tests or team rules.

## Daily commands
- Install: npm ci
- Type check: npm run typecheck
- Unit tests: npm test -- --runInBand
- Lint: npm run lint
- Build: npm run build

## Boundaries
- Do not edit files under migrations/ without human approval.
- Do not read .env, .env.*, secrets/, or production credentials.
- Do not push, commit, deploy, or publish packages.
- Prefer small diffs under 150 lines for first tasks.

## First PR rules
- Explain the intent before editing.
- Reuse existing patterns before adding dependencies.
- Add or update tests for behavior changes.
- Include command output in the PR description.

## When stuck
Ask the engineer to provide:
1. What they tried
2. The exact error
3. The file or command involved
4. What Claude Code inferred and what still needs human judgment
EOF

The point is not to make Claude Code a magical senior engineer. The point is to narrow the work so the new hire learns the team standard while producing a diff a reviewer can actually inspect.

Make Setup Repeatable

The first blocker is usually environment setup: Node version, dependencies, local env vars, test data, and “which command proves it works.” A script turns that into a repeatable path and gives Claude Code concrete context.

mkdir -p scripts
cat > scripts/onboarding-setup.sh <<'EOF'
#!/usr/bin/env bash
set -euo pipefail

echo "== Checking required tools =="
node --version
npm --version
git --version

if ! command -v claude >/dev/null 2>&1; then
  echo "Claude Code is not installed."
  echo "Install with: npm install -g @anthropic-ai/claude-code"
  exit 1
fi

echo "== Installing dependencies =="
npm ci

if [ ! -f .env ] && [ -f .env.example ]; then
  cp .env.example .env
  echo "Created .env from .env.example. Fill in local-only values before running the app."
fi

echo "== Running baseline checks =="
npm run lint
npm run typecheck
npm test -- --runInBand

echo "== Ask Claude Code for a local map =="
claude -p "Read README.md, package.json, and CLAUDE.md. Explain how to start this project locally, which checks just ran, and what a new engineer should verify before opening the first PR."
EOF
chmod +x scripts/onboarding-setup.sh

This is copy-pasteable for a typical npm project. Teams using pnpm, Yarn, Docker Compose, or Make should swap the commands, but keep the same idea: one baseline setup path, one verification path, and one Claude Code prompt that explains what happened.

Add Permission Guardrails

Claude Code can read files, search code, run commands, and, when allowed, edit files. That is useful for onboarding, but dangerous if a new engineer accidentally exposes .env files, runs destructive shell commands, or lets the agent produce a huge change. Permission settings make the boundary explicit.

mkdir -p .claude
cat > .claude/settings.json <<'EOF'
{
  "permissions": {
    "allow": [
      "Read",
      "Grep",
      "Glob",
      "Bash(git status:*)",
      "Bash(git diff:*)",
      "Bash(git log:*)",
      "Bash(npm run lint)",
      "Bash(npm run typecheck)",
      "Bash(npm test:*)"
    ],
    "ask": [
      "Edit",
      "Write",
      "Bash(npm install:*)",
      "Bash(git checkout:*)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Bash(git push:*)",
      "Bash(git commit:*)",
      "Bash(rm:*)",
      "Bash(curl:*)",
      "Bash(npm publish:*)"
    ]
  }
}
EOF

For the first week, I prefer read, search, diff, log, and test commands. Edits can require confirmation. Push, commit, deploy, publishing, and secret access should stay out of the onboarding path.

Use a First-Task Checklist

The first PR is a learning exercise. Good candidates include a missing unit test, a small UI copy fix, a localized error message, or a contained helper cleanup. Bad candidates include billing, auth, permissions, migrations, broad formatting, and dependency upgrades.

mkdir -p docs/onboarding
cat > docs/onboarding/first-task-checklist.md <<'EOF'
# First task checklist

## Before editing
- [ ] I can run `npm ci`.
- [ ] I can run `npm run lint`.
- [ ] I can run `npm run typecheck`.
- [ ] I can run the nearest test for the area I will touch.
- [ ] I understand the user-visible behavior being changed.

## Good first task examples
- [ ] Add a missing unit test around existing behavior.
- [ ] Fix a small UI copy typo with screenshot evidence.
- [ ] Replace duplicated helper logic in one folder.
- [ ] Improve one error message without changing API contracts.

## Not good for the first task
- [ ] Authentication, billing, permissions, or migrations.
- [ ] Broad formatting changes.
- [ ] Dependency upgrades.
- [ ] Refactors across multiple packages.

## PR evidence
- [ ] Summary of the change.
- [ ] Test commands and results.
- [ ] Screenshot or log if behavior changed.
- [ ] Open question for reviewer, if any.
EOF

That gives you at least three strong onboarding use cases: self-service setup, codebase reading, first-task selection, and pre-review self-checks. Claude Code is useful because it leaves a trail of assumptions, commands, and evidence.

Standardize Review Requests

Many first PRs bounce because the reviewer cannot see what was checked. A template forces the new engineer to include intent, safety, verification, and reviewer focus.

mkdir -p .github
cat > .github/pull_request_template.md <<'EOF'
## Summary
- TODO

## Why this is safe for a first PR
- Scope:
- Files changed:
- Behavior changed:

## Verification
- [ ] `npm run lint`
- [ ] `npm run typecheck`
- [ ] `npm test -- --runInBand`

## Claude Code self-review prompt used
Ask Claude Code:
"Review git diff origin/main...HEAD for naming, tests, security, and consistency with CLAUDE.md. Return only actionable issues."

## Reviewer focus
- TODO

## Screenshots or logs
- TODO
EOF

This also helps mentors. They can see whether the question is about design, tests, behavior, screenshots, or just confidence with the workflow.

Show CI from Day One

CI means continuous integration: the automated checks that run before a PR is merged. New engineers should learn how to reproduce CI failures locally instead of treating a red check as a mystery.

name: onboarding-checks

on:
  pull_request:
    branches: [main]

jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "20"
          cache: "npm"
      - run: npm ci
      - run: npm run lint
      - run: npm run typecheck
      - run: npm test -- --runInBand
      - run: npm run build

Even if your team uses another CI system, list the same commands in the onboarding guide. Then ask Claude Code to read a failing log and explain the first local command to run.

Pitfalls

The first pitfall is delegating business judgment to Claude Code. It can infer from code and history, but product commitments, customer exceptions, and compliance rules still need humans.

The second pitfall is making the first PR too large. Keep the first change under 150 lines when possible, covered by tests, and easy to revert.

The third pitfall is secret exposure. Deny .env, credentials, and production files in settings. Use sample values in docs.

The fourth pitfall is banning human questions. “Ask Claude first” is healthy only when the first two weeks still include frequent mentor check-ins.

CTA

If you are rolling this out for a team, standardize CLAUDE.md, permissions, PR evidence, and CI checks together. Individual developers can start with the free cheatsheet. For reusable templates, see ClaudeCodeLab products. For team training, permission design, and repository-specific rollout, use Claude Code training and consultation.

What Happened When I Tried This

In ClaudeCodeLab article work and small code changes, the biggest improvement came from writing the rules before asking for implementation. When Claude Code had CLAUDE.md, a limited permission set, explicit test commands, and a PR template, the resulting diff was easier to review. When the answer was wrong, the saved assumptions and command trail made the misunderstanding easier to locate.