# Developer Onboarding

> 通过精心设计的快速入门、教程和示例应用，让开发者快速完成 "Hello World"。触发词：开发者入门、首次价值时间、快速入门指南、Hello World 教程、开发者激活、入门清单、示例应用、新手体验、降低...

- Skill: `kscz0000/developer-onboarding` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add kscz0000/developer-onboarding`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kscz0000/developer-onboarding/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: kscz0000 (https://skillmd.com/u/kscz0000)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/kscz0000/developer-onboarding

---


# 开发者入门
## 何时使用

当你需要通过精心设计的快速入门、教程和示例应用，让开发者快速完成 "Hello World" 时使用本技能。触发词：开发者入门、首次价值时间、快速入门指南、Hello World 教程、开发者激活、入门清单、示例应用、新手体验、降低...


让开发者从注册到跑通代码尽可能快，然后引导他们走向更深层的使用。

## 概述

开发者入门是介于"我刚注册"和"我知道怎么用了"之间的关键窗口。开发者给你的注意力大约只有 10 分钟。每一秒的困惑、每一条没有指引的错误信息、每一次"按理应该能用但就是不行"的时刻，都会让你失去用户。

优秀的入门体验像是和一位早已预判你每个问题的伙伴结对编程。糟糕的入门体验则像是被丢到一座陌生的城市，手里还没有地图。

## 开始之前

先复习 `/devmarketing-skills/skills/developer-audience-context` 技能，了解你的目标开发者。一个做 side project 的爱好者，与一个为生产环境评估工具的企业架构师，所需要的入门体验是不同的。再复习 `/devmarketing-skills/skills/developer-signup-flow`，确保注册流程能顺畅地衔接到入门环节。

## 首次价值时间优化

### 什么是"首次价值"

首次价值不是"成功调用了一次 API"。首次价值是开发者看到你的工具为他做了一件有用的事。

| 工具类型 | 首次价值时刻 |
|-----------|-------------------|
| API | 响应返回有意义的数据 |
| SDK | 库执行了预期的功能 |
| 数据库 | 查询返回了结果 |
| 托管 | 应用上线且可访问 |
| 鉴权 | 用户成功登录 |
| 支付 | 测试扣款成功处理 |

### 衡量首次价值时间（TTFV）

在每个阶段记录时间戳：

```
signup_completed: 2024-01-15T10:00:00Z
dashboard_loaded: 2024-01-15T10:00:05Z
api_key_copied: 2024-01-15T10:01:30Z
first_api_call: 2024-01-15T10:04:45Z
first_successful_response: 2024-01-15T10:04:46Z  # TTFV = 4:46
```

**分类基准：**
- 简单 API：< 5 分钟
- 需要安装的 SDK：< 10 分钟
- 复杂基础设施：< 30 分钟
- 自托管：< 60 分钟

### 清除 TTFV 障碍

梳理每一步并消除卡点：

**常见的 TTFV 杀手：**
1. 访问面板之前先要求邮箱验证
2. API key 藏在账号设置深处
3. 快速入门假设依赖已经装好
4. 第一个示例就需要付费功能
5. 错误信息没有给出解决办法
6. 文档搜索结果全是过时教程

**TTFV 审计流程：**
1. 新建一个账号（全新浏览器，不带任何 cookie）
2. 录屏记录你的前 30 分钟
3. 记下每一个让人困惑或别扭的瞬间
4. 给每个步骤计时
5. 换 5 种不同的开发者人设重复一次

## 快速入门清单设计

### 理想的快速入门结构

```markdown
# 快速入门：5 分钟完成 [具体目标]

你将完成：[最终效果的截图或描述]

前置条件：
- Node.js 18+ (check: node --version)
- npm 或 yarn

## 步骤 1：安装 SDK
[一行命令，带复制按钮]

## 步骤 2：使用你的 API key 初始化
[带占位符的代码，带复制按钮]

## 步骤 3：发起你的第一个请求
[完整可运行的示例，带复制按钮]

## 步骤 4：查看结果
[展示预期输出]

## 下一步
- [常见第二个任务的链接]
- [完整文档的链接]
```

### 真正有效的清单模式

**进度指示器（Stripe 风格）：**
```
你的集成进度：
[x] 创建账号
[x] 获取 API key
[ ] 安装 SDK
[ ] 发起首次 API 调用
[ ] 处理 Webhook
```

**情境化的下一步（Vercel 风格）：**
```
你已经部署了你的第一个站点。

接下来做什么？
[ ] 添加自定义域名
[ ] 配置环境变量
[ ] 启用分析
```

### 快速入门的常见失败

**前置上下文过多：**
```
# 不好的写法：先讲鉴权的历史
在开始之前，我们先来理解一下 OAuth 2.0……
[500 字的背景铺垫]

# 好的写法：直接动手
安装 SDK 并发起你的第一个鉴权请求。
```

**假设环境已就绪：**
```
# 不好的写法
执行 `npm install` 来安装依赖。

