# Dev Guide Writer

> 技术教程生成器：将任何技术主题转化为完整教程，包含前置知识、环境搭建、核心步骤、常见报错和进阶拓展，并生成速查表（Cheatsheet）。当用户提到编写教程、操作指南、入门手册、环境搭建步骤，或使用如“tutorial”、“step-by-step”、“getting started”、“how-to guide”、“速查表”、“快速上手”、“帮我写个教程”、“怎么从零开始搭这个环境”等关键词或请求时触发。

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

---


# Tech Tutorial Builder

**一个主题 → 完整技术教程**：通过结构化 SOP 流程，将技术主题转化为包含前置知识、环境搭建、核心步骤、常见报错排查和进阶拓展的完整教程，并附带速查表（Cheatsheet）。

## Quick Start

用户只需提供技术主题或操作目标，Agent 按照以下流程自动生成完整教程：

```
用户：帮我写一个 Docker 入门教程
Agent：[按 SOP 流程输出完整技术教程 + Cheatsheet]
```

## SOP 流程

### Phase 1: 主题定位与受众分析

**目标**：明确教程的技术主题、目标读者和范围边界。

**操作步骤**：

1. **解析主题**：从用户输入中识别核心技术、操作目标和预期产出物
2. **提出澄清问题**（最多 4 个关键问题）：
   - 目标读者的技术水平？（零基础 / 有一定基础 / 有经验的开发者）
   - 读者的操作系统环境？（macOS / Windows / Linux / 不限）
   - 教程完成后读者应该能做什么？（具体可交付的成果）
   - 有没有特定版本或技术栈的约束？
3. **如果用户要求跳过澄清**，则基于以下默认假设继续：
   - 读者：有基本编程经验但不熟悉该技术
   - 环境：同时覆盖 macOS 和 Linux（必要时注明 Windows 差异）
   - 目标：能独立完成一个最小可工作的示例

**输出**：教程元信息摘要（主题、受众、目标、范围，不超过 150 字）

---

### Phase 2: 前置知识梳理（Prerequisites）

**目标**：列出读者在开始本教程前需要掌握的所有知识和工具，确保没有知识断层。

**操作步骤**：

1. **知识依赖分析**：
   - 列出本教程涉及的所有技术概念
   - 逐项判断：该概念是"教程内讲解"还是"读者应已掌握"
   - 判断标准：如果展开讲解会偏离主题超过 200 字，则归为前置知识

2. **前置知识清单**：
   - 按"必须掌握"和"了解即可"两个层次分类
   - 每项附带一句话说明"为什么需要它"
   - 格式：

     ```
     **必须掌握**：
     - [知识点]：[为什么需要它]（推荐学习资源名称）

     **了解即可**：
     - [知识点]：[在教程中会涉及哪些方面]
     ```

3. **自检规则**：
   - 如果前置知识超过 5 项，考虑缩小教程范围或拆分为系列教程
   - 每项前置知识必须有公开可获取的学习资源可供参考

**输出**：分层前置知识清单

---

### Phase 3: 环境搭建（Environment Setup）

**目标**：提供一条可复现的环境配置路径，确保读者在动手核心步骤前环境就绪。

**操作步骤**：

1. **环境清单**：列出所有需要安装/配置的工具及推荐版本
   - 格式：`工具名 版本要求（如 >= x.y）| 用途说明`
   - 明确区分"必须安装"和"可选安装"

2. **安装步骤**：按操作系统分别给出命令
   - 每条命令前用一句话说明"这条命令做了什么"
   - 安装命令只使用官方推荐方式或主流包管理器
   - 格式：

     ```
     **macOS**：
     # 安装 xxx（通过 Homebrew）
     brew install xxx

     **Linux (Ubuntu/Debian)**：
     # 安装 xxx（通过 apt）
     sudo apt update && sudo apt install -y xxx
     ```

3. **环境验证**：每个工具安装后提供验证命令和预期输出
   - 格式：

     ```
     # 验证安装
     xxx --version
     # 预期输出：xxx x.y.z
     ```

4. **自检规则**：
   - 所有安装命令必须来自官方文档或主流包管理器，不使用第三方脚本
   - 不包含任何 API Key、密码、token 等敏感信息的真实值
   - 涉及配置文件时，使用占位符（如 `YOUR_API_KEY`）并说明获取途径

