Vibe Vibe

主题

A.4 文档生成类模板 ​

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

模板一：代码注释生成 ​

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

markdown
## 注释需求

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

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

注释要求 ​

注释类型：

  • [ ] 文件头注释（说明文件用途）
  • [ ] 函数注释（说明参数、返回值、功能）
  • [ ] 关键逻辑注释（解释复杂逻辑）
  • [ ] 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 };
}

注释要求 ​

注释类型：

  • [x] 文件头注释
  • [x] 函数注释（JSDoc 格式）
  • [x] 关键逻辑注释

注释风格：

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

特别说明：

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

输出要求 ​

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



## 模板二：README 生成

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

```markdown
## 项目信息

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

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

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

## 项目功能

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

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

## 技术细节

**项目结构**：

[粘贴项目目录结构]


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

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

## README 要求

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

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

## 输出要求

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

填写示例 ​

markdown
## 项目信息

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

**技术栈**：
- 前端：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 要求

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

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

## 输出要求

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

模板三：API 文档生成 ​

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

markdown
## 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

包含内容：

  • [x] 接口描述
  • [x] 请求参数说明
  • [x] 请求体示例
  • [x] 响应格式说明
  • [x] 响应示例
  • [x] 错误码说明
  • [x] 调用示例（curl）

输出要求 ​

请生成完整的 API 文档。



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

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

```markdown
## 产品信息

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

## 核心功能

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

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

## 说明要求

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

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

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

## 输出要求

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

模板五：学习笔记整理 ​

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

markdown
## 学习主题

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

## 学习内容

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

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


## 整理要求

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

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

## 输出要求

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

填写示例 ​

markdown
## 学习主题

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

## 学习内容

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

useEffect 副作用

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

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

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

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


## 整理要求

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

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

## 输出要求

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

精简版：快速生成文档 ​

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

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

```[语言]
[代码]

要求：

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


## 文档生成技巧

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

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

### 技巧二：指定目标读者

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

### 技巧三：给出格式示例

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


## 常见填写误区

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


## 本节要点

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