# 好的写法
npm install our-sdk
# 或使用 yarn：yarn add our-sdk
# 或使用 pnpm：pnpm add our-sdk
```

**隐藏的前置条件：**
```
# 不好的写法（前置条件藏到第 3 步才出现）
步骤 3：连接 Redis
首先，确保 Redis 正在运行……

# 好的写法（前置条件一开始就列出）
前置条件：
- Redis 6+ 在本地运行 (docker run -p 6379:6379 redis)
```

## 交互式教程 vs 静态教程

### 何时使用交互式教程

**交互式教程适用于：**
- 复杂的安装序列
- 能从即时反馈中获益的概念
- 你能完全掌控环境的入门流程
- 需要 API key 或凭证的功能

**交互式教程工具：**
- 嵌入式代码编辑器（CodeSandbox、StackBlitz）
- 终端模拟器（Instruqt、Killercoda）
- 面板内引导（Appcues、Pendo）
- 交互式 Notebook（Jupyter、Observable）

### 何时静态文档更合适

**静态文档更适合：**
- 参考类文档
- 可复制的代码片段
- 涉及本地开发的步骤
- 内容频繁变动的部分

### 混合方式

**最佳实践：两种都提供**

```
# 发起你的第一个 API 请求

## 快速版（复制即用）
[带复制按钮的代码块]

## 交互版
[在 StackBlitz 中打开] [在 CodeSandbox 中尝试]

## 视频讲解
[5 分钟的嵌入视频]
```

### 交互式教程的 UX 准则

**应该做：**
- 自动保存进度
- 允许跳过
- 显示剩余预估时间
- 提供跳转到静态文档的出口
- 在手机浏览器中至少能正常浏览

**不应该做：**
- 教程强制要求注册账号
- 视频自动播放
- 把内容锁在"完成前置步骤"之后
- 静默地让空闲会话超时
- 指定特定 IDE 或浏览器

## 示例应用与模板

### 模板策略

**分层策略：**

1. **极简示例**（Hello World）
   - 单文件
   - 除了你的 SDK 外零依赖
   - 30 秒跑通
   - 目的：证明 SDK 能用

2. **入门模板**（基础应用）
   - 简单的目录结构
   - 展示常见模式
   - 5 分钟跑通
   - 目的：真实项目的起点

3. **生产级模板**（完整应用）
   - 生产就绪的架构
   - 包含鉴权、错误处理和测试
   - 30 分钟跑通
   - 目的：参考实现

### 模板组织

```
github.com/your-org/
├── examples/
│   ├── minimal/
│   │   ├── node/
│   │   ├── python/
│   │   └── go/
│   ├── starter/
│   │   ├── nextjs/
│   │   ├── express/
│   │   └── fastapi/
│   └── production/
│       ├── saas-starter/
│       └── internal-tool/
```

### 模板维护

跑不通的模板，比没有模板更糟糕。

**模板健康清单：**
- [ ] CI 每周对所有模板跑一次
- [ ] 依赖每月更新
- [ ] SDK 版本固定并随发版更新
- [ ] README 每季度由新贡献者验证
- [ ] 移除前先添加弃用提示

### 真实案例

**优秀模板：Supabase**
- 覆盖多种框架的模板
- 一键部署到 Vercel / Netlify
- 包含鉴权、数据库和存储模式
- 持续维护

**优秀模板：Clerk**
- 框架专属的快速入门
- 配齐鉴权流程
- 渐进式复杂度（极简 → 全功能）

## 优雅地处理入门失败

### 常见失败点

1. **安装失败**
   - 依赖冲突
   - 版本不匹配
   - 平台相关问题

2. **鉴权失败**
   - API key 无效
   - Token 过期
   - 环境错误（测试 vs 生产）

3. **首次请求失败**
   - 网络问题
   - CORS 问题
   - 限流
   - 请求格式不合法

### 错误信息设计

**糟糕的错误信息：**
```
Error: Request failed with status 401
```

**好的错误信息：**
```
鉴权失败：API key 无效

你的 API key 以 'sk_test_' 开头，但你正在调用生产端点。

修复方法：
1. 使用生产环境的 API key（以 'sk_live_' 开头），或者
2. 把端点改为 https://api.example.com/test/

文档：https://docs.example.com/auth#environments
```

### 主动预防失败

**实时检测常见错误：**

```javascript
// 客户端 SDK 捕获常见错误
if (apiKey.startsWith('sk_test_') && endpoint.includes('/v1/')) {
  console.warn(
    'Warning: Using test API key with production endpoint. ' +
    'This will fail. Use production key or test endpoint.'
  );
}
```

### 恢复流程

**面板内的错误恢复：**

```
你的集成出现了问题。

我们检测到：
- 上次 API 调用：2 小时前
- 状态：401 Unauthorized
- 可能原因：API key 已轮换

