新人エンジニアが最初のPRを出すまで2週間→3日。Claude Code前提のオンボーディング設計

入社初日の新人が、夕方になってもまだ「アプリが起動しません」と言っている。

僕のチームで何度も見た光景です。原因はだいたい同じでした。Nodeのバージョン違い、.envの作り方が口伝、ローカルDBのseed忘れ、社内VPNの設定漏れ。本人の能力じゃなくて、立ち上げの手順が散らかっているだけ。それなのに新人は「自分の環境だけおかしいのかも」と抱え込み、先輩は同じSlackのDMに何度も答える。

ここで思考が止まると、最初のPR(Pull Request、変更をチームに提案する単位)まで2〜3週間かかります。一方、立ち上げを「仕組み」にしてあるチームだと、同じ人が3日目に小さなPRを出せる。差は地頭じゃなくて、新人がつまずく前提を先につぶしてあるかどうかです。

この記事は、その仕組みをClaude Code前提で作る話です。新人が「まず自分で調べ、分からない所だけ証拠付きで聞く」状態に持っていく。先輩の代役をAIにさせるのではなく、新人が自走するための足場を組みます。

この記事の要点

• 立ち上げが遅いのは新人の能力不足ではなく、環境再現とリポジトリ把握の手順が散らかっているせい。
• 環境はdevcontainerで1ファイル化し、「僕のPCでは動く」をなくす。初日の起動を半日で終わらせる。
• リポジトリの把握は、CLAUDE.mdとリポジトリマップを置き、新人がClaude Codeに案内させる形にする。
• 最初のPRは「成果物」ではなく「チームのやり方を覚える教材」。150行未満・テスト付き・戻しやすい題材に絞る。
• 権限とチェックリストで事故を止めれば、先輩のレビューは設計の話だけに集中できる。

まず2週間ではなく「最短ルート」を地図にする

新人オンボーディングで一番多い失敗は、「空いた時間でコード見ておいて」と丸投げすることです。範囲が広すぎて、新人はどこから読めばいいか分からない。1週間「全体を眺めて」終わります。

そうではなく、日ごとにゴールを決めます。下の表くらいの粒度があれば、新人は今日やることが分かるし、先輩も進捗を見やすい。

日	ゴール	新人がやること	Claude Codeの使いどころ
Day 1	環境が動く	devcontainerで起動、テスト1本を通す	起動手順と検証コマンドを説明させる
Day 2	地図ができる	主要ディレクトリと入口を把握	リポジトリマップを下書きさせる
Day 3	小さく直す	修正候補を1つ選び、差分を作る	既存パターンを探させる
Week 2	PRを出す	初PRとレビュー対応	一次レビューの下書き

ポイントは、各日の終わりにClaude Codeへ「今日分かったこと」「まだ人に確認したいこと」「明日の最初の一手」を3行で書かせること。これだけで質問の質が変わります。「何も分かりません」ではなく「src/authの責務は読めたが、権限変更の判断基準は人に聞きたい」と言えるようになる。先輩は説明を全部やり直さず、誤解している前提だけ直せばよくなります。

Day 1の山場は環境再現。devcontainerで1ファイル化する

立ち上げが詰まる原因の9割は初日の環境構築です。ここを口伝のREADMEに任せると、毎回新人ごとに違う詰まり方をする。

僕がたどり着いた答えは、開発環境を1ファイルにまとめてしまうことでした。devcontainer(開発用コンテナの設定)を使うと、Nodeのバージョンも、必要な拡張機能も、起動後に走らせるコマンドも、リポジトリの中に書いておけます。新人はVS CodeやGitHub Codespacesで「コンテナで開く」を押すだけ。「僕のPCでは動く」という言い訳が、構造的に出てこなくなります。

.devcontainer/devcontainer.jsonはこう書けます。これはコピペで動く最小形です。

{
  "name": "team-onboarding",
  "image": "mcr.microsoft.com/devcontainers/javascript-node:20",
  "features": {
    "ghcr.io/devcontainers/features/git:1": {}
  },
  "postCreateCommand": "npm ci && npm run typecheck && npm test --silent",
  "customizations": {
    "vscode": {
      "extensions": ["dbaeumer.vscode-eslint", "esbenp.prettier-vscode"]
    }
  },
  "remoteEnv": {
    "NODE_ENV": "development"
  }
}

postCreateCommandがキモです。コンテナを開いた直後に依存インストールと型チェックとテストが自動で走る。つまり「起動の成功条件」がここに書いてあるわけです。新人は、これが緑になれば環境は正しいと分かる。詰まったら、どのコマンドで失敗したかを見ればいい。

devの中身をもっと詰めたい人は、featuresやpostCreateCommandの使い分け、Codespacesでの再現まで踏み込んだdevcontainer.jsonで開発環境を1ファイル化する手順を先に読んでおくと、ここで迷いません。

