# 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助手