新人 Onboarding 清单模板：让第一周有路径

新人第一周卡住，通常不是能力问题

带过几个新人之后，我发现一个规律：新人第一周卡住的地方，和我当初卡住的地方几乎一样。这不是偶然——团队的隐性知识如果没有显性化，每一代新人都会重复踩同样的坑。

之前带过一个从大厂跳过来的前端，简历上写着「主导过千万级用户产品重构」。入职第一天，他对着 README 配了一下午环境，第二天提了个 PR，CI 直接挂掉，lint 规则跟老项目的风格对不上。第三天他来找我：「我觉得我对不起这个 Title。」

问题不在能力，在于团队没给路径。

我之前做 SaaS 产品时，研究过一阵用户引导（Onboarding）设计。产品领域有个共识：新用户在产品里前 5 分钟找不到「Aha moment」，大概率就流失了。工程师加入团队也类似——第一周如果建立不起「我能在这个项目里交付价值」的信心，后面几个月都会处于被动跟随的状态。

后来我把产品侧的引导清单思路搬到工程团队里，在几个项目组试过，逐渐沉淀出一套可复用的模板。这篇文章把模板和踩过的坑一起讲清楚。

为什么清单能起作用

新人入职时面对三个隐性障碍：

1. 不知道先做什么 — 信息太多，分不清优先级。
2. 不知道做到什么程度算完成 — 任务模糊，没有验收标准。
3. 不知道卡住了该问谁 — 没有明确的求助通道。

一份好的清单同时解决这三个问题。本质上，它是把团队的认知负荷替新人分担了。

心理学上有个概念叫「目标梯度效应」（Goal Gradient Effect）——当人能看到自己距离目标还有多远时，完成动力会显著提升。行为心理学家 Clark Hull 在 1932 年的实验中首次验证了这个现象，后来被广泛应用到产品设计中。可见的进度条、可勾选的任务项，都能让用户（包括新人）更有动力走完剩下的步骤。

DesignerUp 的研究者研究了 200 多个产品的引导流程，总结了三个共性规律：

• 分角色设计路径 — 工程师、设计师、PM 的清单不该一样。
• 渐进式披露 — 不要一次性把信息全倒出来，到哪个阶段给哪个阶段的内容。
• 用真实行为推进 — 不是点「下一步」，而是完成一个真实的小任务来解锁下一步。

这三条直接影响了后面模板的设计原则。

三个案例

案例一：环境配置地狱

场景：一个中等规模的 B2C 项目组，前端用 React + Vite，后端 Go。之前团队的环境文档只有 README 里一段 15 行的说明。

翻车：连续两个新人在环境配置上卡了超过两天。第一个因为 Node 版本不对，pnpm install 直接报错；第二个装了正确版本，但 postinstall 脚本需要内网 npm registry，文档里没写。第三天他拉了个 30 分钟的会专门问环境，结果发现组里三个人给的解决方案都不一样。

修复：写了一个环境自检脚本，同时把清单从「文字列表」改成「可执行 + 可验证」的形式。

坏做法 — 纯文字 README：

## 环境准备
- Node.js >= 18
- pnpm 8+
- Go 1.21+
- 配置内网 registry

好做法 — 带版本检测和自动修复的脚本：

#!/usr/bin/env bash
# scripts/verify-env.sh
# 新人运行一次就知道哪里不对，不用靠猜
 
set -euo pipefail
 
RED='\033[0;31m'
GREEN='\033[0;32m'
NC='\033[0m'
ERRORS=0
 
# Node 版本检测（检查 major 号，不只检查命令是否存在）
if command -v node &> /dev/null; then
  NODE_MAJOR=$(node -v | cut -d'.' -f1 | tr -d 'v')
  if [ "$NODE_MAJOR" -ge 22 ]; then
    echo -e "${GREEN}✓ Node.js $(node -v)${NC}"
  else
    echo -e "${RED}✗ Node.js 需要 >= 22，当前 $(node -v)${NC}"
    echo "  → 运行: nvm install 22 && nvm use 22"
    ERRORS=$((ERRORS + 1))
  fi
