Claude Codeで新人エンジニアのオンボーディングを2週間に短縮する実践ガイド

新人エンジニアのオンボーディングは、「初日にPCを渡す」だけでは終わりません。オンボーディングとは、新メンバーがチームの開発環境、コードベース、レビュー文化、リリース手順を理解し、自分で小さな変更を安全に出せるようになるまでの立ち上がりです。ここが弱いと、本人は質問しづらくなり、先輩は同じ説明を何度も繰り返し、最初のPRまでに数週間かかります。

Claude Codeを使う価値は、先輩の代わりに判断させることではありません。CLAUDE.md、権限設定、チェックリスト、CI確認を揃え、新人が「まず自分で調べ、次に証拠付きで質問する」足場を作ることです。コードベースはアプリ全体のソースコード、PRはPull Request、CIはテストやビルドを自動で走らせる仕組み、と考えると初心者にもイメージしやすいはずです。

公式情報は必ず確認してください。Claude CodeのインストールやCLIの仕様は変わる可能性があるため、Claude Codeセットアップ、CLIリファレンス、メモリ管理、設定を一次情報にします。関連して、既存コードの読み方はコードベースナビゲーション、レビューはClaude Codeコードレビュー、CLAUDE.mdの設計はCLAUDE.mdテンプレート集も参考になります。

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"]

2週間の進め方を先に決める

新人オンボーディングで失敗しやすいのは、「空いた時間で見ておいて」と曖昧に渡すことです。1日目は環境構築とコマンド確認、2日目はコードベースの地図作り、3〜5日目は読むべきファイルと小さな修正候補の洗い出し、2週目は初PRとレビュー対応に分けます。Claude Codeには各日の最後に「今日分かったこと」「まだ人に確認すべきこと」「明日の最初の一手」を出させます。

この進め方にすると、質問の質が変わります。「何も分かりません」ではなく、「src/authの責務は分かったが、権限変更の判断基準は人間に確認したい」のように、AIで調べた部分と人間が判断すべき部分を分けられます。メンターも説明を全部やり直す必要がなく、誤解している前提だけを直せます。

1. 初日にCLAUDE.mdで迷子を減らす

CLAUDE.mdは、Claude Codeがプロジェクトで作業するときに読むチーム共有メモです。新人向けには、抽象的な理念ではなく「どのコマンドで確認するか」「どのディレクトリを触ってはいけないか」「質問するとき何を添えるか」を書きます。最初にこのファイルを作るだけで、毎回の説明が短くなります。

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

ここで大切なのは、Claude Codeを万能の先生にしないことです。たとえば「設計をよくして」では広すぎます。「既存の命名、テスト、境界を守って初PRを小さくする」と書けば、出力のぶれが減ります。

2. セットアップスクリプトで環境構築を半日化する

新人が最初につまずくのは、Nodeのバージョン、依存関係、環境変数、ローカルDB、テストデータです。ドキュメントが古いと、先輩のSlack DMが増えます。そこで、Claude Codeに読ませる前提のセットアップスクリプトをリポジトリに置きます。

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

このスクリプトは疑似コードではなく、一般的なnpmプロジェクトならそのまま実行できます。もちろん、pnpm、Yarn、Docker Compose、Makefileを使うチームではコマンド名を置き換えます。重要なのは「環境構築の成功条件」を先に決め、Claude Codeに説明させることです。

3. 権限設定で新人の事故を防ぐ

Claude Codeはファイルを読み、コマンドを実行し、設定によっては編集もできます。初心者にとって便利な反面、秘密情報を読んだり、意図せず危険なコマンドを提案したりするリスクがあります。権限は「何を許可するか」だけでなく「何を明示的に禁止するか」を書きます。

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

allowは許可、askは人間に確認、denyは拒否です。新人オンボーディングでは、最初の1週間は読み取りとテスト中心にし、編集はメンターが見てから許可する運用が現実的です。

4. 初PRチェックリストを固定する

最初のPRは、成果物というより「チームのやり方を覚える教材」です。大きな機能追加より、軽いバグ修正、文言修正、テスト追加、小さなリファクタリングが向いています。チェックリストをファイル化しておくと、Claude Codeにも新人にも同じ基準を渡せます。

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