devを使わないチームでも、考え方は同じです。「環境構築の成功条件」をスクリプト1本にまとめ、Claude Codeに説明させる。下のシェルスクリプトは一般的なnpmプロジェクトならそのまま動きます。

#!/usr/bin/env bash
set -euo pipefail

echo "== 必要なツールを確認 =="
node --version
npm --version
git --version

if ! command -v claude >/dev/null 2>&1; then
  echo "Claude Code が未インストールです。"
  echo "ネイティブ版: curl -fsSL https://claude.ai/install.sh | bash"
  exit 1
fi

echo "== 依存をインストール =="
npm ci

if [ ! -f .env ] && [ -f .env.example ]; then
  cp .env.example .env
  echo ".env.example から .env を作成。ローカル用の値だけ埋めてください。"
fi

echo "== 基本チェックを実行 =="
npm run lint
npm run typecheck
npm test -- --runInBand

echo "== Claude Code に起動手順を説明させる =="
claude -p "README.md と package.json と CLAUDE.md を読んで、ローカルでの起動方法、いま通ったチェック、最初のPR前に新人が確認すべき点を説明して。"

pnpmやYarn、Docker Compose、Makefileのチームはコマンドを置き換えるだけ。大事なのは、新人が「これを実行して緑になればOK」という一本道を持てることです。

Day 2はリポジトリ把握。CLAUDE.mdとマップで新人を案内する

環境が動いたら、次は「このコードベース、何がどこにあるの?」です。ここでも全部を読ませてはいけません。10万行のリポジトリを頭から読むのは、地図なしで知らない街を歩くようなものだから。

やることは2つ。リポジトリの入口を示すCLAUDE.mdを置くことと、新人がClaude Codeに案内させることです。

CLAUDE.mdは、Claude Codeがプロジェクトで作業するとき毎回読むチーム共有メモです。理念ではなく、「どのコマンドで確認するか」「どこを触ってはいけないか」「質問するとき何を添えるか」を書く。これがあると、新人もAIも同じルールで動けます。

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

## Goal
新人が、テストやチームのルールを飛ばさずに、小さくレビュー可能な変更を出せるよう手助けする。

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

## Repository map
- src/api/      … HTTPハンドラ。入口はここ
- src/domain/   … 業務ロジック。仕様の中心
- src/db/       … DBアクセス。migrations/ は人の承認なしで触らない
- scripts/      … 開発用スクリプト

## Boundaries
- migrations/ は人の承認なしに編集しない
- .env, .env.*, secrets/ は読まない
- push / commit / deploy / publish はしない
- 最初の課題は150行未満の小さな差分にする

## When stuck
次を添えて質問する: 試したこと / 正確なエラー / 関係するファイルやコマンド / AIが推測した部分と人の判断が要る部分
EOF

注目してほしいのはRepository mapの数行です。たったこれだけでも、新人が「業務ロジックはsrc/domainなんだな」と当たりをつけられる。Claude Codeも、この地図を手がかりに案内できる。

ただしCLAUDE.mdは短く保つのが鉄則です。公式も200行を超えると指示の遵守率が下がると明記しています(出典: How Claude remembers your project)。長い理念を書くより、地図とルールを絞る。粒度の決め方はCLAUDE.mdは何を書かないかで決まるに詳しくまとめました。

そのうえで、新人にはClaude Codeへこう聞かせます。「src/apiの入口から、ユーザー登録の処理がどこを通るか追って。読んだファイルと、人に確認すべき前提を分けて教えて」。AIが実行経路を追い、新人はそれを検算する。読み方の型は巨大コードベースを読む検索術が参考になります。先に45分でリポジトリの地図を作る編集前の安全手順を通すと、Day 2がさらに速くなります。

Day 3以降。事故を止める権限設定

新人がコードを触り始めると、便利さと裏腹に事故のリスクが出ます。秘密情報を読む、危険なコマンドを提案する、本番に何かする。これは「気をつけて」では防げません。仕組みで止めます。

Claude Codeの権限は.claude/settings.jsonに書きます。許可(allow)、確認(ask)、拒否(deny)の3つを使い分ける。最初の1週間は読み取りとテスト中心にして、編集は先輩が見てから許す運用が現実的です。

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(npm publish:*)"
    ]
  }
}
EOF

ここで覚えておきたいのは、CLAUDE.mdのルールは「お願い」だが、denyは「強制」だということ。公式も、確実に止めたい操作はCLAUDE.mdではなく権限やフック(hook)で縛れと言っています。新人に「.envを読まないでね」とお願いするより、読めなくしておくほうが安全です。allow/deny/askの評価順や書き方は権限設定リファレンスにまとめてあります。

Week 2は最初のPR。題材選びが9割

最初のPRは、立派な機能である必要はありません。むしろ、チームのやり方を体で覚えるための教材です。だから題材選びがすべて。重い題材を渡すと、新人もレビュー担当も消耗します。

向く題材と向かない題材を、最初からチェックリストにしておきます。

