# 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. **先执行任务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 |
```

---

## 📊 生成文档的质量标准

### ✅ 必须达到的标准

1. **完整性**
   - ✅ 覆盖所有时间节点或流程阶段
   - ✅ 列出所有核心脚本
   - ✅ 包含所有关键数据文件

2. **清晰性**
   - ✅ ASCII流程图易于理解
   - ✅ 数据流向一目了然
   - ✅ 使用表格和列表组织信息

3. **准确性**
   - ✅ 脚本功能描述准确
   - ✅ 输入输出文件路径正确
   - ✅ 时间节点准确无误

4. **可用性**
   - ✅ 新成员可快速上手
   - ✅ 便于故障排查
   - ✅ 支持快速查找

### ⚠️ 避免的问题

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

---

## 🎓 进阶技巧

### 技巧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帮你快速生成高质量的代码使用文档！**