Developer Onboarding Builder

开发者入职文档构建器

Create frictionless first-day experiences for new team members.

为新团队成员打造顺畅的首日体验。

Core Workflow

核心工作流程

Assess prerequisites: Identify required tools and access
Create setup guide: Step-by-step environment configuration
Design first task: Choose appropriate starter assignment
Add time estimates: Set expectations for each step
Document common issues: Preemptive troubleshooting
Introduce team: Context on people and structure
Provide codebase tour: Walkthrough of key areas

评估前置条件：确定所需工具与访问权限
创建搭建指南：分步完成环境配置
设计首项任务：选择合适的入门任务
添加时间预估：明确各步骤的时间预期
记录常见问题：提前整理故障排查方案
介绍团队成员：说明团队人员架构
提供代码库漫游：讲解代码关键区域

Onboarding Documentation Structure

入职文档结构

ONBOARDING.md Template

ONBOARDING.md 模板

markdown

undefined

markdown

undefined

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

本指南将帮助你在首日完成环境搭建并进入工作状态。

预计完成时间：2-3小时

Before You Start

开始之前

Access Checklist

访问权限清单

GitHub组织访问权限
Slack工作区邀请
邮箱账户配置
VPN凭证（远程办公时）
云控制台访问权限（AWS/GCP/Azure）
CI/CD仪表盘访问权限
项目管理工具（Jira/Linear）

Tools to Install

需安装的工具

Day 1: Environment Setup

首日：环境搭建

Step 1: Clone Repository (5 min)

步骤1：克隆代码仓库（5分钟）

bash

git clone git@github.com:company/project-name.git
cd project-name


**Why:** Get the codebase on your machine

**Troubleshooting:**

