dev-onboarding-builder

Developer Onboarding Builder

为新团队成员打造顺畅无阻的第一天体验。

核心工作流

1. 评估前置条件：确定所需工具和访问权限
2. 创建设置指南：逐步配置环境
3. 设计首个任务：选择合适的入门任务
4. 添加时间估算：明确每个步骤的预期用时
5. 记录常见问题：提前准备故障排查指南
6. 介绍团队：说明团队成员和组织结构
7. 介绍代码库：讲解关键区域

入职文档结构

ONBOARDING.md 模板

# Welcome to [Team/Project Name]! 🎉

This guide will help you get set up and productive on your first day.

**Estimated completion time:** 2-3 hours

## Before You Start

### Access Checklist

- [ ] GitHub organization access
- [ ] Slack workspace invitation
- [ ] Email account setup
- [ ] VPN credentials (if remote)
- [ ] Cloud console access (AWS/GCP/Azure)
- [ ] CI/CD dashboard access
- [ ] Project management tool (Jira/Linear)

### Tools to Install

- [ ] Node.js 20+ (via [Volta](https://volta.sh/))
- [ ] pnpm 8+
- [ ] Docker Desktop
- [ ] PostgreSQL 15+
- [ ] VS Code or preferred editor
- [ ] Git configured with your work email

## Day 1: Environment Setup

### Step 1: Clone Repository (5 min)

```bash
git clone [email protected]:company/project-name.git
cd project-name
```

原因： 将代码库克隆到本地

故障排查：

• SSH 密钥无法使用？参阅 GitHub SSH 设置
• 权限被拒绝？请经理确认 GitHub 访问权限

步骤 2：安装依赖（10 分钟）

# Install Volta (Node version manager)
curl https://get.volta.sh | bash

# Install dependencies
pnpm install

预期输出：“依赖安装成功”

故障排查：

• 找不到 pnpm？重启终端，或运行 volta install pnpm
• 安装卡住了？检查 VPN 连接

步骤 3：配置环境（10 分钟）

# Copy environment template
cp .env.example .env

使用以下值编辑 .env：

DATABASE_URL=postgresql://postgres:password@localhost:5432/projectname_dev
REDIS_URL=redis://localhost:6379
API_KEY=ask-team-for-dev-key

获取凭据：

• 数据库：本地设置（见下一步）
• API 密钥：在 Slack 的 #dev-onboarding 中询问 @alice 或 @bob
• 外部服务：查看 1Password 密钥库“Dev Credentials”

故障排查：

• 找不到凭据？在 #dev-onboarding 中发帖
• 缺少环境变量？查看 .env.example，了解所有必需变量

步骤 4：设置数据库（15 分钟）

# Start PostgreSQL with Docker
docker run --name project-postgres \
  -e POSTGRES_PASSWORD=password \
  -p 5432:5432 \
  -d postgres:15

# Run migrations
pnpm db:migrate

# Seed with test data
pnpm db:seed

预期输出：“迁移完成。数据库已填充初始数据。”

**验证：**打开 http://localhost:5432 并检查是否存在数据表

故障排查：

• 端口 5432 已被占用？终止现有进程：lsof -ti:5432 | xargs kill
• 迁移失败？删除并重新创建：pnpm db:reset

步骤 5：启动开发服务器（5 分钟）

pnpm dev

预期输出：

✓ Ready on http://localhost:3000

**测试：**打开 http://localhost:3000，应能看到主页

故障排查：

• 端口 3000 已被占用？终止进程，或在 .env 中更改 PORT
• 构建错误？清除缓存：rm -rf .next && pnpm dev

步骤 6：运行测试（5 分钟）

pnpm test

**预期输出：**所有测试均通过 ✓

如果测试失败：

• 第一次运行？这是一个错误！在 #dev-help 中报告
• 已知问题？查看 #dev-help 中置顶的消息

第 1 天：你的首个任务

任务：修复入门问题

我们已将一些问题标记为 good-first-issue，供新团队成员处理。

**目标：**成功完成一个小型 PR，了解我们的工作流

步骤：

1. 浏览适合新手的问题
2. 选择一个你感兴趣的问题（或在 #dev-onboarding 中寻求建议）
3. 在问题下评论：“我来处理！”
4. 创建分支：git checkout -b fix/issue-123-description
5. 进行修改
6. 编写或更新测试
7. 运行 pnpm lint 和 pnpm test
8. 按照约定提交
9. 推送并创建 PR
10. 请求导师审查

**预计用时：**2-4 小时

成功标准：

• 已按正确命名规则创建分支
• 已完成代码修改
• 已编写或更新测试
• 所有检查均已通过
• 已创建带有说明的 PR
• 代码已审查并合并

导师：@alice（后端）、@bob（前端）、@charlie（全栈）

第 2-3 天：代码库导览

项目结构概览

src/
├── app/              # Next.js routes (start here!)
│   ├── api/          # API endpoints
│   └── (auth)/       # Authentication pages
├── components/       # React components
│   ├── ui/           # Base UI components
│   └── features/     # Feature-specific components
├── lib/              # Utilities and helpers
│   ├── api/          # API client
│   ├── hooks/        # Custom React hooks
│   └── utils/        # Helper functions
├── services/         # Business logic layer
└── types/            # TypeScript definitions

需要了解的关键文件

文件	功能	何时会修改
src/app/layout.tsx	根布局和提供程序	添加全局提供程序
src/lib/db.ts	数据库客户端	执行数据库查询
src/lib/auth.ts	身份验证逻辑	开发身份验证相关功能
src/middleware.ts	请求中间件	添加身份验证或重定向

代码漫游（按顺序阅读这些文件）

1. src/app/page.tsx - 首页（入口）
2. src/app/api/users/route.ts - 简单的 API 端点
3. src/services/user.service.ts - 业务逻辑示例
4. src/components/ui/button.tsx - UI 组件模式
5. src/lib/hooks/useUser.ts - 自定义 Hook 示例

练习： 找出处理用户注册的代码。提示：从 API 路由开始！

常见模式

API 路由模式

// src/app/api/[resource]/route.ts
export async function GET(req: Request) {
  // 1. Validate auth
  // 2. Parse request
  // 3. Call service layer
  // 4. Return response
}

服务层模式

// src/services/[resource].service.ts
export class UserService {
  async create(data: CreateUserDto) {
    // 1. Validate data
    // 2. Business logic
    // 3. Database operation
    // 4. Return result
  }
}

第 1 周：学习路径

第 1 天

• 完成环境设置
• 修复第一个问题
• 认识团队成员（安排 1:1 会议）

第 2-3 天

• 阅读代码库漫游文档
• 完成第二个问题（中等复杂度）
• 查看队友的 2-3 个 PR

第 4-5 天

• 完成第一个功能（与导师结对）
• 参加团队每日站会／规划会议
• 配置开发工具（代码检查工具、扩展）

团队架构

工程团队

Alice (@alice) - 技术负责人

• 审批架构决策
• 审查复杂 PR 的代码
• 请教：系统设计问题

Bob (@bob) - 资深后端工程师

• 数据库和 API 专家
• 请教：后端、性能问题

Charlie (@charlie) - 资深前端工程师

• UI/UX 实现
• 请教：React、样式问题

你的经理 (@manager)

• 每周五下午 2 点进行 1:1 会议
• 职业发展讨论
• 请教：流程、优先级、职业发展问题

沟通渠道

• #dev-general - 一般开发讨论
• #dev-help - 提问并寻求帮助
• #dev-onboarding - 新成员支持
• #dev-releases - 发布公告
• #dev-alerts - 生产环境警报

会议安排

• 每日站会 - 上午 10:00（15 分钟）
• 冲刺规划 - 每周一下午 2:00（1 小时）
• 团队回顾会 - 每周五下午 4:00（45 分钟）
• 技术分享 - 每周四下午 3:00（30 分钟）

开发工作流

每日工作流

1. 上午： 查看 Slack，拉取最新的 main
2. 站会： 分享昨天完成的工作、今天的计划和阻碍
3. 编码： 处理分配的任务
4. 午餐： 团队通常在 12:30 用餐
5. 下午： 继续编码，审查 PR
6. 结束工作前： 更新任务状态，推送代码

PR 审查指南

审查 PR 时：

• 检查代码质量和风格
• 确认测试覆盖了变更
• 如果变更较大，在本地运行代码
• 有不清楚的地方就提问
• 确认满意后批准

请求代码审查

请求审查时：

• 先自行审查
• 添加清晰的说明
• 链接相关问题
• 标记合适的审查者
• 及时处理反馈

常见问题

数据库

问题： relation "users" does not exist 解决方案： 运行迁移：pnpm db:migrate

问题： 未显示种子数据 解决方案： 重置数据库：pnpm db:reset

开发服务器

问题： 更改未生效 解决方案：

1. 强制刷新（Cmd+Shift+R）
2. 清除 .next 文件夹：rm -rf .next
3. 重启开发服务器

问题： 端口已被占用 解决方案： 结束进程：lsof -ti:3000 | xargs kill

环境

问题： 缺少环境变量 解决方案： 检查 .env.example，并将其添加到你的 .env 文件

问题： API 密钥无法使用 解决方案： 确认这是开发环境密钥，而不是生产环境密钥（询问团队）

资源

文档

• 架构概览
• API 参考
• 贡献指南
• 风格指南

学习资源

• Next.js 文档
• Prisma 指南
• TypeScript 手册

内部资源

• 公司 Wiki：https://wiki.company.com
• 设计系统：https://design.company.com
• API 交互环境：https://api-dev.company.com

获取帮助

遇到困难时（5-15-30 规则）

• 5 分钟： 尝试自己解决
• 15 分钟： 搜索文档、Stack Overflow 和以往的问题
• 30 分钟： 在 #dev-help 中提供背景信息并提问

好问题模板

**What I'm trying to do:** [goal]
**What I tried:** [attempts]
**Error message:** [full error]
**Environment:** [OS, Node version, etc.]
**Related code:** [link to file/line]

可以向谁求助

• 设置问题： #dev-onboarding 或 #dev-help
• 代码问题： #dev-help 或你的导师
• 流程问题： 你的经理
• 紧急/生产问题： #dev-alerts

第 1 周检查清单

第 1 周结束时，你应该已经：

• 完成环境设置
• 修复 2-3 个适合新手的问题
• 创建第一个功能 PR
• 与所有团队成员见面
• 参加所有团队会议
• 阅读关键文档
• 了解开发工作流
• 知道如何寻求帮助

反馈

我们一直在改进入职流程！请分享：

• 哪些方面进展顺利？
• 哪些内容令人困惑？
• 还缺少什么？

分享至： #dev-onboarding 或告诉你的经理

---

欢迎加入团队！我们很高兴你能加入！🚀

## Onboarding Best Practices

### Time Estimates
- Be realistic with timing
- Include buffer for troubleshooting
- Track actual time vs estimated

### Progressive Complexity
- Day 1: Setup and simple task
- Week 1: Understanding patterns
- Month 1: Independent features

### Clear Success Criteria
- Checklist for each step
- Objective completion markers
- Regular check-ins

### Preemptive Troubleshooting
- Document known issues
- Provide solutions upfront
- Update based on new dev feedback

### Human Connection
- Introduce team members
- Schedule 1:1s
- Provide mentors

## First Task Selection Criteria

Good first task should:
- [ ] Be completable in 2-4 hours
- [ ] Touch multiple areas lightly
- [ ] Have clear acceptance criteria
- [ ] Require PR and review
- [ ] Be genuinely useful (not busy work)
- [ ] Have mentor availability

**Examples:**
- Fix typo in error message (touches: frontend, i18n, testing)
- Add validation to API endpoint (touches: backend, testing, docs)
- Improve loading state (touches: frontend, UX, components)

## Documentation Components

### Essential Sections
1. Prerequisites and access
2. Step-by-step setup with time estimates
3. First task assignment
4. Codebase tour
5. Team structure
6. Communication channels
7. Common issues and solutions
8. Resources and next steps

### Optional but Valuable
- Video walkthrough
- Pair programming schedule
- Reading list
- Architecture diagrams
- Glossary of terms

## Maintenance

### Keep Updated
- Review after each new hire
- Update tool versions
- Refresh access instructions
- Add new common issues

### Collect Feedback
- Exit survey after week 1
- Regular check-ins
- Track time to productivity
- Document pain points

## Output Checklist

Complete onboarding package includes:

- [ ] ONBOARDING.md with step-by-step guide
- [ ] Time estimates for each step
- [ ] First task identified and documented
- [ ] Team structure and communication
- [ ] Troubleshooting for common issues
- [ ] Links to all necessary resources
- [ ] Checklists for progress tracking
- [ ] Feedback mechanism
- [ ] Mentor assignments
- [ ] Expected timeline (day/week/month)