else
  echo -e "${RED}✗ Node.js 未安装${NC}"
  echo "  → 参考: https://nodejs.org/ 或 nvm install 22"
  ERRORS=$((ERRORS + 1))
fi
 
# pnpm 和 Go 版本检测省略，结构同上
# ...
 
# 最终汇总，一目了然
if [ $ERRORS -eq 0 ]; then
  echo -e "${GREEN}✓ 环境检查通过，可以开始开发了${NC}"
else
  echo -e "${RED}✗ 发现 $ERRORS 个问题，请按上方提示修复后重新运行${NC}"
  exit 1
fi

这个脚本本身只有 50 行，但把新人配环境的平均耗时从 2.5 天降到了 2 小时。核心区别是：脚本把「隐性知识」变成了「可执行、可验证、可报错」的程序。新人不需要问任何人，跑一次脚本就知道自己差什么。

案例二：代码规范认知断层

场景：一个 B2B SaaS 团队，TypeScript + Next.js，PR 审查比较严格。

翻车：一个新人入职第二周提了 3 个 PR，全部被要求大改。不是逻辑错误——他习惯用 var 声明（老项目遗留），团队用 const 优先；他写的组件没有 Server Component 标记；commit message 是英文的自由格式。三个 PR 改了两天，新人心态崩了。

问题根因：清单上写了「阅读代码规范」，但没有设置验收标准。「阅读」不等于「理解」，更不等于「能在实际代码中应用」。

修复：在清单里加了一个「代码规范实战」环节，要求新人先看规范，再看 3 个最近的已合并 PR，然后做一个只改格式的小 PR。

坏做法 — 只有文字要求的清单：

onboarding_tasks:
  - name: 阅读代码规范
    action: 阅读 CONTRIBUTING.md
    # 没有验收标准，无法确认是否真正理解

好做法 — 带验收标准和渐进式任务的清单：

onboarding_tasks:
  - name: 代码规范学习
    tasks:
      - step: 阅读 CONTRIBUTING.md
        focus: 重点看「组件职责划分」和「Git 规范」两节
        # 标注阅读重点，新人不用逐字通读
 
      - step: 阅读最近 3 个已合并的 PR
        action: 关注 commit message 格式、文件组织、测试写法
        # 用真实代码做教材，比规范文档更直观
 
      - step: 提交一个只改格式的 PR
        scope: 选一个小组件，只改命名和注释，不动逻辑
        acceptance: 一次通过 review，不需要大改
        # 用低风险操作验证规范是否真正理解

改完之后，新人第一周提的 PR 一次通过率从 33% 提升到 80%。关键改动是把「阅读」变成了「阅读 → 观察 → 实践」三步，每一步都有明确的产出。

案例三：架构认知迷宫

场景：一个推荐系统项目组，核心代码 20 万行，有完整的架构文档、API 文档和数据流图。

翻车：新来的工程师被要求「先看文档」。他花了三天看了四篇文档，每篇都讲不同层级的东西，看完之后仍然不知道第一个代码改动应该从哪里下手。第四天他随便挑了一个文件改了改，提交了一个没人看得懂的 PR。

问题根因：文档是「全景式」的，而新人需要的是「导航式」的阅读路径。全景文档适合老人查阅，不适合新人入门。

修复：把文档阅读任务拆成了渐进式的三步，每一步都有明确的「读完之后要能回答的问题」。

architecture_reading_plan:
  - level: 第一天
    scope: 只读 docs/architecture/overview.md 的前三节
    # 限制阅读量，防止信息过载
    deliverable: 能画出系统的一级模块关系图
    # 用输出倒逼输入，读完能画出来才算理解
 
  - level: 第二到三天
    scope: 精读 src/core/ 目录下 README 标注的 3 个核心文件
    files:
      - path: src/core/pipeline.ts
        focus: 数据从进入到输出的完整流转路径
      - path: src/core/store.ts
        focus: 状态是怎么管理的，有哪些全局状态
      - path: src/core/scheduler.ts
        focus: 任务调度的触发时机和执行顺序
    deliverable: 能口头解释一个请求从 API 到数据库的完整路径
 
  - level: 第四到五天
    scope: 做一个只读任务
    task: 写一个集成测试，覆盖 pipeline.ts 的一条核心路径
    acceptance: 测试能跑通，且被至少一个老人 review
    # 通过写测试来验证理解，比看文档有效得多