- SSH key not working? See [GitHub SSH setup](https://docs.github.com/en/authentication/connecting-to-github-with-ssh)
- Permission denied? Ask your manager to verify GitHub access

bash

git clone git@github.com:company/project-name.git
cd project-name


**原因**：将代码库同步到本地机器

**故障排查**：

- SSH密钥无法使用？查看[GitHub SSH设置](https://docs.github.com/en/authentication/connecting-to-github-with-ssh)
- 权限被拒绝？请经理核实你的GitHub访问权限

Step 2: Install Dependencies (10 min)

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

bash

undefined

bash

undefined

Install Volta (Node version manager)

安装Volta（Node版本管理器）

curl https://get.volta.sh | bash

Install dependencies

安装依赖

pnpm install


**Expected output:** "Dependencies installed successfully"

**Troubleshooting:**

- `pnpm not found`? Restart terminal or run `volta install pnpm`
- Installation hangs? Check VPN connection

pnpm install


**预期输出**："Dependencies installed successfully"

**故障排查**：

- 提示`pnpm not found`？重启终端或执行`volta install pnpm`
- 安装停滞？检查VPN连接状态

Step 3: Configure Environment (10 min)

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

bash

undefined

bash

undefined

Copy environment template

复制环境变量模板

cp .env.example .env


**Edit `.env` with these values:**

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


**Get credentials from:**

- Database: Local setup (see next step)
- API keys: Ask @alice or @bob on Slack #dev-onboarding
- External services: Check 1Password vault "Dev Credentials"

**Troubleshooting:**

- Can't find credentials? Post in #dev-onboarding
- Missing env var? Check .env.example for all required variables

cp .env.example .env


**编辑`.env`文件，填入以下值**：

DATABASE_URL=postgresql://postgres:password@localhost:5432/projectname_dev REDIS_URL=redis://localhost:6379 API_KEY=向团队索要开发密钥


**获取凭证的渠道**：

- 数据库：本地搭建（见下一步）
- API密钥：在Slack的#dev-onboarding频道@alice或@bob
- 外部服务：查看1Password的「开发凭证」保险箱

**故障排查**：

- 找不到凭证？在#dev-onboarding频道提问
- 缺少环境变量？查看.env.example中的所有必填变量

Step 4: Setup Database (15 min)

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

bash

undefined

bash

undefined

Start PostgreSQL with Docker

使用Docker启动PostgreSQL

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


**Expected output:** "Migration complete. Database seeded."

**Verify:** Open http://localhost:5432 and check for tables

**Troubleshooting:**

- Port 5432 already in use? Kill existing process: `lsof -ti:5432 | xargs kill`
- Migration fails? Drop and recreate: `pnpm db:reset`

pnpm db:seed


**预期输出**："Migration complete. Database seeded."

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

**故障排查**：

- 端口5432已被占用？终止现有进程：`lsof -ti:5432 | xargs kill`
- 迁移失败？重置数据库：`pnpm db:reset`

Step 5: Start Development Server (5 min)

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

bash

pnpm dev

Expected output:

✓ Ready on http://localhost:3000

Test: Open http://localhost:3000 - you should see the homepage

Troubleshooting:

Port 3000 in use? Kill process or change PORT in .env
Build errors? Clear cache:
```
rm -rf .next && pnpm dev
```

bash

pnpm dev

预期输出：

✓ Ready on http://localhost:3000

测试：打开http://localhost:3000 - 你应该能看到首页

故障排查：

端口3000已被占用？终止进程或修改.env中的PORT值
构建报错？清除缓存：
```
rm -rf .next && pnpm dev
```

Step 6: Run Tests (5 min)

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

bash

pnpm test

Expected output: All tests passing ✓

If tests fail:

First time? This is a bug! Report in #dev-help
Known issue? Check #dev-help pinned messages

bash

pnpm test

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

如果测试失败：

首次运行？这是一个Bug！在#dev-help频道上报
已知问题？查看#dev-help频道的置顶消息

Day 1: Your First Task

首日：你的首项任务

Task: Fix a Starter Issue

任务：修复入门级Issue

We've labeled some issues as

good-first-issue

for new team members.

Goal: Successfully complete one small PR to learn our workflow

Steps:

Browse good first issues
Pick one that interests you (or ask for suggestion in #dev-onboarding)
Comment on the issue: "I'll take this!"

Create a branch:

git checkout -b fix/issue-123-description

Make your changes
Write/update tests
Run
```
pnpm lint
```
and
```
pnpm test
```
Commit following conventions
Push and create PR
Request review from your mentor

Estimated time: 2-4 hours

Success criteria:

Branch created with proper name
Code changes made
Tests written/updated
All checks passing
PR created with description
Code reviewed and merged

Mentors: @alice (backend), @bob (frontend), @charlie (full-stack)

我们为新成员标记了一些

good-first-issue

级别的问题。

目标：成功完成一个小型PR，熟悉我们的工作流程

步骤：

浏览入门级Issue
挑选一个你感兴趣的（或在#dev-onboarding频道寻求建议）
在Issue下评论："I'll take this!"

创建分支：

git checkout -b fix/issue-123-description

进行代码修改
编写/更新测试用例
执行
```
pnpm lint
```
和
```
pnpm test
```
按照提交规范提交代码
推送分支并创建PR
邀请你的导师进行代码评审

预计耗时：2-4小时

成功标准：

创建了命名规范的分支
完成了代码修改
编写/更新了测试用例
所有检查项通过
创建了带描述的PR
代码通过评审并合并

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

Day 2-3: Codebase Tour

第2-3天：代码库漫游

Project Structure Overview

项目结构概览

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/              # Next.js路由（从这里开始！）
│   ├── api/          # API端点
│   └── (auth)/       # 认证页面
├── components/       # React组件
│   ├── ui/           # 基础UI组件
│   └── features/     # 业务特性组件
├── lib/              # 工具函数与辅助模块
│   ├── api/          # API客户端
│   ├── hooks/        # 自定义React Hooks
│   └── utils/        # 通用辅助函数
├── services/         # 业务逻辑层
└── types/            # TypeScript类型定义

Key Files to Understand

核心文件说明

File	What It Does	When You'll Touch It
`src/app/layout.tsx`	Root layout & providers	Adding global providers
`src/lib/db.ts`	Database client	Database queries
`src/lib/auth.ts`	Authentication logic	Auth-related features
`src/middleware.ts`	Request middleware	Adding auth/redirects

文件路径	功能说明	使用场景
`src/app/layout.tsx`	根布局与全局提供者	添加全局提供者时
`src/lib/db.ts`	数据库客户端	编写数据库查询时
`src/lib/auth.ts`	认证逻辑实现	开发认证相关功能时
`src/middleware.ts`	请求中间件	添加认证/跳转逻辑时

Walking Tour (Read These Files in Order)

漫游指南（按顺序阅读以下文件）

src/app/page.tsx
- Homepage (entry point)
src/app/api/users/route.ts
- Simple API endpoint
src/services/user.service.ts
- Business logic example
src/components/ui/button.tsx
- UI component pattern
src/lib/hooks/useUser.ts
- Custom hook example

Exercise: Find the code that handles user registration. Hint: Start at the API route!

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

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

Common Patterns

常见代码模式

API Route Pattern

typescript

// 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
}

Service Layer Pattern

typescript

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

API路由模式

typescript

// src/app/api/[resource]/route.ts
export async function GET(req: Request) {
  // 1. 验证认证信息
  // 2. 解析请求参数
  // 3. 调用业务逻辑层
  // 4. 返回响应结果
}

业务逻辑层模式

typescript

// src/services/[resource].service.ts
export class UserService {
  async create(data: CreateUserDto) {
    // 1. 验证数据合法性
    // 2. 执行业务逻辑
    // 3. 执行数据库操作
    // 4. 返回处理结果
  }
}

Week 1: Learning Path

第一周：学习路径

Day 1

第1天

Complete environment setup
Fix first issue
Meet your team (schedule 1:1s)

完成环境搭建
修复首个Issue
与团队成员见面（预约一对一沟通）

Day 2-3

第2-3天

Read codebase tour documents
Complete second issue (medium complexity)
Review 2-3 PRs from teammates

阅读代码库漫游文档
完成第二个中等复杂度的Issue
评审2-3个团队成员的PR

Day 4-5

第4-5天

Work on first feature (with mentor pairing)
Attend team standup/planning
Set up development tools (linters, extensions)

在导师配对指导下开发首个功能
参加团队站会与规划会议
配置开发工具（代码检查器、编辑器扩展）

Team Structure

团队架构

Engineering Team

技术团队

Alice (@alice) - Tech Lead

Approves architecture decisions
Code review on complex PRs
Ask: System design questions

Bob (@bob) - Senior Backend Engineer

Database and API expert
Ask: Backend, performance questions

Charlie (@charlie) - Senior Frontend Engineer

UI/UX implementation
Ask: React, styling questions

Your Manager (@manager)

Weekly 1:1s on Fridays 2pm
Career development discussions
Ask: Process, priorities, career questions

Alice (@alice) - 技术负责人

审批架构决策
负责复杂PR的代码评审
咨询方向：系统设计相关问题

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

数据库与API专家
咨询方向：后端开发、性能优化问题

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

UI/UX实现专家
咨询方向：React、样式设计问题

你的经理 (@manager)

每周五下午2点进行一对一沟通
职业发展规划讨论
咨询方向：流程规范、工作优先级、职业发展问题

Communication Channels

沟通渠道

#dev-general - General development discussion
#dev-help - Ask questions, get unstuck
#dev-onboarding - New member support
#dev-releases - Release announcements
#dev-alerts - Production alerts

#dev-general - 通用技术讨论
#dev-help - 技术问题求助
#dev-onboarding - 新成员支持
#dev-releases - 版本发布公告
#dev-alerts - 生产环境告警

Meeting Schedule

会议安排

Daily Standup - 10:00 AM (15 min)
Sprint Planning - Mondays 2:00 PM (1 hour)
Team Retro - Fridays 4:00 PM (45 min)
Tech Talks - Thursdays 3:00 PM (30 min)

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

Development Workflow

开发工作流程

Daily Workflow

日常工作流程

Morning: Check Slack, pull latest main
Standup: Share yesterday, today, blockers
Code: Work on assigned tickets
Lunch: Team usually eats at 12:30
Afternoon: Continue coding, review PRs
End of day: Update ticket status, push work

上午：查看Slack消息，拉取最新的main分支代码
站会：分享昨日工作、今日计划与阻塞问题
编码：处理分配的任务
午餐：团队通常在12:30用餐
下午：继续编码，评审PR
下班前：更新任务状态，推送代码

PR Review Guidelines

PR评审规范

When reviewing PRs:

Check code quality and style
Verify tests cover changes
Run the code locally if significant
Ask questions if unclear
Approve when satisfied

评审PR时需检查：

代码质量与风格
测试用例是否覆盖修改内容
重大修改需本地运行验证
对不清晰的地方提出疑问
满意后批准PR

Getting Code Reviewed

申请代码评审

Common Gotchas

常见陷阱

Database

数据库相关

Problem:

relation "users" does not exist

Solution: Run migrations:

pnpm db:migrate

Problem: Seed data not appearing Solution: Reset database:

pnpm db:reset

问题：

relation "users" does not exist

解决方案：执行数据库迁移：

pnpm db:migrate

问题：测试数据未显示 解决方案：重置数据库：

pnpm db:reset

Development Server

开发服务器相关

Problem: Changes not reflecting Solution:

Hard refresh (Cmd+Shift+R)
Clear .next folder:
```
rm -rf .next
```
Restart dev server

Problem: Port already in use Solution: Kill process:

lsof -ti:3000 | xargs kill

问题：代码修改未生效 解决方案：

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

问题：端口已被占用 解决方案：终止进程：

lsof -ti:3000 | xargs kill

Environment

环境变量相关

Problem: Missing environment variable Solution: Check .env.example, add to your .env

Problem: API key not working Solution: Verify it's the dev key, not prod (ask team)

问题：缺少环境变量 解决方案：查看.env.example文件，补充到你的.env中

问题：API密钥无效 解决方案：确认使用的是开发密钥而非生产密钥（可咨询团队）

Resources

资源汇总

Documentation

项目文档

Architecture Overview
API Reference
Contributing Guide
Style Guide

架构概述
API参考
贡献指南
编码规范

Learning Resources

学习资源

Internal Resources

内部资源

Company Wiki: https://wiki.company.com
Design System: https://design.company.com
API Playground: https://api-dev.company.com

Getting Help

求助指南

When You're Stuck (5-15-30 Rule)

遇到问题时的5-15-30规则

5 minutes: Try to solve it yourself
15 minutes: Search docs, Stack Overflow, past issues
30 minutes: Ask in #dev-help with context

5分钟：尝试自行解决
15分钟：查阅文档、Stack Overflow、历史Issue
30分钟：在#dev-help频道提问并提供上下文

Good Question Template

规范提问模板

**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]

**我要实现的目标**：[具体需求]
**已尝试的操作**：[执行步骤]
**错误信息**：[完整错误内容]
**环境信息**：[操作系统、Node版本等]
**相关代码**：[文件/行号链接]

Who to Ask

求助对象

Setup issues: #dev-onboarding or #dev-help
Code questions: #dev-help or your mentor
Process questions: Your manager
Urgent/production: #dev-alerts

环境搭建问题：#dev-onboarding或#dev-help频道
代码问题：#dev-help频道或你的导师
流程问题：你的经理
紧急/生产环境问题：#dev-alerts频道

Week 1 Checklist

第一周完成清单

By end of week 1, you should have:

Completed environment setup
Fixed 2-3 good-first-issues
Created first feature PR
Met with all team members
Attended all team meetings
Read key documentation
Understood development workflow
Know how to get help

Feedback

反馈收集

We're always improving onboarding! Please share:

What went well?
What was confusing?
What's missing?

Share in: #dev-onboarding or with your manager

Welcome to the team! We're excited to have you here! 🚀

undefined

我们持续优化入职流程！欢迎分享：

哪些环节体验良好？
哪些环节存在困惑？
缺少哪些内容？

反馈渠道：#dev-onboarding频道或与你的经理沟通

欢迎加入团队！我们很开心有你！🚀

undefined

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

第1天：环境搭建与简单任务
第1周：熟悉代码模式
第1个月：独立开发功能

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)

