Skip to content

BEST_PRACTICES.md

Latest commit

 

History

History
527 lines (429 loc) · 11.4 KB

BEST_PRACTICES.md

File metadata and controls

527 lines (429 loc) · 11.4 KB

最佳实践指南

目录

  1. 共享上下文最佳实践
  2. QA 验证最佳实践
  3. 决策记录最佳实践
  4. 知识库管理最佳实践
  5. 反馈循环最佳实践
  6. 工作流管理最佳实践
  7. 常见陷阱和解决方案

共享上下文最佳实践

1. 充分利用共享上下文

✅ 好的做法

# 获取特定角色的上下文
context = shared_context.get_context_for_agent(agent_role)

# 检查相关的设计决策
design_decisions = context['design_decisions']

# 查看已识别的风险
risks = context['risks']

# 了解其他 Agent 的假设
assumptions = context['assumptions']

❌ 避免

# 让 Agent 在没有上下文的情况下工作
# 这会导致重复工作和决策冲突

2. 定期更新上下文

✅ 好的做法

# 在每个重要决策后立即更新上下文
context.add_design_decision(decision)

# 识别新的风险时立即记录
context.add_risk(risk)

# 发现新的假设时立即添加
context.add_assumption(assumption)

❌ 避免

# 等到项目结束才更新上下文
# 这样其他 Agent 无法获得最新信息

3. 使用有意义的 ID 和标题

✅ 好的做法

requirement = Requirement(
    id="req_auth_oauth",
    title="OAuth 用户认证",
    description="用户可以通过 OAuth 2.0 登录系统"
)

❌ 避免

requirement = Requirement(
    id="req_1",
    title="认证",
    description="用户认证"
)

QA 验证最佳实践

1. 早期验证

✅ 好的做法

# 在 PRD 完成后立即验证
prd_validation = qa_validator.validate_prd(prd)
if not prd_validation.passed:
    # 立即修改，而不是继续
    fix_prd(prd_validation.issues)
    # 重新验证
    prd_validation = qa_validator.validate_prd(prd)

❌ 避免

# 等到项目后期才发现问题
# 这会导致大量返工

2. 处理验证反馈

✅ 好的做法

result = qa_validator.validate_prd(prd)
if not result.passed:
    print(f"问题: {result.issues}")
    print(f"建议: {result.suggestions}")
    # 根据建议改进
    for suggestion in result.suggestions:
        implement_suggestion(suggestion)

❌ 避免

# 忽视验证反馈
# 这会导致质量问题

3. 三层验证流程

✅ 好的做法

# 第一层：PRD 验证
prd_result = qa.validate_prd(prd)
assert prd_result.passed, "PRD 验证失败"

# 第二层：架构验证
arch_result = qa.validate_architecture(prd, architecture)
assert arch_result.passed, "架构验证失败"

# 第三层：实现验证
impl_result = qa.validate_implementation(prd, architecture, code)
assert impl_result.passed, "实现验证失败"

决策记录最佳实践

1. 记录所有重要决策

✅ 好的做法

# 记录每个架构决策
decision = DesignDecision(
    title="使用 tRPC 而不是 REST",
    context="需要端到端类型安全",
    decision="采用 tRPC",
    reasoning="tRPC 提供完整的类型安全和自动文档",
    alternatives=[
        {"name": "REST", "reason_rejected": "需要手动类型检查"},
        {"name": "GraphQL", "reason_rejected": "学习曲线陡峭"}
    ],
    consequences={
        "pros": ["类型安全", "自动文档", "简单易用"],
        "cons": ["学习成本", "生态较小"]
    }
)
adr_system.record_decision(decision)

❌ 避免

# 只记录决策，不记录推理过程
# 这样后来的人无法理解为什么做这个决策

2. 详细的推理过程

✅ 好的做法

decision = DesignDecision(
    reasoning="""
    我们考虑了三个选项：
    1. REST: 简单但需要手动类型检查
    2. GraphQL: 强大但学习曲线陡峭
    3. tRPC: 简单且提供类型安全
    
    我们选择 tRPC 因为：
    - 团队已经熟悉 TypeScript
    - 项目规模中等，不需要 GraphQL 的复杂性
    - 类型安全对我们的项目很重要
    """
)

3. 记录替代方案

✅ 好的做法

alternatives = [
    {
        "name": "REST",
        "pros": ["广泛支持", "简单"],
        "cons": ["需要手动类型检查"],
        "reason_rejected": "缺乏类型安全"
    },
    {
        "name": "GraphQL",
        "pros": ["强大", "灵活"],
        "cons": ["学习曲线陡峭", "过度设计"],
        "reason_rejected": "对我们的项目来说太复杂"
    }
]

知识库管理最佳实践

1. 积极添加设计模式

✅ 好的做法

# 完成一个项目后，提取可复用的模式
pattern = {
    "name": "三层权限模型",
    "description": "支持公开、私密、自定义三种可见性",
    "keywords": "permission visibility privacy",
    "use_cases": ["社交平台", "内容管理系统"],
    "implementation": "visibleType + visibleUsers 表",
    "pros": ["简单易懂", "灵活", "高效"],
    "cons": ["不支持复杂权限规则"],
    "when_to_use": "需要简单的权限控制时",
    "when_not_to_use": "需要复杂的基于角色的权限控制时"
}
pattern_library.add_pattern(pattern)

2. 创建项目模板

✅ 好的做法

# 为常见项目类型创建模板
template = {
    "type": "social_platform",
    "core_features": [
        "用户认证",
        "内容发布",
        "点赞和评论",
        "搜索功能"
    ],
    "non_functional_requirements": [
        "实时更新",
        "高可用性",
        "可扩展性"
    ],
    "estimated_effort": "4-6 周"
}