这个方案的核心理念来自一个朴素的认识：新人不是来「读文档」的，是来「写代码」的。所有文档阅读都应该以「能写出什么」作为验收标准，而不是「读了多少」。

Onboarding 全流程

下面这个流程图展示了清单在完整入职周期中的位置和节奏。核心思路是「渐进式披露」——每个阶段只关注当前最重要的事，不提前暴露后续内容。

几个关键节点说明：

• Offer 接受到入职前这段时间经常被浪费。很多团队等到入职当天才开始配环境，白白丢了两三天。如果能在 Offer 接受后就发送环境预检清单，新人入职第一天就能直接开始。
• 「卡住超过 2 小时」触发求助，这个规则很重要。新人经常不知道什么时候该问人，给自己设一个时间上限能避免无效的死磕。
• Buddy 渐进退出，不是一下子撤走。前两周 Buddy 每天花 15 分钟 check-in，第三周开始按需答疑，一个月后完全独立。

清单模板全貌

下面是实际使用的清单模板。按阶段分组，每项有明确的验收标准。

阶段一：入职前（远程完成）

• 收到团队 Wiki 链接和核心文档目录
• 运行 scripts/verify-env.sh，环境检测全部通过
• 完成 Git、npm registry、VPN 等基础账号配置
• 添加 Buddy 的即时通讯，完成一次简单对话

阶段二：第一天

• git clone 项目并成功运行 pnpm install && pnpm dev
• 运行 pnpm verify 全部通过（lint + typecheck + test）
• 阅读 CONTRIBUTING.md，能说出分支命名和 commit 格式
• 和 Buddy 完成 30 分钟 1:1，了解团队分工和当前迭代

阶段三：第一周

• 画出系统的一级模块关系图（能向 Buddy 口头讲清楚）
• 阅读 3 个最近合并的 PR，理解代码风格和审查标准
• 提交第一个格式修正 PR（一次通过 review）
• 提交第一个功能/修复 PR，被合并到主分支
• 参加一次 Sprint Planning，能看懂任务拆分逻辑
• 了解发布流程：能在 staging 环境跑通部署
• 阅读事故复盘文档（如有），了解系统的核心风险点

阶段四：第二周

• 独立承担一个小需求（预估 1-2 天工作量）
• 参与至少一次 Code Review，作为 Reviewer 给出有效意见
• 了解监控和告警：能看到自己负责模块的错误率
• 和 Buddy 一起走一遍发布流程（含回滚步骤）

指定两个联系人

每个新人配两个联系人，缺一不可：

不要让新人只能靠猜来理解系统。很多架构决策背后的业务原因，代码里看不出来，必须有人讲。

好清单和坏清单的对比

不同阶段的侧重点

清单本身的维护

清单不是一次性文档。它需要像代码一样维护。

我通常用两个信号判断清单是否需要更新：

1. 新人经常卡在同一步 — 说明这一步的指引不够清晰，或者环境变了。
2. 某一步新人总是 5 分钟搞定 — 说明这一步已经不需要了，可以删除或合并。

下面这个脚本是我用来追踪清单健康度的。每次新人完成清单时运行一次，自动统计每个步骤的耗时：

# scripts/onboarding_metrics.py
# 根据 Buddy 填写的完成记录，生成每个步骤的平均耗时和失败率
 
import json
from pathlib import Path
from datetime import datetime
 
DATA_DIR = Path("data/onboarding-records")
 
def load_records():
    """加载所有新人的完成记录"""
    records = []
    for f in DATA_DIR.glob("*.json"):
        records.append(json.loads(f.read_text()))
    return records
 