优质的入门任务需满足：

可在2-4小时内完成
轻度涉及多个技术领域
有明确的验收标准
需要提交PR并经过评审
具备实际业务价值（而非无意义的任务）
有导师可提供支持

示例：

修复错误提示中的拼写错误（涉及：前端、国际化、测试）
为API端点添加校验逻辑（涉及：后端、测试、文档）
优化加载状态（涉及：前端、UX、组件）

Documentation Components

文档核心模块

Essential Sections

必备章节

Prerequisites and access
Step-by-step setup with time estimates
First task assignment
Codebase tour
Team structure
Communication channels
Common issues and solutions
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)

undefined

完整的入职包需包含：

带分步指南的ONBOARDING.md
各步骤的时间预估
明确并记录的首项任务
团队架构与沟通渠道
常见问题的故障排查方案
所有必要资源的链接
进度跟踪检查清单
反馈收集机制
导师分配
预期时间线（日/周/月）

undefined

dev-onboarding-builder

Original

Translation

Developer Onboarding Builder

开发者入职文档构建器

Core Workflow

核心工作流程

Onboarding Documentation Structure

入职文档结构

ONBOARDING.md Template

ONBOARDING.md 模板

Welcome to [Team/Project Name]! 🎉

欢迎加入[团队/项目名称]！🎉

