用 Claude Code 将新工程师 Onboarding 缩短到 2 周

新工程师的 onboarding 不是发一台电脑就结束。它指的是让新人从“能打开仓库”走到“能独立提交一个小而可评审的变更”的全过程。真正拖慢速度的，通常不是新人不努力，而是环境配置反复失败、代码库太大、评审标准不清楚，以及只有老同事才知道的隐性知识。

Claude Code 不应该替代导师。更好的用法是为新人搭一个安全的工作脚手架：CLAUDE.md 中写清项目规则，准备可重复运行的 setup 脚本，限制工具权限，给出首个任务清单，固定 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 变成“万能资深工程师”，而是让任务边界变小，让新人学会团队标准，同时产出评审者能看懂的差异。

2. 用脚本固定环境搭建

新人第一天最常卡在 Node 版本、依赖安装、环境变量、测试数据和启动命令。把流程写成脚本，既能减少 Slack 上重复提问，也能给 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、部署、发布和密钥读取都应排除在新人流程之外。

4. 固定首个任务清单

第一个 PR 更像学习材料，而不是证明能力的大项目。适合的任务包括补一个已有行为的单元测试、修一个小 UI 文案、改一个错误消息、清理单个目录内的重复 helper。不适合的任务包括鉴权、账单、权限、迁移、全局格式化和依赖升级。

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

这样至少覆盖四个真实场景：自助搭建环境、理解代码库、选择首个任务、提交前自查。Claude Code 的价值在于留下假设、命令和证据，而不是只给一个答案。

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，意思是在合并前自动运行检查。新人不应该只看到一个红色状态，而要知道哪个命令失败，以及如何在本地复现。

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，也应该把同样的命令写进 onboarding 文档。然后让 Claude Code 阅读失败日志，说明新人本地应该先运行哪条命令。

常见失败点

第一，把业务判断交给 Claude Code。它可以从代码和历史推断，但产品承诺、客户例外和合规要求仍然需要人来判断。

第二，第一个 PR 太大。尽量控制在 150 行以内，有测试，容易回滚。

第三，泄露秘密信息。通过 settings 拒绝 .env、凭据和生产文件，文档里只使用示例值。

第四，过度禁止提问。“先问 Claude”只有在前两周仍有高频导师同步时才健康，否则新人会被孤立。

转化引导（CTA）

团队落地时，最好把 CLAUDE.md、权限、PR 证据和 CI 检查一起标准化。个人可以先用免费 cheatsheet建立日常命令习惯；需要可复用模板时看 ClaudeCodeLab products；如果要做团队培训、权限设计和真实仓库导入，可以使用 Claude Code training and consultation。

实际试用结果

在 ClaudeCodeLab 的文章维护和小型代码修改中，先写规则再让 Claude Code 实现，效果明显更稳定。有了 CLAUDE.md、受限权限、验证命令和 PR 模板后，差异更容易评审。即使答案出错，保存下来的前提和命令记录也能帮助我快速定位 Claude Code 是从哪里误解的。