mkdir -p docs/onboarding
cat > docs/onboarding/first-task-checklist.md <<'EOF'
# 最初の課題チェックリスト

## 編集の前に
- [ ] npm ci が通る
- [ ] npm run lint が通る
- [ ] npm run typecheck が通る
- [ ] 触る範囲の近くのテストを1本実行できる
- [ ] 変える挙動が、ユーザーから見てどう変わるか説明できる

## 向く題材
- [ ] 既存挙動にテストを1本足す
- [ ] UI文言の小さな誤字を、スクショ付きで直す
- [ ] 1フォルダ内の重複ヘルパーをまとめる
- [ ] APIの契約を変えずにエラーメッセージを1つ改善する

## 向かない題材
- [ ] 認証・課金・権限・DBマイグレーション
- [ ] 広いフォーマット変更
- [ ] 依存のアップグレード
- [ ] 複数パッケージにまたがるリファクタ

## PRに添える証拠
- [ ] 変更の要約
- [ ] 実行したテストコマンドと結果
- [ ] 挙動が変わったならスクショかログ
- [ ] レビュアーへの確認したい点(あれば)
EOF

PR本文も、書くことが決まっていれば新人は迷いません。.github/pull_request_template.mdを置いて、Claude Codeに差分から下書きを作らせると質が安定します。レビュー担当も「どこを重点的に見るか」が分かるので、設計の話に集中できる。Claude Codeに一次レビューを任せて人間は設計に集中する型は、コードレビューを任せる進め方で詳しく書きました。

僕がやらかした失敗3つ

正直に書きます。最初の数人のオンボーディングは、僕のほうがミスだらけでした。

ひとつ目は、READMEだけで済ませようとしたこと。「READMEに全部書いてあるから読んで」と渡したら、新人ごとに違う所で詰まりました。READMEは読み物としては良くても、環境の「成功条件」を保証してくれない。devcontainerと検証スクリプトに移してから、初日の詰まりが激減しました。

ふたつ目は、初PRを大きくしすぎたこと。良かれと思って「認証まわりを直してみて」と渡したら、新人は仕様の海で溺れ、レビューも往復だらけになった。今は150行未満・テスト付き・戻しやすい、を絶対の条件にしています。

みっつ目は、質問を禁止しすぎたこと。「まずClaudeに聞いて」は有効なんですが、やりすぎると新人が孤立する。最初の2週間は短い1on1を多めに入れて、AIの回答に違和感があったらすぐ人に聞ける状態を保つ。自走と孤立は紙一重でした。

よくある質問

Q. Claude Codeは無料で使えますか? いいえ。Claude CodeはPro / Max / Team / Enterprise、またはConsole(API)のアカウントが必要です。無料のClaude.aiプランでは使えません。新人に配る前にアカウント区分を確認してください。

Q. WindowsのPCしかない新人でも大丈夫ですか? 大丈夫です。Windows 10(1809+)以降に対応していて、ネイティブ版・WSL・npmから入れられます。サンドボックス(隔離実行)を使いたいならWSL 2が必要、と覚えておけば十分です。

Q. CLAUDE.mdとREADMEは何が違うんですか? READMEは人間向けのプロジェクト説明、CLAUDE.mdはClaude Codeが毎回読む作業用メモです。READMEに「貢献手順」を、CLAUDE.mdに「コマンド・境界・質問の作法」を書くと棲み分けがきれいです。/initコマンドで叩き台を自動生成できます。

Q. 既存のAGENTS.mdがあるのですが、両方書くんですか? 不要です。Claude Codeが読むのはCLAUDE.mdなので、CLAUDE.mdの中で@AGENTS.mdと書いて取り込めば、両方のツールが同じ指示を見ます。二重メンテになりません。

Q. devcontainerは必須ですか? 必須ではありません。ただ初日の環境差をなくす効果が一番大きいのがdevです。導入が難しいチームは、まず検証スクリプト1本から始めて、「実行して緑になればOK」の状態だけ先に作ってください。

実際に試した結果

MasaがClaudeCodeLabの記事改善と小さなコード修正でこの型を試したところ、いきなり実装を頼むより、先に環境再現・CLAUDE.md・権限・PRテンプレートを揃えたほうが、立ち上げも差分の確認もはっきり楽になりました。

特に効いたのは2つ。devcontainerで「起動の成功条件」をコードに固定したことと、Claude Codeに「読み取った前提」と「実行したコマンド」を毎回書かせたことです。前者で初日の「動きません」が消え、後者で回答が外れたときも、どこから誤解したか追えるようになった。先輩が直すべき所を短時間で見つけられる。

新人が早く戦力になるかは、本人の地頭より、転んでもケガしない足場をこちらが先に組めるかで決まる、というのが今の実感です。チームで標準化したいなら教材一覧のテンプレートが土台に使えます。まずはdevcontainerとCLAUDE.mdの2つから、自分のリポジトリに足してみてください。