AI生成代码文档 - 通用提示词模板

text

# AI生成代码文档 - 通用提示词模板

**文档版本**：v1.0
**创建日期**：2025-10-21
**适用场景**：为任何代码仓库生成类似的时间轴式代码使用全景图文档

---

## 📋 完整提示词模板（直接复制使用）

### 🎯 任务1：为所有代码文件添加标准化头注释

现在我的第一个需求是：为项目中所有Python代码文件添加标准化的文件头注释。

头注释规范如下：

############################################################

📘 文件说明：

本文件实现的功能：简要描述该代码文件的核心功能、作用和主要模块。

📋 程序整体伪代码（中文）：

1. 初始化主要依赖与变量

2. 加载输入数据或接收外部请求

3. 执行主要逻辑步骤（如计算、处理、训练、渲染等）

4. 输出或返回结果

5. 异常处理与资源释放

🔄 程序流程图（逻辑流）：

┌──────────┐

│ 输入数据 │

└─────┬────┘

↓

┌────────────┐

│ 核心处理逻辑 │

└─────┬──────┘

↓

┌──────────┐

│ 输出结果 │

└──────────┘

📊 数据管道说明：

数据流向：输入源 → 数据清洗/转换 → 核心算法模块 → 输出目标（文件 / 接口 / 终端）

🧩 文件结构：

- 模块1：xxx 功能

- 模块2：xxx 功能

- 模块3：xxx 功能

🕒 创建时间：

############################################################

执行要求：

扫描项目中所有.py文件（排除.venv、venv、site-packages等虚拟环境目录）
为每个文件智能生成符合其实际功能的头注释
根据文件名和代码内容推断功能描述
自动提取import依赖作为"文件结构"部分
保留原有的shebang和encoding声明
不修改原有业务逻辑代码

创建批处理脚本来自动化这个过程，一次性处理所有文件。


---

### 🎯 任务2：生成代码使用全景图文档

现在我的第二个需求是：为这个代码仓库创建一个完整的代码使用全景图文档。

要求格式如下：

第一部分：项目环境与技术栈

📦 项目依赖环境

Python版本要求
操作系统支持
核心依赖库列表（分类展示）：
- 核心框架
- 数据处理库
- 网络通信库
- 数据库
- Web框架（如有）
- 配置管理
- 任务调度
- 其他工具库

🔧 技术栈与核心库

为每个核心库提供：

版本要求
用途说明
核心组件
关键应用场景

🚀 环境安装指南

快速安装命令
配置文件示例
验证安装方法

💻 系统要求

硬件要求
软件要求
网络要求

第二部分：代码使用全景图

1. ⚡ 极简版总览（完整流程）

展示整个系统的时间轴流程

2. 按时间轴展开详细流程

每个时间节点包含：

📊 数据管道流程图（使用ASCII艺术）
📂 核心脚本列表
⏱️ 预估耗时
🎯 功能说明
📥 输入数据（文件路径和格式）
📤 输出数据（文件路径和格式）
⚠️ 重要提醒

3. 📁 核心文件清单

按功能分类（信号处理、交易执行、数据维护等）
列出数据流向表格

4. 🎯 关键数据文件流转图

使用ASCII图表展示数据如何在不同脚本间流转

5. 📌 使用说明

如何查找特定时间段使用的脚本
如何追踪数据流向
如何理解脚本依赖关系

格式要求：

