(7,1)_#_AI生成代码文档_-_通用提示词模板.md 12 KB
AI生成代码文档 - 通用提示词模板
文档版本：v1.0 创建日期：2025-10-21 适用场景：为任何代码仓库生成类似的时间轴式代码使用全景图文档
📋 完整提示词模板（直接复制使用）
🎯 任务1：为所有代码文件添加标准化头注释
现在我的第一个需求是：为项目中所有Python代码文件添加标准化的文件头注释。
头注释规范如下：
############################################################
# 📘 文件说明：
# 本文件实现的功能：简要描述该代码文件的核心功能、作用和主要模块。
#
# 📋 程序整体伪代码（中文）：
# 1. 初始化主要依赖与变量
# 2. 加载输入数据或接收外部请求
# 3. 执行主要逻辑步骤（如计算、处理、训练、渲染等）
# 4. 输出或返回结果
# 5. 异常处理与资源释放
#
# 🔄 程序流程图（逻辑流）：
# ┌──────────┐
# │ 输入数据 │
# └─────┬────┘
# ↓
# ┌────────────┐
# │ 核心处理逻辑 │
# └─────┬──────┘
# ↓
# ┌──────────┐
# │ 输出结果 │
# └──────────┘
#
# 📊 数据管道说明：
# 数据流向：输入源 → 数据清洗/转换 → 核心算法模块 → 输出目标（文件 / 接口 / 终端）
#
# 🧩 文件结构：
# - 模块1：xxx 功能
# - 模块2：xxx 功能
# - 模块3：xxx 功能
#
# 🕒 创建时间：{自动生成当前日期}
############################################################
执行要求：
1. 扫描项目中所有.py文件（排除.venv、venv、site-packages等虚拟环境目录）
2. 为每个文件智能生成符合其实际功能的头注释
3. 根据文件名和代码内容推断功能描述
4. 自动提取import依赖作为"文件结构"部分
5. 保留原有的shebang和encoding声明
6. 不修改原有业务逻辑代码
创建批处理脚本来自动化这个过程，一次性处理所有文件。
🎯 任务2：生成代码使用全景图文档
现在我的第二个需求是：为这个代码仓库创建一个完整的代码使用全景图文档。
要求格式如下：
## 第一部分：项目环境与技术栈
### 📦 项目依赖环境
- Python版本要求
- 操作系统支持
- 核心依赖库列表（分类展示）：
- 核心框架
- 数据处理库
- 网络通信库
- 数据库
- Web框架（如有）
- 配置管理
- 任务调度
- 其他工具库
### 🔧 技术栈与核心库
为每个核心库提供：
- 版本要求
- 用途说明
- 核心组件
- 关键应用场景
### 🚀 环境安装指南
- 快速安装命令
- 配置文件示例
- 验证安装方法
### 💻 系统要求
- 硬件要求
- 软件要求
- 网络要求
---
## 第二部分：代码使用全景图
### 1. ⚡ 极简版总览（完整流程）
展示整个系统的时间轴流程
### 2. 按时间轴展开详细流程
每个时间节点包含：
- 📊 数据管道流程图（使用ASCII艺术）
- 📂 核心脚本列表
- ⏱️ 预估耗时
- 🎯 功能说明
- 📥 输入数据（文件路径和格式）
- 📤 输出数据（文件路径和格式）
- ⚠️ 重要提醒
### 3. 📁 核心文件清单
- 按功能分类（信号处理、交易执行、数据维护等）
- 列出数据流向表格
### 4. 🎯 关键数据文件流转图
使用ASCII图表展示数据如何在不同脚本间流转
### 5. 📌 使用说明
- 如何查找特定时间段使用的脚本
- 如何追踪数据流向
- 如何理解脚本依赖关系
---
格式要求：
- 使用Markdown格式
- 使用ASCII流程图（使用 ┌ ─ ┐ │ └ ┘ ├ ┤ ┬ ┴ ┼ ↓ ← → ↑ 等字符）
- 使用表格展示关键信息
- 使用Emoji图标增强可读性
- 代码块使用```包围
存储位置：
将生成的文档保存到项目根目录或文档目录中，文件名为：
代码使用全景图_按时间轴_YYYYMMDD.md
参考资料：
[这里指定你的操作手册PDF路径或已有文档路径]
📝 使用说明
按顺序执行两个任务：
先执行任务1：为所有代码添加头注释
- 这会让每个文件的功能更清晰
- 便于后续生成文档时理解代码用途
再执行任务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调用关系。
时间轴包括：
- 用户注册登录流程
- 数据上传处理流程
- 报表生成流程
- 定时任务执行流程
存储到：docs/code-usage-guide.md
### 场景3：为数据分析项目生成文档
现在我的需求是为这个数据分析项目创建代码使用文档。
按照数据处理pipeline的时间线：
- 数据采集阶段
- 数据清洗阶段
- 特征工程阶段
- 模型训练阶段
- 结果输出阶段
为每个阶段详细列出使用的脚本、数据流向、依赖关系。
存储到：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 |
---
## 📊 生成文档的质量标准
### ✅ 必须达到的标准
1. **完整性**
- ✅ 覆盖所有时间节点或流程阶段
- ✅ 列出所有核心脚本
- ✅ 包含所有关键数据文件
2. **清晰性**
- ✅ ASCII流程图易于理解
- ✅ 数据流向一目了然
- ✅ 使用表格和列表组织信息
3. **准确性**
- ✅ 脚本功能描述准确
- ✅ 输入输出文件路径正确
- ✅ 时间节点准确无误
4. **可用性**
- ✅ 新成员可快速上手
- ✅ 便于故障排查
- ✅ 支持快速查找
### ⚠️ 避免的问题
1. ❌ 过于简化，缺少关键信息
2. ❌ 过于复杂，难以理解
3. ❌ 缺少数据流向说明
4. ❌ 没有实际示例
5. ❌ 技术栈和依赖信息不完整
---
## 🎓 进阶技巧
### 技巧1：为大型项目分层展示
第一层：系统总览（极简版） 第二层：模块详细流程 第三层：具体脚本说明 第四层：数据格式规范
### 技巧2：使用颜色标记（在支持的环境中）
markdown 🟢 正常流程 🟡 可选步骤 🔴 关键步骤 ⚪ 人工操作
### 技巧3：添加快速导航
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帮你快速生成高质量的代码使用文档！