ユースケースは少なくとも3つあります。1つ目は環境構築の自走化、2つ目はコードベース理解、3つ目は初PRの題材選び、4つ目はレビュー前のセルフチェックです。Claude Codeはこの一連の流れで「質問相手」ではなく「作業記録を残す相棒」として使います。

5. レビュー依頼テンプレートを作る

新人のPRが差し戻される理由は、コードの良し悪しだけではありません。なぜ変えたのか、何を確認したのか、どこが不安なのかが書かれていないと、レビューの往復が増えます。テンプレートを作り、Claude Codeに差分から下書きを作らせると、PRの質が安定します。

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

このテンプレートは、レビュー担当者にも効きます。「どこを重点的に見るか」が書かれているため、設計レビューなのか、テスト確認なのか、文言確認なのかが分かります。レビュー文化は暗黙知になりやすいので、毎回のPRに残すのが最短です。

6. CI確認を初日から見せる

CIはContinuous Integrationの略で、変更をマージする前にビルド、型チェック、テストなどを自動実行する仕組みです。新人には「CIが赤いからダメ」ではなく、「どのコマンドが失敗し、ローカルでどう再現するか」を教える必要があります。

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

GitHub Actionsを使わないチームでも、ここに並ぶコマンドはオンボーディング資料に入れてください。Claude Codeには「CIログを読んで、最初に直すべき失敗とローカル再現コマンドを説明して」と依頼できます。

具体的な落とし穴

一つ目の落とし穴は、Claude Codeに全部任せることです。Claude Codeはログやコードから推測できますが、なぜその仕様なのか、顧客とどんな約束をしているのかは人間の判断が必要です。

二つ目は、初PRを大きくしすぎることです。認証、請求、権限、DBマイグレーションは新人の学習効率が悪く、レビューも重くなります。最初は150行未満、テスト付き、戻しやすい変更に絞ります。

三つ目は、秘密情報の扱いです。.envや本番認証情報を読ませる運用は避けます。Claude Codeの設定で拒否し、ドキュメントにも「サンプル値だけ使う」と明記します。

四つ目は、質問を禁止しすぎることです。「まずClaudeに聞いて」は有効ですが、孤立を生むと逆効果です。最初の2週間は短い1on1を多めに入れ、Claude Codeの回答に違和感がある時はすぐ人間に聞ける状態にします。

よくある実例は、セットアップで詰まった新人が「自分の環境だけがおかしい」と抱え込むケースです。Nodeのバージョン、.env.exampleの不足、DBのseed忘れ、社内VPNの接続漏れは、本人の能力ではなく手順の不備です。Claude Codeには「新人が初日に詰まりそうな前提条件を10個挙げ、確認コマンドと失敗時の相談先を追記して」と頼むと、オンボーディング資料がかなり実用的になります。人間のメンターは、その出力を読んで社内事情に合わない部分だけ直せばよく、毎回同じ説明を繰り返す時間を減らせます。

収益導線CTA

チームでこの仕組みを整えるなら、CLAUDE.md、権限、レビュー観点、CI証跡をセットで標準化するのが近道です。個人で始める場合は無料チートシートで日常コマンドを固め、テンプレートを増やしたい場合はClaudeCodeLabの商品一覧を使ってください。チーム導入、研修、既存リポジトリへの適用までまとめて進めたい場合は、Claude Code研修・導入相談で運用設計から相談できます。

まとめ

Claude Codeによる新人オンボーディングの肝は、AIに先輩の代役をさせることではありません。新人が安全に自走するための足場を作ることです。CLAUDE.mdでルールを渡し、セットアップスクリプトで初日の詰まりを減らし、権限設定で危険操作を止め、チェックリストとPRテンプレートでレビュー可能な形にします。そこまで整えると、先輩の説明時間は減り、新人は「何を確認したか」を自分の言葉で残せるようになります。

実際に試した結果

MasaがClaudeCodeLabの記事改善と小さなコード修正でこの型を試したところ、いきなり実装を頼むより、最初にCLAUDE.md、権限、検証コマンド、PRテンプレートを揃えたほうが差分の確認がかなり楽になりました。特に効果が大きかったのは、Claude Codeに「変更前に読み取った前提」と「実行したコマンド」を書かせることです。回答が外れた時も、どこから誤解したか追いやすく、メンターが直すべきポイントを短時間で見つけられました。