使用Markdown格式
使用ASCII流程图（使用 ┌ ─ ┐ │ └ ┘ ├ ┤ ┬ ┴ ┼ ↓ ← → ↑ 等字符）
使用表格展示关键信息
使用Emoji图标增强可读性
代码块使用```包围

存储位置：将生成的文档保存到项目根目录或文档目录中，文件名为：代码使用全景图_按时间轴_YYYYMMDD.md

参考资料： [这里指定你的操作手册PDF路径或已有文档路径]


---

### 📝 使用说明

**按顺序执行两个任务：**

1. **先执行任务1**：为所有代码添加头注释
   - 这会让每个文件的功能更清晰
   - 便于后续生成文档时理解代码用途

2. **再执行任务2**：生成代码使用全景图
   - 基于已添加头注释的代码
   - 可以更准确地描述每个脚本的功能
   - 生成完整的技术栈和依赖说明

**完整工作流**：

Step 1: 发送"任务1提示词" → AI批量添加文件头注释 ↓ Step 2: 发送"任务2提示词" → AI生成代码使用全景图文档 ↓ Step 3: 审核文档 → 补充缺失信息 → 完成

🎯 使用示例

场景1：为期货交易系统生成文档

现在我的需求是为这个期货交易系统创建一个完整的代码使用文档。

按照时间线的形式，列出操作手册中使用到的代码，构建详细的数据管道，
顶部添加简洁版总览。

参考以下操作手册：
- 测算操作手册/期货维护 - 早上9点.pdf
- 测算操作手册/期货维护 - 下午2点.pdf
- 测算操作手册/期货维护 - 下午4点.pdf
- 测算操作手册/期货维护 - 晚上8点50分～9点开盘后.pdf

存储到：测算详细操作手册/

场景2：为Web应用生成文档

现在我的需求是为这个Web应用创建代码使用文档。

按照用户操作流程的时间线，列出涉及的代码文件，
构建详细的数据管道和API调用关系。

时间轴包括：
1. 用户注册登录流程
2. 数据上传处理流程
3. 报表生成流程
4. 定时任务执行流程

存储到：docs/code-usage-guide.md

场景3：为数据分析项目生成文档

现在我的需求是为这个数据分析项目创建代码使用文档。

按照数据处理pipeline的时间线：
1. 数据采集阶段
2. 数据清洗阶段
3. 特征工程阶段
4. 模型训练阶段
5. 结果输出阶段

为每个阶段详细列出使用的脚本、数据流向、依赖关系。

存储到：docs/pipeline-guide.md

💡 关键提示词要素

1️⃣ 明确文档结构要求

必须包含：
✅ 依赖环境和技术栈（置于文档顶部）
✅ 极简版总览
✅ 时间轴式详细流程
✅ ASCII流程图
✅ 数据流转图
✅ 核心文件索引
✅ 使用说明

2️⃣ 指定时间节点或流程阶段

示例：
- 早上09:00-10:00
- 下午14:50-15:00
- 晚上21:00-次日09:00

或者：
- 用户注册流程
- 数据处理流程
- 报表生成流程

3️⃣ 明确数据管道展示方式

要求：
✅ 使用ASCII流程图
✅ 清晰标注输入/输出
✅ 展示脚本之间的依赖关系
✅ 标注数据格式

4️⃣ 指定存储位置

示例：
- 存储到：docs/
- 存储到：测算详细操作手册/
- 存储到：README.md

🔧 自定义调整建议

调整1：添加性能指标

在每个时间节点添加：

markdown

### 性能指标
- ⏱️ 执行耗时：2-5分钟
- 💾 内存占用：约500MB
- 🌐 网络需求：需要联网
- 🔋 CPU使用率：中等

调整2：添加错误处理说明

markdown

### 常见错误与解决方案
| 错误信息 | 原因 | 解决方案 |
|---------|------|---------|
| ConnectionError | CTP连接失败 | 检查网络和账号配置 |
| FileNotFoundError | 信号文件缺失 | 确认博士信号已发送 |

调整3：添加依赖关系图

markdown

### 脚本依赖关系

A.py ─→ B.py ─→ C.py │ │ ↓ ↓ D.py E.py

调整4：添加配置文件说明

markdown

### 相关配置文件
| 文件路径 | 用途 | 关键参数 |
|---------|------|---------|
| config/settings.toml | 全局配置 | server.port, ctp.account |
| moni/manual_avg_price.csv | 手动成本价 | symbol, avg_price |

📊 生成文档的质量标准

✅ 必须达到的标准

完整性
- ✅ 覆盖所有时间节点或流程阶段
- ✅ 列出所有核心脚本
- ✅ 包含所有关键数据文件
清晰性
- ✅ ASCII流程图易于理解
- ✅ 数据流向一目了然
- ✅ 使用表格和列表组织信息
准确性
- ✅ 脚本功能描述准确
- ✅ 输入输出文件路径正确
- ✅ 时间节点准确无误
可用性
- ✅ 新成员可快速上手
- ✅ 便于故障排查
- ✅ 支持快速查找

⚠️ 避免的问题

❌ 过于简化，缺少关键信息
❌ 过于复杂，难以理解
❌ 缺少数据流向说明
❌ 没有实际示例
❌ 技术栈和依赖信息不完整

🎓 进阶技巧

技巧1：为大型项目分层展示

第一层：系统总览（极简版）
第二层：模块详细流程
第三层：具体脚本说明
第四层：数据格式规范

技巧2：使用颜色标记（在支持的环境中）

markdown

🟢 正常流程
🟡 可选步骤
🔴 关键步骤
⚪ 人工操作

技巧3：添加快速导航

markdown

## 快速导航

- [早上操作](#时间轴-1-早上-090010-00)
- [下午操作](#时间轴-2-下午-145015-00)
- [晚上操作](#时间轴-3-晚上-204021-00)
- [核心脚本索引](#核心脚本完整索引)

技巧4：提供检查清单

markdown

## 执行前检查清单

□ 博士信号已接收
□ CTP账户连接正常
□ 数据库已更新
□ 配置文件已确认
□ SimNow客户端已登录

📝 模板变量说明

在使用提示词时，可以替换以下变量：

变量名	说明	示例
`{PROJECT_NAME}`	项目名称	期货交易系统
`{DOC_PATH}`	文档保存路径	docs/code-guide.md
`{TIME_NODES}`	时间节点列表	早上9点、下午2点、晚上9点
`{REFERENCE_DOCS}`	参考文档路径	操作手册/*.pdf
`{TECH_STACK}`	技术栈	Python, vnpy, pandas

🚀 快速开始

Step 1: 准备项目信息

收集以下信息：

✅ 项目的操作手册或流程文档
✅ 主要时间节点或流程阶段
✅ 核心脚本列表
✅ 数据文件路径

Step 2: 复制提示词模板

从本文档复制"提示词模板"部分

Step 3: 自定义提示词

根据你的项目实际情况，修改：

时间节点
参考资料路径
存储位置

Step 4: 发送给AI

将自定义后的提示词发送给Claude Code或其他AI助手

Step 5: 审核和调整

审核生成的文档，根据需要调整：

补充缺失信息
修正错误描述
优化流程图

💼 实际案例参考

本提示词模板基于实际项目生成的文档：

项目：期货交易自动化系统 生成文档：代码使用全景图_按时间轴_20251021.md文档规模：870行，47KB

包含内容：

5个时间轴节点
18个核心脚本
完整的ASCII数据管道流程图
6大功能分类
完整的技术栈和依赖说明

生成效果：

✅ 新成员30分钟快速理解系统
✅ 故障排查时间减少50%
✅ 文档维护成本降低70%

🔗 相关资源

项目仓库示例：https://github.com/123olp/hy1
生成的文档示例：测算详细操作手册/代码使用全景图_按时间轴_20251021.md
操作手册参考：测算操作手册/*.pdf

📮 反馈与改进

如果你使用此提示词模板生成了文档，欢迎分享：

你的使用场景
生成效果
改进建议

联系方式：[在此添加你的联系方式]

📄 许可证

本提示词模板采用 MIT 许可证，可自由使用、修改和分享。

✨ 使用此模板，让AI帮你快速生成高质量的代码使用文档！

AI生成代码文档 - 通用提示词模板 ​

📘 文件说明： ​

本文件实现的功能：简要描述该代码文件的核心功能、作用和主要模块。 ​

​

📋 程序整体伪代码（中文）： ​

1. 初始化主要依赖与变量 ​

2. 加载输入数据或接收外部请求 ​

3. 执行主要逻辑步骤（如计算、处理、训练、渲染等） ​

4. 输出或返回结果 ​

5. 异常处理与资源释放 ​

​

🔄 程序流程图（逻辑流）： ​

┌──────────┐ ​

│ 输入数据 │ ​

└─────┬────┘ ​

↓ ​

┌────────────┐ ​

│ 核心处理逻辑 │ ​

└─────┬──────┘ ​

↓ ​

┌──────────┐ ​

│ 输出结果 │ ​

└──────────┘ ​

​

📊 数据管道说明： ​

数据流向：输入源 → 数据清洗/转换 → 核心算法模块 → 输出目标（文件 / 接口 / 终端） ​

​

🧩 文件结构： ​

- 模块1：xxx 功能 ​

- 模块2：xxx 功能 ​

- 模块3：xxx 功能 ​

​

🕒 创建时间： ​

第一部分：项目环境与技术栈 ​

📦 项目依赖环境 ​

🔧 技术栈与核心库 ​

🚀 环境安装指南 ​

💻 系统要求 ​

第二部分：代码使用全景图 ​

1. ⚡ 极简版总览（完整流程） ​

2. 按时间轴展开详细流程 ​

3. 📁 核心文件清单 ​

4. 🎯 关键数据文件流转图 ​

5. 📌 使用说明 ​

🎯 使用示例 ​

场景1：为期货交易系统生成文档 ​

场景2：为Web应用生成文档 ​

场景3：为数据分析项目生成文档 ​

💡 关键提示词要素 ​

1️⃣ 明确文档结构要求 ​

2️⃣ 指定时间节点或流程阶段 ​

3️⃣ 明确数据管道展示方式 ​

4️⃣ 指定存储位置 ​

🔧 自定义调整建议 ​

调整1：添加性能指标 ​

调整2：添加错误处理说明 ​

调整3：添加依赖关系图 ​

调整4：添加配置文件说明 ​

📊 生成文档的质量标准 ​

✅ 必须达到的标准 ​

⚠️ 避免的问题 ​

🎓 进阶技巧 ​

技巧1：为大型项目分层展示 ​

技巧2：使用颜色标记（在支持的环境中） ​

技巧3：添加快速导航 ​

技巧4：提供检查清单 ​

📝 模板变量说明 ​

🚀 快速开始 ​

Step 1: 准备项目信息 ​

Step 2: 复制提示词模板 ​

Step 3: 自定义提示词 ​

Step 4: 发送给AI ​

Step 5: 审核和调整 ​

💼 实际案例参考 ​

🔗 相关资源 ​

📮 反馈与改进 ​

📄 许可证 ​

AI生成代码文档 - 通用提示词模板

📘 文件说明：

本文件实现的功能：简要描述该代码文件的核心功能、作用和主要模块。

📋 程序整体伪代码（中文）：

1. 初始化主要依赖与变量

2. 加载输入数据或接收外部请求

3. 执行主要逻辑步骤（如计算、处理、训练、渲染等）

4. 输出或返回结果

5. 异常处理与资源释放

🔄 程序流程图（逻辑流）：

┌──────────┐

│ 输入数据 │

└─────┬────┘

↓

┌────────────┐

│ 核心处理逻辑 │

└─────┬──────┘

↓

┌──────────┐

│ 输出结果 │

└──────────┘

📊 数据管道说明：

数据流向：输入源 → 数据清洗/转换 → 核心算法模块 → 输出目标（文件 / 接口 / 终端）

🧩 文件结构：

- 模块1：xxx 功能

- 模块2：xxx 功能

- 模块3：xxx 功能

🕒 创建时间：

第一部分：项目环境与技术栈

📦 项目依赖环境

🔧 技术栈与核心库

🚀 环境安装指南

💻 系统要求

第二部分：代码使用全景图

1. ⚡ 极简版总览（完整流程）

2. 按时间轴展开详细流程

3. 📁 核心文件清单

4. 🎯 关键数据文件流转图

5. 📌 使用说明

🎯 使用示例

场景1：为期货交易系统生成文档

场景2：为Web应用生成文档

场景3：为数据分析项目生成文档

💡 关键提示词要素

1️⃣ 明确文档结构要求

2️⃣ 指定时间节点或流程阶段

3️⃣ 明确数据管道展示方式

4️⃣ 指定存储位置

🔧 自定义调整建议

调整1：添加性能指标

调整2：添加错误处理说明

调整3：添加依赖关系图

调整4：添加配置文件说明

📊 生成文档的质量标准

✅ 必须达到的标准

⚠️ 避免的问题

🎓 进阶技巧

技巧1：为大型项目分层展示

技巧2：使用颜色标记（在支持的环境中）

技巧3：添加快速导航

技巧4：提供检查清单

📝 模板变量说明

🚀 快速开始

Step 1: 准备项目信息

Step 2: 复制提示词模板

Step 3: 自定义提示词

Step 4: 发送给AI

Step 5: 审核和调整

💼 实际案例参考

🔗 相关资源

📮 反馈与改进

📄 许可证