3. 记录项目经验

✅ 好的做法

# 项目完成后，记录经验教训
project_history.record_project({
    "type": "social_platform",
    "name": "Moments 应用",
    "duration": "4 周",
    "team_size": 3,
    "what_went_well": [
        "清晰的需求定义",
        "完整的架构设计",
        "及早的 QA 验证"
    ],
    "what_could_improve": [
        "提前进行性能优化",
        "更多的集成测试"
    ],
    "key_decisions": ["ADR-1", "ADR-2"],
    "risks_encountered": [
        {"risk": "性能瓶颈", "mitigation": "添加缓存层"}
    ],
    "lessons_learned": [
        "共享上下文大大提高了协作效率",
        "早期 QA 验证避免了返工"
    ]
})

反馈循环最佳实践

1. 建立反馈文化

✅ 好的做法

# 提供建议，不只是批评
feedback_loop.provide_feedback(
    feedback_type="qa_validation",
    source_agent=AgentRole.QA,
    target_agent=AgentRole.DEVELOPER,
    content="发现了一些代码质量问题",
    issues=["缺少错误处理", "测试覆盖率不足"],
    suggestions=[
        "在关键路径上添加 try-catch 块",
        "为每个函数编写单元测试"
    ]
)

2. 及时处理反馈

✅ 好的做法

# 定期检查反馈
feedback = feedback_loop.get_feedback_for_agent(AgentRole.DEVELOPER)

# 立即处理反馈
for item in feedback:
    if not item['resolved']:
        # 处理反馈
        implement_feedback(item)
        # 标记为已解决
        feedback_loop.mark_feedback_resolved(item['id'])

3. 反馈的可操作性

✅ 好的做法

# 反馈应该具体和可操作
feedback_loop.provide_feedback(
    issues=[
        "函数 calculate_total() 没有处理 null 输入",
        "test_user_authentication.py 的测试覆盖率只有 60%"
    ],
    suggestions=[
        "添加 null 检查: if (!items) return 0;",
        "添加边界情况测试: 空列表、无效令牌等"
    ]
)

❌ 避免

# 模糊的反馈
issues=["代码质量差"]
suggestions=["改进代码"]

工作流管理最佳实践

1. 准确分析复杂度

✅ 好的做法

# 仔细评估项目复杂度
requirements = {
    "features": [
        {"title": "用户认证", "complexity": 2},
        {"title": "内容发布", "complexity": 3},
        {"title": "搜索功能", "complexity": 4}
    ],
    "non_functional_requirements": [
        "实时更新",
        "高可用性"
    ],
    "special_requirements": [
        "GDPR 合规"
    ]
}

complexity = workflow.analyze_project_complexity(requirements)
# 结果: 7/10 → 选择 COMPLEX 工作流

2. 根据复杂度选择工作流

✅ 好的做法

# 简单项目：快速迭代
if complexity <= 2:
    stages = workflow.get_workflow_stages("simple")
    # PM → Developer → QA

# 中等项目：标准流程
elif complexity <= 5:
    stages = workflow.get_workflow_stages("standard")
    # PM → Architect → Developer → QA

# 复杂项目：完整流程
else:
    stages = workflow.get_workflow_stages("complex")
    # PM → Security → Architect → Performance → Developer → QA

3. 定期评估工作流

✅ 好的做法

# 项目进行中评估工作流效果
if project_complexity_increased:
    # 升级工作流
    new_workflow = workflow.select_workflow(new_complexity)
    # 添加新的阶段
    add_stages(new_workflow)

常见陷阱和解决方案

陷阱 1：忽视共享上下文

问题

# Developer 不查看共享上下文
# 导致重复工作和决策冲突

解决方案

# 在每个阶段开始时获取上下文
context = shared_context.get_context_for_agent(agent_role)

# 检查相关的决策和风险
design_decisions = context['design_decisions']
risks = context['risks']

陷阱 2：验证太晚

问题

# 只在项目结束时进行验证
# 导致大量返工

解决方案

# 在每个环节进行验证
prd_result = qa.validate_prd(prd)
assert prd_result.passed

arch_result = qa.validate_architecture(prd, architecture)
assert arch_result.passed

impl_result = qa.validate_implementation(prd, architecture, code)
assert impl_result.passed

陷阱 3：不记录决策

问题

# 没有记录为什么做这个决策
# 后来的人无法理解

解决方案

# 详细记录每个决策
decision = DesignDecision(
    title="...",
    reasoning="...",  # 详细的推理过程
    alternatives=[...],  # 考虑过的其他方案
    consequences={...}  # 优点和缺点
)
adr_system.record_decision(decision)

陷阱 4：不使用知识库

问题

# 每个项目都从零开始
# 浪费时间和资源

解决方案

# 查询相似的历史决策
similar = adr_system.get_similar_decisions(context)

# 查询推荐的设计模式
pattern = pattern_library.suggest_pattern(requirement)

# 查询相似的历史项目
projects = project_history.get_similar_projects(type)

陷阱 5：反馈不可操作

问题

# 反馈太模糊，无法实施
issues=["代码质量差"]

解决方案

# 提供具体和可操作的反馈
issues=[
    "函数 calculate_total() 没有处理 null 输入",
    "test_user_authentication.py 的测试覆盖率只有 60%"
]
suggestions=[
    "添加 null 检查: if (!items) return 0;",
    "添加边界情况测试"
]

总结

遵循这些最佳实践可以帮助您：

✅ 提高协作效率 ✅ 减少返工 ✅ 积累知识 ✅ 改进代码质量 ✅ 加快项目交付

记住：好的实践不是一次性的，而是持续的过程。定期审视和改进您的工作流。

更新时间: 2026-02-11