来源：https://github.com/datawhalechina/vibe-vibe

本节提供生成各类文档的 Prompt 模板，包括代码注释、README、API 文档和使用说明。

模板一：代码注释生成

适用于：为现有代码添加注释

## 注释需求

请为以下代码添加中文注释：

```[语言]
[粘贴代码]

注释要求

注释类型：
文件头注释（说明文件用途）
函数注释（说明参数、返回值、功能）
关键逻辑注释（解释复杂逻辑）
TODO 注释（标记待完善的地方）

注释风格：

• 语言：中文
• 格式：[JSDoc 风格 / 普通注释 / 你的规范]
• 详细程度：[简洁/适中/详尽]

特别说明：

• [其他要求，如"不需要给简单的变量加注释"]

输出要求

请输出添加注释后的完整代码，保持原有代码逻辑不变。

### 填写示例

```markdown
## 注释需求

请为以下代码添加中文注释：

```typescript
interface Task {
  id: string;
  title: string;
  completed: boolean;
  createdAt: Date;
}

function useTasks() {
  const [tasks, setTasks] = useState<Task[]>([]);

  const addTask = useCallback((title: string) => {
    const newTask: Task = {
      id: crypto.randomUUID(),
      title,
      completed: false,
      createdAt: new Date(),
    };
    setTasks(prev => [...prev, newTask]);
  }, []);

  const toggleTask = useCallback((id: string) => {
    setTasks(prev => 
      prev.map(task => 
        task.id === id ? { ...task, completed: !task.completed } : task
      )
    );
  }, []);

  return { tasks, addTask, toggleTask };
}

注释要求

注释类型：
文件头注释
函数注释（JSDoc 格式）
关键逻辑注释

注释风格：

• 语言：中文
• 格式：JSDoc 风格
• 详细程度：适中

特别说明：

• interface 的每个字段需要注释
• useCallback 需要解释为什么用它

输出要求

请输出添加注释后的完整代码。

## 模板二：README 生成

适用于：为项目生成说明文档

```markdown
## 项目信息

**项目名称**：[名称]
**一句话描述**：[简述项目做什么]

**技术栈**：
- 前端：[技术]
- 后端：[技术，如无则写"无"]
- 数据库：[技术，如无则写"无"]

**目标用户**：[谁会用这个项目]

## 项目功能

**核心功能**：
1. [功能1]
2. [功能2]
3. [功能3]

**功能截图**（可选）：
[如果有截图，描述截图内容]

## 技术细节

**项目结构**：

[粘贴项目目录结构]

**环境要求**：
- Node.js 版本：[版本]
- 其他依赖：[列出]

**安装步骤**：
[如果你知道安装步骤，可以先写出来]

## README 要求

**包含内容**：
 项目简介
 功能特性
 快速开始（安装和运行）
 项目结构说明
 技术栈说明
 贡献指南
 License

**风格要求**：
- 语言：中文
- 风格：[简洁专业/友好亲切/技术范]

## 输出要求

请生成完整的 README.md 文件内容。

填写示例

## 项目信息

**项目名称**：极简待办
**一句话描述**：一个打开浏览器就能用的极简待办清单

**技术栈**：
- 前端：React + TypeScript + Tailwind CSS
- 后端：无
- 数据库：浏览器 localStorage

**目标用户**：想要简单记录每日待办的个人用户

## 项目功能

**核心功能**：
1. 添加待办任务
2. 标记任务完成
3. 删除任务
4. 数据本地持久化

## 技术细节

**项目结构**：

src/
├── components/
│ ├── AddTask.tsx
│ ├── TaskList.tsx
│ └── TaskItem.tsx
├── hooks/
│ └── useTasks.ts
├── types/
│ └── index.ts
├── App.tsx
└── main.tsx

**环境要求**：
- Node.js 版本：18+
- 包管理器：npm 或 pnpm

## README 要求

**包含内容**：
 项目简介
 功能特性
 快速开始
 项目结构说明
 贡献指南（不需要）
 License（不需要）

**风格要求**：
- 语言：中文
- 风格：简洁专业

## 输出要求

请生成完整的 README.md 文件内容。

模板三：API 文档生成

适用于：为后端接口生成文档

## API 基本信息

**API 名称**：[接口名称]
**请求路径**：[如 /api/users]
**请求方法**：[GET/POST/PUT/DELETE]
**功能描述**：[这个接口做什么]

## 接口代码

```[语言]
[粘贴接口实现代码]

文档要求

文档格式：[Markdown / OpenAPI YAML / 其他]

包含内容：
接口描述
请求参数说明
请求体示例
响应格式说明
响应示例
错误码说明
调用示例（curl/JavaScript）

输出要求

请生成完整的 API 文档。

### 填写示例

```markdown
## API 基本信息