[重新生成 API key] [查看错误日志] [联系支持]
```

## 衡量激活指标

### 什么是激活

激活 = 开发者获得了足够多的成功、愿意继续使用你的产品。

不同产品有不同的激活定义：

| 产品 | 激活定义 |
|---------|----------------------|
| Stripe | 首次测试扣款成功 |
| Twilio | 首条短信成功发出并送达 |
| Auth0 | 首位用户鉴权成功 |
| Vercel | 首次部署可通过 URL 访问 |
| Algolia | 首次搜索返回结果 |

### 核心激活指标

**激活率**
```
已激活用户 / 注册用户 × 100
```
基准：自服务开发者产品为 20-40%

**激活耗时**
```
从注册到激活事件的中位时间
```
基准：API < 10 分钟，基础设施 < 1 小时

**按群组看激活**
按周或按月跟踪群组，识别改进效果：
```
第 1 周群组：激活率 25%
第 2 周群组：激活率 28%（改进了错误信息）
第 3 周群组：激活率 35%（新增了交互式教程）
```

### 先行指标

跟踪能够预测激活的行为：

| 先行指标 | 与激活的相关性 |
|-------------------|---------------------------|
| 复制了 API key | 激活概率高 2 倍 |
| 浏览了快速入门 | 激活概率高 1.5 倍 |
| 安装了 SDK | 激活概率高 3 倍 |
| 加入 Discord | 激活概率高 2.5 倍 |

### 后置指标

确认激活确实带来了价值：

| 后置指标 | 含义 |
|-------------------|---------|
| 第 7 日留存 | 一周后仍在使用 |
| 第 2 周 API 调用量 | 持续开发中 |
| 升级到付费 | 认为价值足够 |
| 邀请团队成员 | 使用范围在扩大 |

### 激活漏斗示例

```
注册：1,000
├── 访问面板：950 (95%)
├── 浏览快速入门：700 (74%)
├── 复制 API key：500 (71%)
├── 发起首次 API 调用：350 (70%)
├── 收到成功响应：300 (86%)  ← 激活
├── 调用 10+ 次：150 (50%)
└── 第 7 日回访：100 (67%)
```

## 入门邮件序列

### 邮件时机

| 邮件 | 时机 | 目的 |
|-------|--------|---------|
| 欢迎 | 即时 | 确认注册、提供关键链接 |
| 入门引导 | +1 小时 | 推动首次 API 调用（若尚未完成） |
| 技巧 | +1 天 | 分享常见模式 |
| 回访 | +3 天 | 询问是否卡住、主动提供帮助 |
| 激活催促 | +7 天 | 若仍未激活，给出最后推动 |

### 邮件内容原则

**应该做：**
- 包含代码片段（带语法高亮）
- 链接到具体的文档页面
- 允许直接回复求助
- 激活后立即停止序列

**不应该做：**
- 在入门期间发送营销内容
- 需要点击才能看到内容
- 一天之内发送超过一封邮件
- 激活之后还继续发邮件

## 真实开发者工具案例

### 优秀入门：Stripe

- 测试 API key 立即可见
- 面板内有"完成首笔扣款"的交互式引导
- 语言专属的代码示例
- 错误信息附带修复建议
- 进度指示器显示完成度

### 优秀入门：Railway

- 一键部署模板
- 常见框架无需任何配置
- 数秒即可获得预览 URL
- 清晰展示免费额度上限

### 优秀入门：Planetscale

- 交互式数据库浏览器
- 提供从现有数据库导入
- SQL 示例匹配你的 schema
- 用可视化方式讲解 branch 工作流

### 应避免的糟糕入门模式

- 多步骤向导且无法跳过
- "完善资料"卡住代码访问
- 必须搜索才能找到快速入门的文档
- 快速入门假设了太多前置设置
- 错误信息没有任何指引

## 工具

### 入门平台

- **Appcues** - 应用内引导和清单
- **Pendo** - 带入门功能的产品分析
- **Userflow** - 无代码入门流程
- **CommandBar** - 面向开发者的命令面板，自带入门能力

### 交互式文档

- **CodeSandbox / StackBlitz** - 浏览器内的代码环境
- **Killercoda** - 交互式终端场景
- **ReadMe** - 带"在线试用"的 API 文档
- **Mintlify** - 内嵌代码运行器的现代文档

### 邮件与生命周期

- **Customer.io** - 行为触发的邮件
- **Loops** - 面向 SaaS 的邮件
- **Intercom** - 即时通讯 + 邮件入门

### 分析

- **Amplitude** - 入门漏斗分析
- **PostHog** - 开源替代品
- **Heap** - 自动捕获，支持回溯分析

## 相关技能

- `/devmarketing-skills/skills/developer-signup-flow` - 抵达入门起点
- `/devmarketing-skills/skills/developer-audience-context` - 你在为谁做入门
- `/devmarketing-skills/skills/free-tier-strategy` - 他们在不付费的情况下能做什么

## 局限

- 仅当任务与上游来源及本地项目上下文明确匹配时使用本技能。
- 在应用变更前，请验证命令、生成的代码、依赖、凭证以及外部服务行为。
- 不要把示例当作特定环境测试、安全审查或针对破坏性/高成本操作的用户审批的替代品。