**输出**：分操作系统的安装配置指南 + 验证命令

---

### Phase 4: 核心步骤（Core Steps）

**目标**：以递进式结构带领读者从零完成核心操作，每一步都可独立验证。

**操作步骤**：

1. **步骤规划**：
   - 将整个操作拆分为 5-10 个步骤（每步聚焦一个子目标）
   - 步骤之间严格按依赖关系排序
   - 每步包含：步骤编号、标题、目标说明

2. **步骤编写格式**：

   ```
   #### 步骤 N：[步骤标题]

   **目标**：[这一步完成后达到什么状态]

   **操作**：
   [代码块或操作说明]

   **解释**：
   - [逐行/逐段解释关键部分的含义]

   **验证**：
   [运行什么命令/检查什么结果来确认这一步成功]
   预期输出：[具体的预期结果]
   ```

3. **编写规范**：
   - 代码块必须标注语言类型（如 ```bash、```python）
   - 占位符使用全大写 + 下划线格式（如 `YOUR_PROJECT_NAME`），并在首次出现时说明含义
   - 每个代码块不超过 30 行；超过时拆分并分段解释
   - 文件路径使用相对路径，开头说明项目根目录
   - 每一步结尾必须有验证环节

4. **渐进复杂度**：
   - 前 1-3 步：最小可运行示例（Hello World 级别）
   - 中间步骤：逐步加入真实场景的特性
   - 最后 1-2 步：组合所有内容形成完整示例

**输出**：编号步骤列表，每步含操作 + 解释 + 验证

---

### Phase 5: 常见报错与排查（Troubleshooting）

**目标**：预判读者可能遇到的问题，提供从错误信息到解决方案的直达路径。

**操作步骤**：

1. **报错收集**：基于技术主题，列出 5-8 个最常见的报错场景
   - 来源：环境配置错误、版本不兼容、权限问题、拼写错误、网络问题等

2. **报错条目格式**：

   ```
   **报错 N：[错误信息摘要]**

   完整错误信息：
   [实际错误输出]

   原因：[一句话解释为什么会出现这个错误]

   解决方案：
   [具体的修复命令或操作步骤]

   验证修复：
   [运行什么来确认问题已解决]
   ```

3. **编写规范**：
   - 错误信息必须是真实存在的（不编造错误信息）
   - 解决方案必须对应具体的操作，不使用"请检查配置"等模糊指引
   - 如果一个报错有多种可能原因，按概率从高到低排列
   - 涉及权限问题时，解释为什么需要该权限，而非直接给出 `sudo` 或 `chmod 777`

4. **自检规则**：
   - 解决方案中不包含可能导致安全风险的操作（如 `chmod 777`、禁用防火墙等）
   - 不建议读者关闭安全特性来"解决"问题

**输出**：结构化报错排查表

---

### Phase 6: 进阶拓展（Advanced Topics）

**目标**：为完成基础教程的读者指明进阶方向，提供从入门到深入的学习路径。

**操作步骤**：

1. **进阶主题推荐**（3-5 个方向）：
   - 每个方向用一段话说明：它是什么、为什么值得学、适用于什么场景
   - 标注难度等级：中级 / 高级
   - 格式：

     ```
     **方向 N：[主题名称]** ｜ 难度：[中级/高级]

     [一段话说明]

     推荐资源：
     - [资源名称]（[类型：文档/书籍/课程]）
     ```

2. **实战项目建议**：
   - 提供 2-3 个可以用本教程所学知识独立完成的小项目
   - 每个项目包含：项目名称、一句话描述、涉及的知识点

3. **最佳实践提示**（3-5 条）：
   - 生产环境与教程环境的关键差异
   - 安全注意事项
   - 性能优化方向

**输出**：进阶学习路线图 + 实战项目建议 + 最佳实践

---

### Phase 7: Cheatsheet 速查表

**目标**：提炼教程精华为一页速查表，供读者日常参考。

**操作步骤**：

