505 lines
13 KiB
Markdown
505 lines
13 KiB
Markdown
# AI-Generated Code Document - General Prompt Template
|
||
|
||
**Document Version**: v1.0
|
||
**Creation Date**: 2025-10-21
|
||
**Applicable Scenarios**: Generate a panoramic document of code usage, similar to a timeline, for any code repository.
|
||
|
||
---
|
||
|
||
## 📋 Complete Prompt Template (Copy and Use Directly)
|
||
|
||
### 🎯 Task 1: Add Standardized Header Comments to All Code Files
|
||
|
||
```
|
||
My first requirement now is to add standardized header comments to all Python code files in the project.
|
||
|
||
The header comment specification is as follows:
|
||
|
||
############################################################
|
||
# 📘 File Description:
|
||
# The function implemented by this file: Briefly describe the core function, purpose, and main modules of this code file.
|
||
#
|
||
# 📋 Overall Program Pseudocode (Chinese):
|
||
# 1. Initialize main dependencies and variables.
|
||
# 2. Load input data or receive external requests.
|
||
# 3. Execute main logic steps (e.g., calculation, processing, training, rendering).
|
||
# 4. Output or return results.
|
||
# 5. Exception handling and resource release.
|
||
#
|
||
# 🔄 Program Flowchart (Logical Flow):
|
||
# ┌──────────┐
|
||
# │ Input Data │
|
||
# └─────┬────┘
|
||
# ↓
|
||
# ┌────────────┐
|
||
# │ Core Processing Logic │
|
||
# └─────┬──────┘
|
||
# ↓
|
||
# ┌──────────┐
|
||
# │ Output Results │
|
||
# └──────────┘
|
||
#
|
||
# 📊 Data Pipeline Description:
|
||
# Data flow: Input source → Data cleaning/transformation → Core algorithm module → Output target (file / interface / terminal)
|
||
#
|
||
# 🧩 File Structure:
|
||
# - Module 1: xxx Function
|
||
# - Module 2: xxx Function
|
||
# - Module 3: xxx Function
|
||
#
|
||
# 🕒 Creation Time: {Automatically generate current date}
|
||
############################################################
|
||
|
||
Execution requirements:
|
||
1. Scan all .py files in the project (excluding virtual environment directories such as .venv, venv, site-packages).
|
||
2. Intelligently generate header comments for each file that match its actual function.
|
||
3. Infer functional descriptions based on filenames and code content.
|
||
4. Automatically extract import dependencies as the "File Structure" section.
|
||
5. Retain existing shebang and encoding declarations.
|
||
6. Do not modify existing business logic code.
|
||
|
||
Create a batch script to automate this process and process all files at once.
|
||
```
|
||
|
||
---
|
||
|
||
### 🎯 Task 2: Generate a Panoramic Code Usage Document
|
||
|
||
```
|
||
My second requirement now is to create a complete panoramic code usage document for this code repository.
|
||
|
||
The required format is as follows:
|
||
|
||
## Part One: Project Environment and Technology Stack
|
||
|
||
### 📦 Project Dependency Environment
|
||
- Python version requirements
|
||
- Operating system support
|
||
- List of core dependency libraries (categorized display):
|
||
- Core framework
|
||
- Data processing library
|
||
- Network communication library
|
||
- Database
|
||
- Web framework (if any)
|
||
- Configuration management
|
||
- Task scheduling
|
||
- Other utility libraries
|
||
|
||
### 🔧 Technology Stack and Core Libraries
|
||
Provide for each core library:
|
||
- Version requirements
|
||
- Purpose description
|
||
- Core components
|
||
- Key application scenarios
|
||
|
||
### 🚀 Environment Installation Guide
|
||
- Quick installation commands
|
||
- Configuration file examples
|
||
- Installation verification methods
|
||
|
||
### 💻 System Requirements
|
||
- Hardware requirements
|
||
- Software requirements
|
||
- Network requirements
|
||
|
||
---
|
||
|
||
## Part Two: Panoramic Code Usage
|
||
|
||
### 1. ⚡ Minimalist Overview (Complete Process)
|
||
Display the timeline process of the entire system.
|
||
|
||
### 2. Detailed Process Expanded by Timeline
|
||
Each time node includes:
|
||
- 📊 Data pipeline flowchart (using ASCII art)
|
||
- 📂 List of core scripts
|
||
- ⏱️ Estimated time consumption
|
||
- 🎯 Function description
|
||
- 📥 Input data (file path and format)
|
||
- 📤 Output data (file path and format)
|
||
- ⚠️ Important reminders
|
||
|
||
### 3. 📁 Core File List
|
||
- Categorized by function (signal processing, transaction execution, data maintenance, etc.)
|
||
- List of data flow tables
|
||
|
||
### 4. 🎯 Key Data File Flow Diagram
|
||
Use ASCII diagrams to show how data flows between different scripts.
|
||
|
||
### 5. 📌 Usage Instructions
|
||
- How to find scripts used in specific time periods
|
||
- How to track data flow
|
||
- How to understand script dependencies
|
||
|
||
---
|
||
|
||
Format requirements:
|
||
- Use Markdown format.
|
||
- Use ASCII flowcharts (using ┌ ─ ┐ │ └ ┘ ├ ┤ ┬ ┴ ┼ ↓ ← → ↑ and other characters).
|
||
- Use tables to display key information.
|
||
- Use Emoji icons to enhance readability.
|
||
- Code blocks are enclosed by ```.
|
||
|
||
Storage location:
|
||
Save the generated document to the project root directory or document directory, with the filename:
|
||
Code Usage Panorama_by Timeline_YYYYMMDD.md
|
||
|
||
References:
|
||
[Specify your operation manual PDF path or existing document path here]
|
||
```
|
||
|
||
---
|
||
|
||
### 📝 Usage Instructions
|
||
|
||
**Execute two tasks in order:**
|
||
|
||
1. **First execute Task 1**: Add header comments to all code.
|
||
- This will make the function of each file clearer.
|
||
- Convenient for understanding code purpose when generating documents later.
|
||
|
||
2. **Then execute Task 2**: Generate a panoramic code usage document.
|
||
- Based on the code with added header comments.
|
||
- Can more accurately describe the function of each script.
|
||
- Generate complete tech stack and dependency descriptions.
|
||
|
||
**Complete workflow**:
|
||
```
|
||
Step 1: Send "Task 1 Prompt" → AI batch adds file header comments
|
||
↓
|
||
Step 2: Send "Task 2 Prompt" → AI generates code usage panorama document
|
||
↓
|
||
Step 3: Review document → Supplement missing information → Complete
|
||
```
|
||
```
|
||
|
||
---
|
||
|
||
## 🎯 Usage Examples
|
||
|
||
### Scenario 1: Generate Documentation for a Futures Trading System
|
||
|
||
```
|
||
My current requirement is to create a complete code usage document for this futures trading system.
|
||
|
||
In the form of a timeline, list the code used in the operation manual, build a detailed data pipeline,
|
||
and add a concise overview at the top.
|
||
|
||
Refer to the following operation manuals:
|
||
- Measurement Operation Manual/Futures Maintenance - 9 AM.pdf
|
||
- Measurement Operation Manual/Futures Maintenance - 2 PM.pdf
|
||
- Measurement Operation Manual/Futures Maintenance - 4 PM.pdf
|
||
- Measurement Operation Manual/Futures Maintenance - 8:50 PM to after 9 PM opening.pdf
|
||
|
||
Save to: Measurement Detailed Operation Manual/
|
||
```
|
||
|
||
### Scenario 2: Generate Documentation for a Web Application
|
||
|
||
```
|
||
My current requirement is to create a code usage document for this web application.
|
||
|
||
Following the timeline of user operations, list the involved code files,
|
||
build a detailed data pipeline and API call relationships.
|
||
|
||
The timeline includes:
|
||
1. User registration and login process
|
||
2. Data upload and processing process
|
||
3. Report generation process
|
||
4. Scheduled task execution process
|
||
|
||
Save to: docs/code-usage-guide.md
|
||
```
|
||
|
||
### Scenario 3: Generate Documentation for a Data Analysis Project
|
||
|
||
```
|
||
My current requirement is to create a code usage document for this data analysis project.
|
||
|
||
Following the timeline of the data processing pipeline:
|
||
1. Data collection stage
|
||
2. Data cleaning stage
|
||
3. Feature engineering stage
|
||
4. Model training stage
|
||
5. Result output stage
|
||
|
||
For each stage, list the scripts used, data flow, and dependencies in detail.
|
||
|
||
Save to: docs/pipeline-guide.md
|
||
```
|
||
|
||
---
|
||
|
||
## 💡 Key Prompt Elements
|
||
|
||
### 1️⃣ Clear Document Structure Requirements
|
||
|
||
```
|
||
Must include:
|
||
✅ Dependency environment and tech stack (placed at the top of the document)
|
||
✅ Minimalist overview
|
||
✅ Timeline-style detailed process
|
||
✅ ASCII flowchart
|
||
✅ Data flow diagram
|
||
✅ Core file index
|
||
✅ Usage instructions
|
||
```
|
||
|
||
### 2️⃣ Specify Time Nodes or Process Stages
|
||
|
||
```
|
||
Example:
|
||
- 09:00-10:00 AM
|
||
- 14:50-15:00 PM
|
||
- 21:00 PM - 09:00 AM the next day
|
||
|
||
Or:
|
||
- User registration process
|
||
- Data processing process
|
||
- Report generation process
|
||
```
|
||
|
||
### 3️⃣ Clearly Define Data Pipeline Display Method
|
||
|
||
```
|
||
Requirements:
|
||
✅ Use ASCII flowcharts
|
||
✅ Clearly label input/output
|
||
✅ Show dependencies between scripts
|
||
✅ Label data format
|
||
```
|
||
|
||
### 4️⃣ Specify Storage Location
|
||
|
||
```
|
||
Example:
|
||
- Save to: docs/
|
||
- Save to: Measurement Detailed Operation Manual/
|
||
- Save to: README.md
|
||
```
|
||
|
||
---
|
||
|
||
## 🔧 Customization Suggestions
|
||
|
||
### Adjustment 1: Add Performance Metrics
|
||
|
||
Add to each time node:
|
||
```markdown
|
||
### Performance Metrics
|
||
- ⏱️ Execution time: 2-5 minutes
|
||
- 💾 Memory usage: approx. 500MB
|
||
- 🌐 Network requirements: Internet connection needed
|
||
- 🔋 CPU utilization: Medium
|
||
```
|
||
|
||
### Adjustment 2: Add Error Handling Description
|
||
|
||
```markdown
|
||
### Common Errors and Solutions
|
||
| Error Message | Cause | Solution |
|
||
|---|---|---|
|
||
| ConnectionError | CTP connection failed | Check network and account configuration |
|
||
| FileNotFoundError | Signal file missing | Confirm Doctor Signal has been sent |
|
||
```
|
||
|
||
### Adjustment 3: Add Dependency Graph
|
||
|
||
```markdown
|
||
### Script Dependencies
|
||
```
|
||
A.py ─→ B.py ─→ C.py
|
||
│ │
|
||
↓ ↓
|
||
D.py E.py
|
||
```
|
||
```
|
||
|
||
### Adjustment 4: Add Configuration File Description
|
||
|
||
```markdown
|
||
### Related Configuration Files
|
||
| File Path | Purpose | Key Parameters |
|
||
|---|---|---|
|
||
| config/settings.toml | Global configuration | server.port, ctp.account |
|
||
| moni/manual_avg_price.csv | Manual cost price | symbol, avg_price |
|
||
```
|
||
|
||
---
|
||
|
||
## 📊 Quality Standards for Generated Documents
|
||
|
||
### ✅ Must Meet Standards
|
||
|
||
1. **Completeness**
|
||
- ✅ Covers all time nodes or process stages.
|
||
- ✅ Lists all core scripts.
|
||
- ✅ Includes all key data files.
|
||
|
||
2. **Clarity**
|
||
- ✅ ASCII flowcharts are easy to understand.
|
||
- ✅ Data flow is clear at a glance.
|
||
- ✅ Information is organized using tables and lists.
|
||
|
||
3. **Accuracy**
|
||
- ✅ Script function descriptions are accurate.
|
||
- ✅ Input and output file paths are correct.
|
||
- ✅ Time nodes are accurate.
|
||
|
||
4. **Usability**
|
||
- ✅ New members can quickly get started.
|
||
- ✅ Facilitates troubleshooting.
|
||
- ✅ Supports quick lookup.
|
||
|
||
### ⚠️ Problems to Avoid
|
||
|
||
1. ❌ Over-simplification, missing key information.
|
||
2. ❌ Over-complexity, difficult to understand.
|
||
3. ❌ Lack of data flow description.
|
||
4. ❌ No practical examples.
|
||
5. ❌ Incomplete tech stack and dependency information.
|
||
|
||
---
|
||
|
||
## 🎓 Advanced Tips
|
||
|
||
### Tip 1: Layered Display for Large Projects
|
||
|
||
```
|
||
Layer 1: System Overview (minimalist version)
|
||
Layer 2: Module detailed process
|
||
Layer 3: Specific script description
|
||
Layer 4: Data format specification
|
||
```
|
||
|
||
### Tip 2: Use Color Marking (in supported environments)
|
||
|
||
```markdown
|
||
🟢 Normal flow
|
||
🟡 Optional step
|
||
🔴 Key step
|
||
⚪ Manual operation
|
||
```
|
||
|
||
### Tip 3: Add Quick Navigation
|
||
|
||
```markdown
|
||
## Quick Navigation
|
||
|
||
- [Morning Operations](#timeline-1-morning-090010-00)
|
||
- [Afternoon Operations](#timeline-2-afternoon-145015-00)
|
||
- [Evening Operations](#timeline-3-evening-204021-00)
|
||
- [Full Index of Core Scripts](#full-index-of-core-scripts)
|
||
```
|
||
|
||
### Tip 4: Provide Checklist
|
||
|
||
```markdown
|
||
## Pre-execution Checklist
|
||
|
||
□ Doctor Signal received
|
||
□ CTP account connected normally
|
||
□ Database updated
|
||
□ Configuration file confirmed
|
||
□ SimNow client logged in
|
||
```
|
||
|
||
---
|
||
|
||
## 📝 Template Variable Description
|
||
|
||
When using the prompt, the following variables can be replaced:
|
||
|
||
| Variable Name | Description | Example |
|
||
|---|---|---|
|
||
| `{PROJECT_NAME}` | Project name | Futures Trading System |
|
||
| `{DOC_PATH}` | Document save path | docs/code-guide.md |
|
||
| `{TIME_NODES}` | List of time nodes | 9 AM, 2 PM, 9 PM |
|
||
| `{REFERENCE_DOCS}` | Reference document path | Operation Manual/*.pdf |
|
||
| `{TECH_STACK}` | Tech stack | Python, vnpy, pandas |
|
||
|
||
---
|
||
|
||
## 🚀 Quick Start
|
||
|
||
### Step 1: Prepare Project Information
|
||
|
||
Collect the following information:
|
||
- ✅ Project operation manual or process document
|
||
- ✅ Main time nodes or process stages
|
||
- ✅ List of core scripts
|
||
- ✅ Data file paths
|
||
|
||
### Step 2: Copy Prompt Template
|
||
|
||
Copy the "Prompt Template" section from this document.
|
||
|
||
### Step 3: Customize Prompt
|
||
|
||
Modify according to your project's actual situation:
|
||
- Time nodes
|
||
- Reference material paths
|
||
- Storage location
|
||
|
||
### Step 4: Send to AI
|
||
|
||
Send the customized prompt to Claude Code or other AI assistants.
|
||
|
||
### Step 5: Review and Adjust
|
||
|
||
Review the generated document and adjust as needed:
|
||
- Supplement missing information
|
||
- Correct erroneous descriptions
|
||
- Optimize flowcharts
|
||
|
||
---
|
||
|
||
## 💼 Practical Case Reference
|
||
|
||
This prompt template is based on documents generated from actual projects:
|
||
|
||
**Project**: Futures Trading Automation System
|
||
**Generated Document**: `Code Usage Panorama_by Timeline_20251021.md`
|
||
**Document Scale**: 870 lines, 47KB
|
||
|
||
**Includes**:
|
||
- 5 timeline nodes
|
||
- 18 core scripts
|
||
- Complete ASCII data pipeline flowchart
|
||
- 6 major functional categories
|
||
- Complete tech stack and dependency descriptions
|
||
|
||
**Generation Effect**:
|
||
- ✅ New members quickly understand the system in 30 minutes
|
||
- ✅ Troubleshooting time reduced by 50%
|
||
- ✅ Document maintenance cost reduced by 70%
|
||
|
||
---
|
||
|
||
## 🔗 Related Resources
|
||
|
||
- **Project Repository Example**: https://github.com/123olp/hy1
|
||
- **Generated Document Example**: `Measurement Detailed Operation Manual/Code Usage Panorama_by Timeline_20251021.md`
|
||
- **Operation Manual Reference**: `Measurement Operation Manual/*.pdf`
|
||
|
||
---
|
||
|
||
## 📮 Feedback and Improvements
|
||
|
||
If you use this prompt template to generate documents, feel free to share:
|
||
- Your use case
|
||
- Generation effect
|
||
- Improvement suggestions
|
||
|
||
**Contact**: [Add your contact information here]
|
||
|
||
---
|
||
|
||
## 📄 License
|
||
|
||
This prompt template is licensed under the MIT license and can be freely used, modified, and shared.
|
||
|
||
---
|
||
|
||
**✨ Use this template to let AI help you quickly generate high-quality code usage documentation!**
|