**API 名称**：创建任务
**请求路径**：/api/tasks
**请求方法**：POST
**功能描述**：创建一个新的待办任务

## 接口代码

```typescript
// POST /api/tasks
export async function POST(request: Request) {
  const body = await request.json();
  const { title, priority } = body;

  if (!title || title.trim() === '') {
    return Response.json(
      { error: 'Title is required' },
      { status: 400 }
    );
  }

  const task = {
    id: crypto.randomUUID(),
    title: title.trim(),
    priority: priority || 'medium',
    completed: false,
    createdAt: new Date().toISOString(),
  };

  // 保存到数据库...
  await db.tasks.create(task);

  return Response.json(task, { status: 201 });
}

文档要求

文档格式：Markdown

包含内容：
接口描述
请求参数说明
请求体示例
响应格式说明
响应示例
错误码说明
调用示例（curl）

输出要求

请生成完整的 API 文档。

## 模板四：使用说明生成

适用于：为非技术用户编写使用指南

```markdown
## 产品信息

**产品名称**：[名称]
**产品类型**：[网页/App/桌面软件/脚本]
**目标用户**：[谁会用，技术水平如何]

## 核心功能

请为以下功能编写使用说明：

1. **[功能1]**
   - 功能描述：[做什么]
   - 入口位置：[在哪里找到这个功能]

2. **[功能2]**
   - 功能描述：[做什么]
   - 入口位置：[在哪里找到这个功能]

## 说明要求

**语言风格**：
- 语气：[正式/亲切/简洁]
- 技术术语：[避免使用/简单解释后使用]

**内容结构**：
 功能介绍
 操作步骤（分步骤说明）
 注意事项
 常见问题

**配图说明**（可选）：
[描述需要配什么图，或标注"无需配图"]

## 输出要求

请生成用户友好的使用说明文档。

模板五：学习笔记整理

适用于：整理技术学习内容

## 学习主题

我学习了 [主题]，请帮我整理笔记。

## 学习内容

以下是我学习过程中记录的零散笔记：

[粘贴你的学习笔记、代码片段、关键词等]

## 整理要求

**笔记结构**：
 概念定义
 核心要点（3-5 条）
 代码示例
 使用场景
 常见误区
 相关概念链接

**格式偏好**：
- 使用 Markdown
- 代码块带语法高亮
- 重点用加粗标注

## 输出要求

请输出结构化的学习笔记，方便日后复习。

填写示例

## 学习主题

我学习了 React Hooks 中的 useEffect，请帮我整理笔记。

## 学习内容

以下是我学习过程中记录的零散笔记：

useEffect 副作用

• 获取数据
• 订阅事件
• 修改 DOM

依赖数组
[] 空数组 - 只在挂载时执行一次
不写 - 每次渲染都执行
[dep1, dep2] - 依赖变化时执行

清理函数 return () => {}
组件卸载时调用
避免内存泄漏

常见错误：
无限循环 - 依赖数组没写对
内存泄漏 - 忘记清理订阅

## 整理要求

**笔记结构**：
 概念定义
 核心要点
 代码示例
 使用场景
 常见误区

**格式偏好**：
- 使用 Markdown
- 代码块带语法高亮
- 重点用加粗标注

## 输出要求

请输出结构化的学习笔记。

精简版：快速生成文档

当需求简单时，可以用这个精简版：

请为以下代码生成 [注释/文档/说明]：

```[语言]
[代码]

要求：

• 语言：中文
• 格式：[Markdown/JSDoc/其他]
• [其他要求]

文档生成技巧

技巧一：提供足够的上下文

AI 需要理解代码的用途才能写出好的文档。简单说明这段代码"是做什么的"，能让文档更准确。

技巧二：指定目标读者

给开发者看的文档和给普通用户看的说明，写法完全不同。明确读者是谁。

技巧三：给出格式示例

如果你有特定的文档格式要求，给一个示例比文字描述更有效。

常见填写误区

误区	问题	正确做法
不说明用途	AI 不理解代码做什么	简要说明功能和场景
不指定格式	输出格式随机	明确要 Markdown/JSDoc 等
不指定语言	可能输出英文	明确要求中文
要求过于笼统	"写个文档"	具体说明包含哪些内容

本节要点

• ✅ 代码注释：指定注释类型 + 风格 + 详细程度
• ✅ README：提供项目信息 + 功能列表 + 技术细节
• ✅ API 文档：提供接口代码 + 指定文档格式
• ✅ 使用说明：明确目标用户 + 指定语言风格
• ✅ 关键技巧：提供上下文 + 指定目标读者 + 给出格式示例