Claude Code로 신규 엔지니어 온보딩을 2주로 줄이는 실전 가이드

신규 엔지니어 온보딩은 노트북을 지급하는 것으로 끝나지 않습니다. 온보딩은 새 팀원이 저장소를 열 수 있는 상태에서 시작해, 팀 규칙을 지키며 작은 변경을 PR로 올리고 리뷰를 받을 수 있는 상태까지 가는 과정입니다. 속도를 늦추는 원인은 보통 반복되는 환경 설정 질문, 큰 코드베이스, 불명확한 리뷰 기준, 문서화되지 않은 암묵지입니다.

Claude Code는 멘토를 대체하는 도구가 아닙니다. 더 현실적인 역할은 안전한 작업 발판을 만드는 것입니다. CLAUDE.md에 프로젝트 규칙을 적고, 재현 가능한 셋업 스크립트를 두고, 권한을 제한하고, 첫 작업 체크리스트와 PR 템플릿, CI 확인 절차를 제공합니다. 코드베이스는 애플리케이션 전체 소스, PR은 리뷰를 위한 변경 요청, CI는 병합 전에 테스트와 빌드를 자동 실행하는 시스템이라고 설명하면 초보자도 이해하기 쉽습니다.

Claude Code의 설치와 CLI 동작은 바뀔 수 있으므로 공식 문서를 우선 확인하세요. Claude Code setup, CLI reference, memory, settings를 기준으로 삼습니다. 함께 보면 좋은 글은 codebase navigation, code review, 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"]

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를 만능 시니어로 만드는 것이 아닙니다. 작업 범위를 좁혀 새 팀원이 팀 표준을 배우면서 리뷰 가능한 diff를 만들도록 돕는 것입니다.

2. 환경 설정을 스크립트로 고정하기

첫날 가장 많이 막히는 부분은 Node 버전, 의존성, 환경 변수, 테스트 데이터, 실행 확인 방법입니다. 스크립트로 만들면 반복 질문이 줄고 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을 쓰는 팀은 명령만 바꾸면 됩니다. 핵심은 성공 기준과 검증 명령을 먼저 고정하는 것입니다.

3. 권한으로 사고를 막기

Claude Code는 파일 읽기, 검색, 명령 실행, 허용된 편집을 할 수 있습니다. 편리하지만 .env를 읽거나 위험한 명령을 실행하거나 너무 큰 변경을 만들 위험도 있습니다. 권한은 허용, 확인 필요, 금지를 모두 명시해야 합니다.

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

첫 주에는 읽기, 검색, diff, log, 테스트 중심이 좋습니다. 편집은 확인을 거치고, push, commit, 배포, 패키지 publish, 비밀정보 접근은 온보딩 경로에서 제외합니다.

4. 첫 PR 체크리스트 만들기

첫 PR은 큰 성과보다 팀 방식 학습에 가깝습니다. 기존 동작의 단위 테스트 추가, 작은 UI 문구 수정, 오류 메시지 개선, 한 폴더 안의 중복 helper 정리가 적합합니다. 인증, 결제, 권한, migration, 광범위한 포맷팅, 의존성 업그레이드는 피합니다.

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

이 흐름은 환경 설정 자립, 코드베이스 이해, 첫 작업 선택, 리뷰 전 셀프 체크라는 네 가지 실무 사례를 커버합니다.

5. 리뷰 요청 템플릿 고정하기

첫 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

템플릿은 멘토에게도 도움이 됩니다. 이번 리뷰가 설계, 테스트, 동작, 스크린샷, 또는 프로세스 학습 중 어디에 초점을 둬야 하는지 빨리 보입니다.

6. CI를 첫날부터 설명하기

CI는 Continuous Integration으로, PR을 병합하기 전에 자동으로 검증을 실행하는 시스템입니다. 신규 엔지니어에게는 빨간 체크만 보여주지 말고, 어떤 명령이 실패했는지와 로컬 재현 방법을 알려줘야 합니다.

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

다른 CI를 쓰더라도 같은 명령 목록을 온보딩 문서에 넣으세요. 실패 로그를 Claude Code에 읽게 하고, 가장 먼저 로컬에서 실행할 명령을 설명하게 하면 좋습니다.

흔한 함정

첫째, 비즈니스 판단을 Claude Code에 맡기는 것입니다. 코드와 기록에서 추론은 가능하지만 고객 약속, 예외 처리, 컴플라이언스는 사람이 판단해야 합니다.

둘째, 첫 PR을 너무 크게 만드는 것입니다. 가능하면 150줄 이하, 테스트 포함, 되돌리기 쉬운 변경으로 제한합니다.

셋째, 비밀정보 노출입니다. settings에서 .env, credential, production 파일을 거부하고 문서에는 샘플 값만 사용합니다.

넷째, 질문을 막는 것입니다. “먼저 Claude에게 물어보기”는 첫 2주 동안 충분한 멘토 체크인이 있을 때만 건강하게 작동합니다.

CTA

팀에 적용하려면 CLAUDE.md, 권한, PR 증거, CI 체크를 함께 표준화하세요. 개인은 무료 cheatsheet로 일상 명령부터 익히고, 반복 템플릿은 ClaudeCodeLab products를 참고할 수 있습니다. 팀 교육, 권한 설계, 실제 저장소 적용은 Claude Code training and consultation에서 상담할 수 있습니다.

실제로 시도한 결과

ClaudeCodeLab의 글 수정과 작은 코드 변경에서, 구현을 바로 요청하기보다 규칙을 먼저 적었을 때 결과가 더 안정적이었습니다. CLAUDE.md, 제한된 권한, 검증 명령, PR 템플릿이 있으면 diff를 훨씬 쉽게 리뷰할 수 있었습니다. 답이 틀렸을 때도 남아 있는 전제와 명령 기록 덕분에 어디서 오해가 생겼는지 빠르게 찾을 수 있었습니다.