# 子Agent使用时的最佳实践

## 1. 推荐的引用方式

### 完整引用（最佳）
```
# 通用基础
@子agent/00-通用基础/base_prompt.md
@子agent/00-通用基础/project_structure.md
@子agent/00-通用基础/essential_docs.md

# 架构规划（强烈推荐）
@考培练系统规划/后端开发拆分策略/协作机制设计.md
@考培练系统规划/后端开发拆分策略/模块分工指南.md
@考培练系统规划/后端开发拆分策略/开发规范文档.md

# Agent特定
@子agent/01-Agent-Auth/prompt.md
@子agent/01-Agent-Auth/context.md
@子agent/01-Agent-Auth/checklist.md

我是Agent-Auth，准备开始开发认证模块。
我已经理解了项目的整体架构和协作机制。
```

### 标准引用
```
@子agent/01-Agent-Auth/prompt.md
@子agent/01-Agent-Auth/context.md

按照Agent-Auth的角色开发认证模块。
```

### 最小引用
```
@子agent/01-Agent-Auth/prompt.md

开始开发Auth模块。
```

## 2. Agent启动提示词模板

```markdown
我是[Agent名称]，我已经阅读了：
1. 通用开发规范（base_prompt.md）
2. 项目结构说明（project_structure.md）
3. 我的角色定义（prompt.md）
4. 项目上下文（context.md）

我理解我需要：
- 遵循统一的代码规范
- 使用项目的基础类和工具
- 与其他模块保持接口一致
- 编写测试和文档

项目根目录是：/Users/nongjun/Desktop/Ai公司/本地开发与测试/kaopeilian-backend/

我现在开始按照checklist.md的步骤进行开发。
```

## 3. 常见问题的预防性提醒

### 开始开发前
```
提醒：
1. 所有import从app开始，不是从根目录
2. 继承BaseModel和相应的Mixin
3. 使用项目定义的异常类
4. 遵循日志规范
5. API响应使用ResponseModel包装
```

### 创建新文件时
```
注意文件位置：
- API路由放在 app/api/v1/
- 模型放在 app/models/
- Schema放在 app/schemas/
- 服务放在 app/services/
- 测试放在 tests/
```

### 依赖其他模块时
```
检查依赖关系：
- 从 app.api.deps 导入认证依赖
- 不要循环依赖
- 使用依赖注入而不是直接导入
```

## 4. 分步开发策略

### 第一步：理解和规划
```
1. 仔细阅读所有文档
2. 列出需要创建的文件
3. 确认依赖关系
4. 制定开发顺序
```

### 第二步：创建基础结构
```
1. 先创建数据模型
2. 定义Schema
3. 创建空的Service类
4. 创建路由框架
```

### 第三步：实现核心功能
```
1. 实现一个最简单的功能
2. 测试是否能正常运行
3. 逐步添加其他功能
4. 同步编写测试
```

### 第四步：完善和优化
```
1. 添加错误处理
2. 完善日志记录
3. 优化性能
4. 补充文档
```

## 5. 协作开发技巧

### 模拟其他模块
```python
# 当依赖的模块还未完成时
# mocks/auth.py
async def get_current_user_mock():
    return User(id=1, username="test", role="admin")

# 在开发时临时使用
from mocks.auth import get_current_user_mock as get_current_user
```

### 定义接口契约
```python
# interfaces/auth_interface.py
from typing import Protocol

class AuthServiceInterface(Protocol):
    async def get_current_user(self, token: str) -> User: ...
    async def verify_token(self, token: str) -> dict: ...
```

### 集成测试桩
```python
# tests/stubs/external_service.py
class DifyServiceStub:
    async def generate_exam_questions(self, **kwargs):
        return [{"question": "测试题目", "answer": "A"}]
```

## 6. 输出质量检查

### 代码风格
- [ ] 是否遵循了PEP 8
- [ ] 导入是否按规范排序
- [ ] 是否有类型注解
- [ ] 文档字符串是否完整

### 功能完整性
- [ ] 是否实现了所有要求的API
- [ ] 错误处理是否完善
- [ ] 日志记录是否充分
- [ ] 是否有相应的测试

### 安全性
- [ ] 是否有SQL注入风险
- [ ] 是否验证了所有输入
- [ ] 敏感信息是否加密
- [ ] 权限检查是否到位

## 7. 调试和验证

### 快速验证API
```python
# 在main.py临时添加
@app.get("/debug/routes")
async def debug_routes():
    routes = []
    for route in app.routes:
        if hasattr(route, "methods"):
            routes.append({
                "path": route.path,
                "methods": list(route.methods),
                "name": route.name
            })
    return routes
```

### 检查数据库连接
```python
# 临时健康检查
@app.get("/debug/db")
async def check_db(db: AsyncSession = Depends(get_db)):
    try:
        await db.execute("SELECT 1")
        return {"status": "connected"}
    except Exception as e:
        return {"status": "error", "message": str(e)}
```

## 8. 持续改进

### 收集反馈
- 记录Agent生成代码的问题
- 改进prompt和示例
- 更新checklist

### 知识共享
- 将好的代码片段加入examples
- 更新常见问题解答
- 分享成功经验

通过遵循这些最佳实践，可以让Agent更高效、更准确地完成开发任务。