308 lines
9.6 KiB
Markdown
308 lines
9.6 KiB
Markdown
# MQL4 Instruction Files - Creation Summary
|
|
|
|
## Overview
|
|
Created comprehensive MQL4 instruction files based on real-world experience from developing the MultiTimeframeZone EA. These files mirror the existing MQL5 instruction structure and provide AI agents with proper context for MQL4 development.
|
|
|
|
---
|
|
|
|
## Files Created
|
|
|
|
### 1. mql4-syntax-critical.instructions.md
|
|
**Purpose:** Critical syntax rules that prevent compilation errors
|
|
**Location:** `.github/instructions/mql4-syntax-critical.instructions.md`
|
|
**Apply To:** `**/*.mq4,**/MQL4/**/*.mqh`
|
|
|
|
**Key Sections:**
|
|
- Loop Variable Declaration (must declare before for-loop)
|
|
- Array Declarations and Sizing
|
|
- Order Functions and Trade Operations
|
|
- Price and Market Information Functions
|
|
- Object Properties and Chart Objects
|
|
- String Operations and Formatting
|
|
- Time and Date Functions
|
|
- Account and Trade Information
|
|
- Global Variables vs Input Parameters
|
|
- Common Pitfalls and Best Practices
|
|
- Compilation and Testing Checklists
|
|
- MQL4 vs MQL5 Comparison Table
|
|
|
|
**Critical Rules Covered:**
|
|
- ✅ Declare loop variables BEFORE for-loop: `int i; for(i=0; i<n; i++)`
|
|
- ✅ Use `OrderSend()`, `OrderClose()`, `OrderModify()` for trading
|
|
- ✅ Use `AccountBalance()`, `AccountEquity()` (not `AccountInfoDouble()`)
|
|
- ✅ Always call `OrderSelect()` before accessing order properties
|
|
- ✅ Normalize all prices with `NormalizeDouble(price, Digits)`
|
|
- ✅ Handle errors with `GetLastError()` and `ErrorDescription()`
|
|
|
|
---
|
|
|
|
### 2. mql4-experts.instructions.md
|
|
**Purpose:** Expert Advisor development guidelines
|
|
**Location:** `.github/instructions/mql4-experts.instructions.md`
|
|
**Apply To:** `**/MQL4/Experts/_Thivyam/**/*.mq4`
|
|
|
|
**Key Sections:**
|
|
- EA Structure and Organization
|
|
- Initialization (`OnInit()`) best practices
|
|
- Deinitialization (`OnDeinit()`) cleanup
|
|
- Main Trading Logic (`OnTick()`) patterns
|
|
- Multi-Timeframe Execution
|
|
- Trade Execution Templates
|
|
- Position Monitoring
|
|
- Risk Management (MANDATORY dynamic lot sizing)
|
|
- Pattern Detection (Engulfing patterns)
|
|
- Zone Management with Arrays
|
|
- Zone Drawing on Charts
|
|
- Error Handling
|
|
- Visual Display (Info Panels)
|
|
- Testing and Validation
|
|
- Demo/Trial Version Implementation
|
|
|
|
**Real-World Examples:**
|
|
- Complete once-per-bar execution pattern
|
|
- Multi-timeframe bar detection (H4, M30, M15)
|
|
- Pending order placement with full validation
|
|
- Position monitoring with trailing stops
|
|
- Dynamic lot calculation based on risk %
|
|
- Zone storage using fixed-size arrays
|
|
- Demo expiry logic
|
|
|
|
---
|
|
|
|
### 3. mql4-indicators.instructions.md
|
|
**Purpose:** Custom indicator development guidelines
|
|
**Location:** `.github/instructions/mql4-indicators.instructions.md`
|
|
**Apply To:** `**/MQL4/Indicators/_Thivyam/**/*.mq4`
|
|
|
|
**Key Sections:**
|
|
- Indicator Structure and Property Directives
|
|
- Buffer Declaration (Plot vs Calculation Buffers)
|
|
- OnCalculate() Function Signature and Patterns
|
|
- Efficient Calculation Pattern (using prev_calculated)
|
|
- Drawing Styles (Line, Histogram, Arrow, etc.)
|
|
- Multi-Buffer Indicators
|
|
- Arrow Drawing and Symbol Codes
|
|
- Multi-Timeframe Indicators
|
|
- Using Other Indicators (iMA, iRSI, iStochastic)
|
|
- Zone Detection Indicator Example
|
|
- Alerts and Notifications
|
|
- Performance Optimization
|
|
- Repaint vs Non-Repaint Logic
|
|
- Common Pitfalls
|
|
|
|
**Complete Examples:**
|
|
- Moving Average Indicator
|
|
- Multi-Buffer Signal Indicator
|
|
- Arrow-Based Signal Indicator
|
|
- Supply/Demand Zone Indicator
|
|
- Support/Resistance Detection
|
|
|
|
---
|
|
|
|
### 4. mql4-scripts.instructions.md
|
|
**Purpose:** Script development guidelines
|
|
**Location:** `.github/instructions/mql4-scripts.instructions.md`
|
|
**Apply To:** `**/MQL4/Scripts/_Thivyam/**/*.mq4`
|
|
|
|
**Key Sections:**
|
|
- Script Overview (OnStart vs OnTick)
|
|
- Script Structure
|
|
- Common Script Types:
|
|
- Close All Orders Script
|
|
- Delete All Objects Script
|
|
- Modify All Orders Script
|
|
- Account Information Script
|
|
- Draw Support/Resistance Lines Script
|
|
- Best Practices:
|
|
- User Confirmation
|
|
- Progress Reporting
|
|
- Error Handling
|
|
- File Operations
|
|
|
|
**Complete Working Scripts:**
|
|
Each script type includes full, production-ready code with:
|
|
- Input parameter validation
|
|
- User confirmation dialogs
|
|
- Error handling
|
|
- Progress feedback
|
|
- Result reporting
|
|
|
|
---
|
|
|
|
## Updated Files
|
|
|
|
### copilot-instructions.md
|
|
**Changes Made:**
|
|
|
|
1. **Added Section 5: Language-Specific Instructions**
|
|
- Clear routing to MQL5 vs MQL4 instruction files
|
|
- Mandatory reading requirements before coding
|
|
- Key rules summary for each language
|
|
- Python and compilation verification guidance
|
|
|
|
2. **Reorganized Section 6: Information Sourcing Protocol**
|
|
- Priority 1: Language-specific instruction files
|
|
- Priority 2: Internal documentation
|
|
- Priority 3: Official MQL5/MQL4 channels
|
|
- Priority 4: General internet search
|
|
|
|
3. **Added Section 7: Key Differences MQL4 vs MQL5**
|
|
- Side-by-side comparison table
|
|
- Critical differences highlighted
|
|
- "Golden Rule" for language separation
|
|
|
|
4. **Added Section 8: Workflow for Agentic AI Coders**
|
|
- 9-step process from identification to commit
|
|
- Emphasis on reading instructions first
|
|
- Compilation and testing requirements
|
|
|
|
5. **Added Section 9: Common Pitfalls to Avoid**
|
|
- Universal pitfalls (both languages)
|
|
- MQL4-specific pitfalls
|
|
- MQL5-specific pitfalls
|
|
|
|
6. **Added Section 10: Success Checklist**
|
|
- Pre-completion verification checklist
|
|
- 11 critical items to verify before marking task complete
|
|
|
|
---
|
|
|
|
## Key Learnings from MultiTimeframeZone EA
|
|
|
|
The instruction files incorporate these real-world lessons:
|
|
|
|
### Syntax Issues Discovered
|
|
1. **Loop Variable Declaration**: Must declare before for-loop in both MQL4 and MQL5
|
|
2. **Error Handling**: All trade operations need GetLastError() checks
|
|
3. **Price Normalization**: Critical for avoiding Error 130 (Invalid Stops)
|
|
4. **Margin Checking**: Must verify before placing orders to avoid Error 134
|
|
|
|
### Trade Execution Issues Fixed
|
|
1. **Order Type Error**: Used OP_BUYSTOP instead of OP_BUYLIMIT (wrong order type)
|
|
2. **Stop Loss Logic**: SL should be at zone boundary, not zone opposite end
|
|
3. **Price Validation**: Entry price must respect MODE_STOPLEVEL distance
|
|
4. **Lot Normalization**: Must use broker's MODE_LOTSTEP and limits
|
|
|
|
### Zone Management Issues Resolved
|
|
1. **Zone Lifecycle**: H4 zones need proper break and reversal tracking
|
|
2. **Zone Deletion**: M15 zones must be deleted after order closes
|
|
3. **Visual Styling**: Rectangle objects need proper OBJPROP_STYLE settings
|
|
4. **Zone Drawing**: Use OBJPROP_BACK=false to avoid filled rectangles
|
|
|
|
### Risk Management Issues Addressed
|
|
1. **No Hardcoded Lots**: Always calculate based on risk %
|
|
2. **Dynamic SL Distance**: Calculate from zone size or ATR
|
|
3. **Margin Validation**: Check before every trade
|
|
4. **Demo Expiry**: Implement time-limited trial logic
|
|
|
|
---
|
|
|
|
## Instruction File Structure
|
|
|
|
All instruction files follow this structure:
|
|
|
|
```
|
|
---
|
|
applyTo: "file_pattern"
|
|
---
|
|
# Title
|
|
|
|
## CRITICAL: Syntax Compliance
|
|
[Reference to critical syntax file]
|
|
|
|
## Sections
|
|
[Organized by topic]
|
|
|
|
### Code Examples
|
|
✅ CORRECT - [Description]
|
|
❌ WRONG - [Description]
|
|
|
|
## Best Practices
|
|
[Bullet points]
|
|
|
|
## Common Pitfalls
|
|
[What to avoid]
|
|
|
|
## Summary
|
|
[Checklist format]
|
|
```
|
|
|
|
---
|
|
|
|
## Usage by AI Agents
|
|
|
|
When an AI agent is asked to work with MQL code:
|
|
|
|
1. **File Type Detection**: Check file extension (.mq4 vs .mq5)
|
|
2. **Read Critical Syntax**: Read `mql4-syntax-critical.instructions.md` or `mql5-syntax-critical.instructions.md`
|
|
3. **Read Type-Specific**: Read experts/indicators/scripts instructions based on code type
|
|
4. **Follow Patterns**: Use the code examples as templates
|
|
5. **Verify Checklist**: Check all items before marking complete
|
|
6. **Compile & Test**: Use compilation-verification.instructions.md
|
|
|
|
---
|
|
|
|
## Benefits
|
|
|
|
### For AI Agents:
|
|
- Clear, unambiguous rules based on real-world experience
|
|
- Complete working examples to use as templates
|
|
- Common pitfalls explicitly documented
|
|
- Compilation verification process documented
|
|
|
|
### For Human Developers:
|
|
- Comprehensive reference for MQL4 development
|
|
- Side-by-side MQL4 vs MQL5 comparisons
|
|
- Production-ready code examples
|
|
- Testing and validation checklists
|
|
|
|
### For Project Quality:
|
|
- Consistent code style across all MQL4 projects
|
|
- Reduced compilation errors
|
|
- Fewer runtime errors
|
|
- Better error handling
|
|
|
|
---
|
|
|
|
## Files Added to Repository
|
|
|
|
```
|
|
.github/
|
|
├── copilot-instructions.md (UPDATED)
|
|
└── instructions/
|
|
├── mql4-syntax-critical.instructions.md (NEW)
|
|
├── mql4-experts.instructions.md (NEW)
|
|
├── mql4-indicators.instructions.md (NEW)
|
|
└── mql4-scripts.instructions.md (NEW)
|
|
```
|
|
|
|
Total Lines Added: ~2,740 lines of comprehensive documentation
|
|
|
|
---
|
|
|
|
## Next Steps for Users
|
|
|
|
1. **Review the Instructions**: Familiarize yourself with the new instruction files
|
|
2. **Test with New Projects**: Use these instructions when creating new MQL4 code
|
|
3. **Refine as Needed**: Update instructions based on new learnings
|
|
4. **Share with Team**: Ensure all developers follow these guidelines
|
|
|
|
---
|
|
|
|
## Maintenance
|
|
|
|
These instruction files should be updated when:
|
|
- New syntax issues are discovered
|
|
- Better patterns are identified
|
|
- MQL4 language updates are released
|
|
- Team conventions change
|
|
|
|
Keep the instruction files synchronized with real-world development experience!
|
|
|
|
---
|
|
|
|
## Conclusion
|
|
|
|
The MQL4 instruction files provide comprehensive, battle-tested guidance for AI agents developing trading systems. They incorporate real-world lessons from the MultiTimeframeZone EA project and ensure consistent, high-quality code across all _Thivyam projects.
|
|
|
|
**Key Achievement:** AI agents now have the same level of instruction quality for MQL4 as they had for MQL5, ensuring consistent development standards across both platforms.
|