1. **速查表结构**：

   ```
   # [技术名称] Cheatsheet

   ## 环境信息
   | 项目 | 命令/路径 |
   |------|-----------|
   | 安装 | `命令` |
   | 版本检查 | `命令` |
   | 配置文件位置 | `路径` |

   ## 常用命令
   | 操作 | 命令 | 说明 |
   |------|------|------|
   | xxx  | `xxx` | xxx |

   ## 常用代码片段
   [最多 5 个高频使用的代码片段，每个不超过 10 行]

   ## 快速排错
   | 症状 | 可能原因 | 快速修复 |
   |------|----------|----------|
   | xxx  | xxx      | `xxx`    |
   ```

2. **编写规范**：
   - 速查表总长度控制在可打印的 2 页 A4 纸以内
   - 命令必须是完整可直接复制执行的
   - 不包含解释性文字，只保留"做什么 → 怎么做"的映射
   - 排列顺序按使用频率从高到低

**输出**：一页式 Cheatsheet

---

### Phase 8: 文档组装与输出

**目标**：将前七个阶段的产出组装成完整教程文档。

**教程文档模板**：

```markdown
# [技术主题] 完整教程

> 最后更新：[当前日期] | 适用版本：[版本号]
> 难度：[入门/中级/高级] | 预计耗时：[N 小时/分钟]

## 教程概览

[Phase 1 的教程元信息摘要，说明学完能做什么]

## 1. 前置知识

[Phase 2 的前置知识清单]

## 2. 环境搭建

[Phase 3 的安装配置指南]

## 3. 核心步骤

[Phase 4 的编号步骤列表]

## 4. 常见报错与排查

[Phase 5 的报错排查表]

## 5. 进阶拓展

[Phase 6 的进阶路线图和实战项目]

## 6. Cheatsheet 速查表

[Phase 7 的速查表]

## 附录

- 术语表（如有领域专业术语，用表格列出：术语 | 解释）
- 参考链接（官方文档、社区资源等）
```

**文档输出要求**：
- 所有代码块标注语言类型
- 所有命令可直接复制执行（不包含行号、提示符等干扰字符）
- 所有占位符使用 `YOUR_XXX` 格式并在首次出现时说明
- 配置文件中不包含真实密钥或 token
- 日期使用当前实际日期

---

## 流程控制规则

### 交互模式选择

根据用户输入的详细程度选择模式：

| 用户输入 | 模式 | 行为 |
|----------|------|------|
| 只有技术名称（如"Docker 教程"） | **引导模式** | 执行 Phase 1 提问，等用户回答后继续 |
| 有具体目标（如"用 Docker 部署 Node.js 应用"） | **半自动模式** | 提出 1-2 个关键问题，同时开始规划步骤 |
| 详细描述（含受众、环境、目标） | **全自动模式** | 直接从 Phase 2 开始输出 |
| 用户说"直接写/不用问" | **快速模式** | 基于默认假设直接输出完整教程 |

### 质量检查清单

在输出最终教程前，逐项检查：

- [ ] 前置知识清单完整，无知识断层
- [ ] 环境搭建步骤每条命令都有验证方式
- [ ] 核心步骤每步都包含"操作 + 解释 + 验证"三部分
- [ ] 步骤之间的依赖关系正确（不会出现用到未安装工具的情况）
- [ ] 常见报错不少于 5 个，且解决方案具体可操作
- [ ] 进阶方向至少 3 个，附带资源推荐
- [ ] Cheatsheet 可独立使用，包含常用命令和排错信息
- [ ] 所有代码块标注语言类型
- [ ] 不包含任何硬编码的密钥、token 或个人路径
- [ ] 不包含可能导致安全问题的操作建议（如 `chmod 777`）
- [ ] 不依赖任何付费 API 或需要付费订阅的工具（除非该工具本身是教程主题）

### 迭代优化

如果用户对教程有反馈：
1. 定位反馈涉及的 Phase
2. 从该 Phase 重新执行
3. 向下级联更新所有受影响的内容（如环境变更需同步更新后续步骤和 Cheatsheet）
4. 保持步骤编号的连续性

## 适用场景

本教程生成器适用于以下类型的技术教程：

- **工具使用类**：Git、Docker、Kubernetes、Vim 等工具的使用教程
- **环境搭建类**：开发环境、CI/CD 流水线、服务器配置等
- **编程入门类**：语言入门、框架上手、库的使用等
- **运维操作类**：部署、监控、日志、备份恢复等操作手册
- **数据处理类**：数据库操作、ETL 流程、数据分析工具使用等