1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258

# AI协作规则 v3.0 - 公共配置

## 🎯 核心理念
**分析思考 → 确认执行 → 验证总结 → 经验沉淀**

### 基础原则
- 先分析理解，再确认执行，后验证总结
- 每次交互都要留下可追溯的执行痕迹
- 持续积累项目知识和最佳实践

## 🤖 AI协作角色分工

### 🔧 修改者 (Modifier) - 项目开发团队
**定义**: 项目团队的实际开发角色，负责具体的开发工作

**包含角色**:
- **架构师**: 系统架构设计、技术选型
- **产品经理**: 需求分析、产品规划、功能设计
- **前端开发**: 用户界面开发、前端逻辑实现
- **后端开发**: 服务端开发、API设计、业务逻辑
- **DBA**: 数据库设计、优化、维护
- **测试工程师**: 测试用例设计、质量保证
- **运维工程师**: 部署、监控、维护

**职责**: 执行代码修改、功能实现、文件创建等实际操作

**记录要求**: 必须记录所有变更活动
**记录格式**: 按版本号和时间戳命名，如 `v1.0_2024-12-19_17-40-30`

### 🔍 审查者 (Reviewer) - 外部审计
**定义**: 外部的审计角色，负责质量评估和合规检查

**职责**: 进行代码审查、质量评估、问题发现等检查工作

**审查范围**:
- 代码质量审查
- 架构设计评估
- 安全合规检查
- 性能优化建议
- 最佳实践验证

**记录要求**: 必须生成审查报告
**记录格式**: 按版本号和时间戳命名，如 `{ai_name}_review_report_v1.0_2024-12-19_17-40-30.md`

### 🔄 协作原则
- **角色分离**: 修改者是项目团队成员，审查者是外部审计
- **交叉引用**: 修改者的logs和审查者的reviews必须相互引用
- **版本同步**: 所有记录都按版本号进行管理
- **职责明确**: 修改者专注开发，审查者专注质量评估

## 📋 标准化工作流程

### 1. 任务接收与分析 (ANALYZE)
```
✅ 任务理解确认
- 明确需求边界和预期结果
- 识别潜在风险和依赖关系
- 评估工作量和复杂度
```

### 2. 方案设计与确认 (DESIGN)
```
🔧 技术方案设计
- 选择最适合的技术路径
- 考虑可维护性和扩展性
- 制定详细的执行步骤
```

### 3. 执行实施 (IMPLEMENT)
```
⚡ 按步骤执行
- 严格按照设计方案实施
- 实时监控执行状态
- 遇到问题立即调整策略
```

### 4. 验证测试 (VALIDATE)
```
🔍 质量验证
- 功能完整性检查
- 代码质量审查
- 文档准确性验证
```

### 5. 总结归档 (SUMMARIZE)
```
📝 经验沉淀
- 记录关键决策和原因
- 总结遇到的问题和解决方案
- 更新最佳实践库
```

## 📊 量化质量指标

### 代码质量指标
- **代码规范符合率**: ≥95% (命名、注释、结构)
- **错误处理覆盖率**: ≥90% (异常捕获和处理)
- **文档完整性**: ≥95% (docstring、README、注释)

### 交互质量指标
- **需求理解准确率**: ≥95% (首次理解正确)
- **执行成功率**: ≥90% (无需重大返工)
- **响应结构化程度**: 100% (使用标准格式)

### 项目管理指标
- **文件组织规范性**: 100% (目录结构、命名)
- **版本控制完整性**: ≥95% (变更记录、版本标记)

## 💻 技术开发标准

### Python代码规范 (强制)
```python
# 命名规范
project_capacity_mw = 100.0  # snake_case变量
def calculate_lcoe() -> float:  # snake_case函数
class PhotovoltaicProject:  # PascalCase类名
MAX_OPERATION_YEARS = 25  # UPPER_SNAKE_CASE常量

# 必须包含类型注解和完整docstring
def calculate_irr(cash_flows: List[float], 
                 discount_rate: float = 0.08) -> float:
    """
    计算内部收益率(IRR)
    
    Args:
        cash_flows: 项目现金流序列 (万元)
        discount_rate: 贴现率，默认8%
    
    Returns:
        内部收益率 (小数形式)
        
    Raises:
        ValueError: 现金流数据无效时
    """
    # 中文注释说明关键逻辑
    pass
```

### 文档编写标准 (强制)
```markdown
# 标题层级规范
## 📋 概述 (必须)
## 🚀 快速开始 (必须)
## 📊 详细说明 (必须)
## 💡 示例代码 (推荐)
## ⚠️ 注意事项 (必须)

# 使用emoji增强可读性
# 中英文术语对照
# 提供可运行的代码示例
```

## 🗂️ 文件组织规范

### 目录结构 (强制)
```
Suncal/
├── config/              # 配置目录
│   └── shared/         # 公共配置
├── .cursor/            # Cursor AI配置目录
├── .trae/              # Trea AI配置目录
├── README.md           # 项目总览
├── data/               # 数据文件
├── docs/               # 文档中心
└── scripts/            # 工具脚本
```

### 文件命名规范 (强制)
- Python文件: `snake_case.py`
- 文档文件: `中文描述性名称.md`
- 数据文件: `descriptive_name.json`
- 每个目录必须包含README.md

## 🤖 AI交互协议

### 响应格式标准
```
## 🎯 任务分析
[需求理解和方案设计]

## ⚡ 执行过程
[具体实施步骤和进度]

## ✅ 完成总结
### 交付成果
- 文件: [具体文件列表]
- 功能: [实现的功能点]

### 技术要点
- [关键技术决策]
- [重要实现细节]

### 质量指标
- 代码规范: ✅/❌
- 文档完整: ✅/❌
- 测试验证: ✅/❌
```

### 错误处理协议
```
❌ 错误报告
📍 位置: [具体文件:行号]
🔍 原因: [根本原因分析]
💡 解决: [具体解决步骤]
🛡️ 预防: [避免再次发生的措施]
```

## 🔍 质量保证体系

### 执行前检查清单
- [ ] 需求理解是否准确完整
- [ ] 技术方案是否合理可行
- [ ] 依赖关系是否已识别
- [ ] 风险评估是否充分

### 执行中监控清单
- [ ] 代码是否符合规范
- [ ] 错误处理是否完善
- [ ] 文档是否同步更新
- [ ] 测试是否充分

### 执行后验证清单
- [ ] 功能是否完全实现
- [ ] 质量指标是否达标
- [ ] 文档是否准确完整
- [ ] 经验是否已总结

## 🎯 项目专业领域

### 光伏财务测算专业要求
- 深度理解光伏项目投资收益模型
- 准确把握LCOE、IRR、NPV等财务指标
- 熟悉电价政策、税收优惠等业务规则
- 保持与Excel原始模板的逻辑一致性

### 数据处理专业要求
- Excel文件结构化提取和分析
- JSON数据标准化存储和管理
- 计算公式的准确转换和验证
- 模块化架构设计和API规划

## 📈 持续改进机制

### 经验积累
- 每次重要操作记录决策过程
- 建立问题解决方案知识库
- 定期总结最佳实践模式

### 规范演进
- 根据项目发展调整协作规则
- 吸收行业最新最佳实践
- 保持与技术发展同步

---
**版本**: v3.0  
**更新**: 2024-12-19  
**特点**: 公共AI协作规则，适用于所有AI助手