def generate_report(records):
    """按步骤汇总统计，找出卡住点"""
    step_stats = {}
    for r in records:
        for item in r["checklist"]:
            name = item["step"]
            if name not in step_stats:
                step_stats[name] = {
                    "completions": 0,
                    "total_hours": 0,
                    "blocked_count": 0,  # 卡住超过 2 小时的次数
                }
            step_stats[name]["completions"] += 1
            step_stats[name]["total_hours"] += item.get("hours_spent", 0)
            if item.get("was_blocked", False):
                step_stats[name]["blocked_count"] += 1
 
    # 按失败率排序，优先改进失败率高的步骤
    for name, stats in sorted(
        step_stats.items(),
        key=lambda x: x[1]["blocked_count"] / max(x[1]["completions"], 1),
        reverse=True,
    ):
        avg = stats["total_hours"] / max(stats["completions"], 1)
        fail_rate = stats["blocked_count"] / max(stats["completions"], 1) * 100
        # 失败率超过 30% 的步骤需要优先优化指引
        print(f"{name}: 平均 {avg:.1f}h, 卡住率 {fail_rate:.0f}%")
 
if __name__ == "__main__":
    generate_report(load_records())

每月看一次这个报告，失败率超过 30% 的步骤就是清单需要优化的地方。清单的维护和代码重构一样——数据驱动，不靠感觉。

清单落地方式对比

我的建议是：先从 Markdown 开始。原因很简单——维护成本最低，和代码在同一个仓库，改了清单会走 PR 审查，天然有版本记录。等团队超过 15 人、或者多个项目组共用一份清单时，再考虑迁移到更重的工具。

完整检查清单

按阶段分组，共 26 项。可以直接复制使用，根据团队实际情况裁剪。

入职前

• 团队 Wiki / 核心文档链接已发送
• 环境自检脚本（verify-env.sh）运行通过
• 基础账号申请完成（Git、npm registry、CI、监控平台）
• 与 Buddy 建立联系，完成首次沟通

第一天

• 项目 clone + install + dev 一次跑通
• pnpm verify（或等效验证命令）全部通过
• 阅读 CONTRIBUTING.md，能复述分支和 commit 规范
• 与 Buddy 完成 30 分钟 1:1

第一周

• 能画出系统一级模块关系图
• 阅读 3 个已合并 PR，理解代码风格
• 提交一个纯格式修正 PR 并一次通过
• 提交一个功能 / 修复 PR 并被合并
• 参加 Sprint Planning，理解任务拆分逻辑
• 在 staging 环境完成一次部署
• 阅读至少一篇事故复盘文档

第二周

• 独立承担一个 1-2 天的小需求
• 作为 Reviewer 参与一次 Code Review
• 了解负责模块的监控和告警配置
• 与 Buddy 一起完成一次完整发布流程

持续跟进（第一个月内）

• Buddy 每日 check-in（15 分钟），两周后改为按需
• 第二周末做一次 1:1 回顾，收集对清单的反馈
• 月底评估：新人是否能独立完成需求 → Buddy 退出日常

成熟度参考

最后用一个成熟度表做收尾。不需要一步到位，先做到 Level 1，跑顺了再往上升。

关键原则：第一版不需要完美，但需要能跑。见过太多团队花两周做了一个精美的 Onboarding 页面，结果新人入职后发现链接是坏的、步骤是过时的，反而更打击信心。先把 Level 1 跑起来，再慢慢迭代。

参考资料

• I Studied the UX/UI of Over 200 Onboarding Flows — DesignerUp
• SaaS Onboarding Checklist: Step-by-Step Guide (2026) — Jimo
• Onboarding Checklist: Definition, Design Best Practices — Jimo
• SaaS 中 6 种常见 UI 入职模式 — 知乎专栏
• 如何设计用户引导：3 大策略和 7 个常见错误 — 知乎
• The Twelve-Factor App: 配置与依赖 — 12factor.net
• Clark Hull — Goal Gradient Effect — Wikipedia
• Apple HIG: 用户引导 — developer.apple.com