012-kaopeilian/docs/规划/后端开发拆分策略/子agent/使用时的最佳实践.md

子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启动提示词模板

我是[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. 协作开发技巧

模拟其他模块

# 当依赖的模块还未完成时
# 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

定义接口契约

# 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: ...

集成测试桩

# 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

# 在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

检查数据库连接

# 临时健康检查
@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更高效、更准确地完成开发任务。