Before You Start

开始之前

Access Checklist

访问权限清单

Tools to Install

需安装的工具

Day 1: Environment Setup

首日：环境搭建

Step 1: Clone Repository (5 min)

步骤1：克隆代码仓库（5分钟）

Step 2: Install Dependencies (10 min)

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

Install Volta (Node version manager)

安装Volta（Node版本管理器）

Install dependencies

安装依赖

Step 3: Configure Environment (10 min)

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

Copy environment template

复制环境变量模板

Step 4: Setup Database (15 min)

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

Start PostgreSQL with Docker

使用Docker启动PostgreSQL

Run migrations

执行数据库迁移

Seed with test data

导入测试数据

Step 5: Start Development Server (5 min)

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

Step 6: Run Tests (5 min)

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

Day 1: Your First Task

首日：你的首项任务

Task: Fix a Starter Issue

任务：修复入门级Issue

Day 2-3: Codebase Tour

第2-3天：代码库漫游

Project Structure Overview

项目结构概览

Key Files to Understand

核心文件说明

Walking Tour (Read These Files in Order)

漫游指南（按顺序阅读以下文件）

Common Patterns

常见代码模式

Week 1: Learning Path

第一周：学习路径

Day 1

第1天

Day 2-3

第2-3天

Day 4-5

第4-5天

Team Structure

团队架构

Engineering Team

技术团队

Communication Channels

沟通渠道

Meeting Schedule

会议安排

Development Workflow

开发工作流程

Daily Workflow

日常工作流程

PR Review Guidelines