MBE 团队开发协作指南
版本: v1.0
更新时间: 2026-01-28
👥 团队结构
推荐配置（根据团队规模）
小型团队 (2-3人)
角色1: 全栈开发 + Tech Lead
- 后端开发
- 系统架构
- 代码审查
- 部署运维
角色2: 前端开发 + 测试
- 前端界面
- 用户体验
- 功能测试
- 文档维护
角色3: 后端开发 (可选)
- 功能开发
- 知识库维护
- 专家配置
中型团队 (5-8人)
Tech Lead (1人)
├── 后端组 (2-3人)
│ ├── 核心功能开发
│ ├── API设计
│ └── 知识库管理
├── 前端组 (1-2人)
│ ├── PWA开发
│ └── 用户界面
├── 测试+运维 (1-2人)
│ ├── 自动化测试
│ ├── 性能测试
│ └── 部署维护
└── 产品 (1人)
├── 需求管理
└── 用户反馈
🔄 开发流程详解
1. Sprint 规划 (每2周)
Sprint 开始
时间: 周一上午
参与: 全员
时长: 2小时
议程:
1. Sprint 目标确定 (15分钟)
2. 需求评审 (30分钟)
- 产品讲解需求
- 技术提问澄清
3. 任务分解 (45分钟)
- 拆分用户故事
- 估算工作量
- 分配任务
4. 风险识别 (15分钟)
- 技术风险
- 依赖风险
5. 确认目标 (15分钟)
输出:
- Sprint Backlog
- 任务分配表
- 风险清单
Sprint 执行
每日站会 (10:00, 15分钟):
每人回答3个问题:
1. 昨天完成了什么?
2. 今天计划做什么?
3. 遇到什么阻碍?
站会原则:
- 准时开始
- 简洁明了
- 问题会后讨论
开发规范:
# 每天的工作流程
1. 早上: 拉取最新代码
git checkout develop
git pull origin develop
2. 开发: 在功能分支开发
git checkout feature/xxx
# ... 编码 ...
3. 提交: 及时提交代码
git add .
git commit -m "feat: XXX"
git push origin feature/xxx
4. 审查: 创建PR请求审查
# GitHub/GitLab 创建 PR
5. 合并: 审查通过后合并
git checkout develop
git merge feature/xxx
Sprint 结束
时间: 周五下午
参与: 全员
时长: 1.5小时
议程:
1. Sprint 演示 (30分钟)
- 演示完成的功能
- 产品确认验收
2. Sprint 回顾 (30分钟)
- 做得好的地方
- 需要改进的地方
- 行动计划
3. Sprint 指标回顾 (30分钟)
- 完成率
- 质量指标
- 性能指标
📝 任务管理
Jira/Linear 使用规范
任务状态流转
TODO → In Progress → Code Review → Testing → Done
↓ ↓ ↓ ↓ ↓
计划中 开发中 审查中 测试中 已完成
任务模板
用户故事:
标题: [功能] 作为XXX，我想要XXX，以便XXX
描述:
作为: 律师专家用户
我想要: System Prompt 优化
以便: 提供更专业的法律回答
验收标准:
- [ ] 法律引用覆盖率 > 80%
- [ ] 举证指导覆盖率 > 60%
- [ ] 测试通过率 > 90%
技术方案:
- 更新 experts/index.json
- 添加详细 system_prompt
- 测试验证
工作量估算: 2 Story Points
Bug:
标题: [Bug] 民事律师回答混入面包知识
描述:
重现步骤:
1. 访问 mbe.hi-maker.com
2. 提问: "离婚财产怎么分?"
3. 回答中出现"面包发酵"等无关内容
预期行为: 只返回民事法律相关内容
实际行为: 混入了其他知识库内容
环境: 生产环境
优先级: P1 - High
根因分析:
- 知识库检索未隔离
- 缺少 kb_id 过滤
修复方案:
- 在 _search_chunks 添加 kb_id 过滤
- 重新测试验证
🔀 Git 工作流
分支策略 (Git Flow)
main (生产)
├── v1.0.0 (tag)
├── v1.1.0 (tag)
└── v1.2.0 (tag)
↑
release/v1.2.0 (发布准备)
↑
develop (开发主分支)
↑
├── feature/system-prompt-optimization
├── feature/knowledge-base-isolation
├── bugfix/expert-routing
└── hotfix/critical-bug
分支命名规范
feature/<issue-id>-<short-description>
例: feature/MBE-123-system-prompt-optimization
bugfix/<issue-id>-<short-description>
例: bugfix/MBE-456-fix-kb-contamination
hotfix/<issue-id>-<short-description>
例: hotfix/MBE-789-critical-security-fix
release/v<major>.<minor>.<patch>
例: release/v1.2.3
Commit 规范
<type>(<scope>): <subject>
<body>
<footer>
类型 (type):
- feat: 新功能
- fix: Bug修复
- docs: 文档
- style: 格式
- refactor: 重构
- test: 测试
- chore: 构建工具
范围 (scope):
- knowledge: 知识库相关
- expert: 专家系统
- api: API接口
- ui: 用户界面
- db: 数据库
- deploy: 部署相关
示例:
feat(knowledge): 为民事律师添加system_prompt优化
- 添加2000+字符的详细system_prompt
- 包含法律引用、举证指导标准
- 通过10个测试用例验证
Closes #123
📋 代码审查规范
审查流程
1. 开发者创建 PR
- 填写完整的 PR 描述
- 自测通过
- CI 测试通过
2. 自动检查
- 代码规范检查
- 单元测试
- 类型检查
- 安全扫描
3. 人工审查
- 至少1人审查
- 核心功能至少2人审查
- Tech Lead 审查重要变更
4. 修改反馈
- 审查者提出建议
- 开发者修改
- 重新审查
5. 合并
- 审查通过
- CI通过
- 合并到目标分支
审查重点
功能正确性
- [ ] 功能是否符合需求?
- [ ] 边界条件是否处理?
- [ ] 错误情况是否考虑?
代码质量
- [ ] 代码是否清晰易懂?
- [ ] 命名是否规范?
- [ ] 是否有重复代码?
- [ ] 是否遵循设计模式?
性能考虑
- [ ] 是否有性能瓶颈?
- [ ] 数据库查询是否优化?
- [ ] 缓存是否合理使用?
- [ ] 是否有内存泄漏风险?
安全性
- [ ] 是否有SQL注入风险?
- [ ] 是否有XSS风险?
- [ ] 敏感信息是否加密?
- [ ] 权限控制是否正确?
可维护性
- [ ] 是否有充分的注释?
- [ ] 是否有单元测试?
- [ ] 日志是否充分?
- [ ] 文档是否更新?
🎯 实际工作场景
场景1: 添加新功能
需求: 为民事律师添加 system_prompt 优化
Day 1 (周一):
10:00 - Sprint Planning
11:00 - 需求评审和技术方案讨论
14:00 - 创建功能分支 feature/system-prompt-opt
15:00 - 开始开发
Day 2 (周二):
10:00 - 每日站会
10:15 - 继续开发
15:00 - 本地测试
16:00 - 提交代码并创建 PR
17:00 - 请求代码审查
Day 3 (周三):
10:00 - 每日站会
10:15 - 根据审查意见修改
14:00 - 审查通过，合并到 develop
15:00 - 自动部署到开发环境
16:00 - 运行集成测试
17:00 - 测试通过，功能完成
Day 4-5 (周四-周五):
- 开发其他功能
- 准备 Sprint 演示
Week 2 (周五):
14:00 - Sprint 演示
15:00 - 准备发布
16:00 - 部署到生产环境
17:00 - 监控验证
场景2: 紧急Bug修复
事件: 生产环境民事律师回答混入面包知识
10:00 - 用户报告问题
10:05 - Tech Lead 确认为 P1 Bug
10:10 - 创建 hotfix/kb-isolation 分支
10:30 - 完成代码修复
11:00 - 本地测试通过
11:10 - 部署到开发环境验证
11:30 - 测试通过
11:40 - 创建 PR，快速审查
12:00 - 审查通过，合并
12:10 - 部署到生产环境
12:30 - 验证修复成功
13:00 - 通知用户问题已修复
15:00 - 编写事故报告
📊 项目管理建议
Sprint 看板
TODO | In Progress | Code Review | Testing | Done
-----|-------------|-------------|---------|------
5票 | 3票 | 2票 | 1票 | 15票
规则:
- In Progress 限制: 每人最多2个任务
- Code Review 48小时内完成
- Testing 24小时内完成
优先级管理
P0 - Critical (紧急且重要)
- 生产服务中断
- 数据丢失风险
- 安全漏洞
→ 立即处理，4小时内修复
P1 - High (重要)
- 核心功能异常
- 影响大量用户
- 重要功能缺失
→ 24小时内修复
P2 - Medium (正常)
- 一般功能问题
- 影响部分用户
- 功能优化
→ 1周内处理
P3 - Low (不紧急)
- 小问题
- 优化建议
- 技术债务
→ 排期处理
🛠️ 开发工具配置
1. IDE 配置
VSCode / Cursor 推荐插件
{
"recommendations": [
"ms-python.python",
"ms-python.vscode-pylance",
"ms-azuretools.vscode-docker",
"eamodio.gitlens",
"streetsidesoftware.code-spell-checker",
"editorconfig.editorconfig"
]
}
配置文件 (.vscode/settings.json)
{
"python.linting.enabled": true,
"python.linting.flake8Enabled": true,
"python.formatting.provider": "black",
"editor.formatOnSave": true,
"editor.codeActionsOnSave": {
"source.organizeImports": true
}
}
2. Git Hooks
Pre-commit Hook
创建 .git/hooks/pre-commit:
#!/bin/bash
# 提交前检查
echo "运行代码检查..."
# 1. 代码格式
python -m black src/ --check
if [ $? -ne 0 ]; then
echo "❌ 代码格式不符合规范，请运行: python -m black src/"
exit 1
fi
# 2. 代码规范
python -m flake8 src/
if [ $? -ne 0 ]; then
echo "❌ 代码规范检查失败"
exit 1
fi
# 3. 类型检查
python -m mypy src/
if [ $? -ne 0 ]; then
echo "❌ 类型检查失败"
exit 1
fi
# 4. 单元测试
python -m pytest tests/ -x
if [ $? -ne 0 ]; then
echo "❌ 单元测试失败"
exit 1
fi
echo "✅ 所有检查通过"
📚 知识分享
技术分享会 (每周五)
Week 1: Python 最佳实践
Week 2: Docker 容器化
Week 3: FastAPI 性能优化
Week 4: 知识库设计
Week 5: LLM Prompt Engineering
...
格式:
- 演讲: 30分钟
- 讨论: 15分钟
- Q&A: 15分钟
要求:
- 准备PPT或Demo
- 分享可复用的经验
- 会后整理文档
文档维护
/docs
├── architecture/ # 架构文档
│ ├── system-design.md
│ └── database-schema.md
├── api/ # API文档
│ ├── openapi.yaml
│ └── endpoints.md
├── development/ # 开发文档
│ ├── setup.md
│ └── coding-style.md
├── deployment/ # 部署文档
│ ├── deployment-guide.md
│ └── rollback-guide.md
└── troubleshooting/ # 故障排查
├── common-issues.md
└── debugging-guide.md
🔐 权限管理
环境访问权限
| 角色 | 本地 | 开发环境 | 生产环境 |
|---|---|---|---|
| 开发 | ✅ 读写 | ✅ 读写 | ❌ 只读日志 |
| 测试 | ✅ 读写 | ✅ 读写 | ❌ 只读日志 |
| Tech Lead | ✅ 读写 | ✅ 读写 | ✅ 读写 |
| 运维 | ✅ 读写 | ✅ 读写 | ✅ 读写 |
Git 权限
main 分支:
- 只有 Tech Lead 可以直接推送
- 需要至少2个 Approve
- 需要 CI 通过
develop 分支:
- 开发者可以推送 PR
- 需要至少1个 Approve
- 需要 CI 通过
feature 分支:
- 开发者自由创建和推送
📈 质量保证
代码质量指标
- 测试覆盖率: > 70%
- 代码复杂度: Cyclomatic < 10
- 代码重复率: < 5%
- 技术债务: < 10%
定期检查
每日:
- CI/CD 状态
- 错误日志
- 性能监控
每周:
- 代码质量报告
- 测试覆盖率
- 性能测试
每月:
- 技术债务盘点
- 依赖更新检查
- 安全漏洞扫描
🎓 新成员入职
第1天: 环境搭建
1. 账号开通
- GitHub/GitLab
- Slack/飞书
- Jira/Linear
- 服务器访问
2. 文档阅读
- 系统架构文档
- 开发规范文档
- API文档
3. 环境搭建
- 克隆代码
- 启动本地环境
- 验证可以运行
第2-3天: 熟悉代码
1. 代码导读 (Mentor)
- 项目结构介绍
- 核心模块讲解
- 关键流程梳理
2. 运行测试
- 运行单元测试
- 运行集成测试
- 理解测试用例
3. 小任务实践
- 修复一个简单Bug
- 添加一个简单功能
- 完成代码审查流程
第4-5天: 独立开发
1. 接手正式任务
- 选择合适的任务
- 独立完成开发
- 请求代码审查
2. 参与协作
- 审查他人代码
- 参与技术讨论
- 提出改进建议
🎯 成功案例: System Prompt 优化项目
项目背景
- 问题: 民事律师回答缺少法律引用，质量不高
- 目标: 法律引用覆盖率 40% → 80%+
- 时间: 1个Sprint (2周)
执行过程
Week 1:
Day 1: 问题分析和方案设计
Day 2: 设计 system_prompt
Day 3: 本地开发和测试
Day 4: 部署到开发环境
Day 5: 开发环境测试验证
Week 2:
Day 1: 修复发现的问题
Day 2: 完善测试用例
Day 3: 准备发布文档
Day 4: 部署到生产环境
Day 5: 监控和验证，Sprint演示
关键决策
决策1: 不增加知识库内容，只优化 system_prompt
原因: 知识库已足够丰富，问题在于使用机制
结果: 0成本，显著效果
决策2: 先开发环境验证，再生产部署
原因: 降低风险
结果: 发现问题并修复，生产部署顺利
决策3: 使用10个问题快速测试
原因: 快速验证效果
结果: 发现知识库隔离问题并修复
成果
✅ 法律引用覆盖率: 40% → 100%
✅ 知识库隔离: 100%成功
✅ 专业性提升: 3/5 → 4.5/5
✅ 成本: 0元
✅ 时间: 按时完成
📞 沟通协作
沟通渠道
日常沟通: Slack/飞书
#general - 一般讨论
#development - 技术讨论
#testing - 测试相关
#deployment - 部署通知
#emergency - 紧急事件
代码讨论: GitHub/GitLab
- PR评论
- Issue讨论
- Code Review
文档协作: Notion/Confluence
- 技术文档
- 产品文档
- 会议记录
视频会议: Zoom/腾讯会议
- Sprint Planning
- Sprint Review
- 技术讨论
沟通原则
1. 异步优先
- 文档记录
- Issue/PR 讨论
- 减少会议
2. 清晰表达
- 明确问题
- 提供上下文
- 附带截图/日志
3. 及时响应
- 工作时间 2小时内回复
- 紧急问题立即响应
- 标记优先级
4. 友善协作
- 尊重他人意见
- 建设性反馈
- 团队第一
🎊 总结
核心原则
- ✅ 质量第一: 代码质量 > 开发速度
- ✅ 自动化: 能自动化的都自动化
- ✅ 文档化: 重要决策和流程都文档化
- ✅ 小步快跑: 快速迭代，持续改进
- ✅ 团队协作: 沟通透明，互相支持
成功指标
开发效率:
✅ Sprint 完成率 > 85%
✅ 代码审查 24小时内完成
✅ Bug修复及时
代码质量:
✅ 测试覆盖率 > 70%
✅ 代码审查率 100%
✅ 生产Bug < 5个/Sprint
团队协作:
✅ 每日站会参与率 100%
✅ 文档及时更新
✅ 知识共享活跃
文档版本: v1.0
适用范围: MBE 项目
维护: 持续更新