软件工程全流程工作流

借鉴 elsewhencode/project-guidelines (29k⭐) + Google eng-practices + 业界最佳实践。

一、Git 分支策略

master/main ← 永远可部署，只接受 PR 合并
  ↑
develop    ← 日常开发主线
  ↑
feature/*  ← 每个功能/修复一个分支，从 develop 分出，合回 develop
hotfix/*   ← 紧急修复，从 master 分出，同时合回 master 和 develop

铁律

1. 永远在 feature 分支上工作，不直接改 master/develop
2. 分支前先 pull 最新 develop
3. 合并前 rebase develop（保持历史干净）
4. 一个分支只做一件事

分支命名

feature/short-description    # 新功能
bugfix/short-description     # Bug修复
hotfix/short-description     # 紧急修复
refactor/short-description   # 重构
docs/short-description       # 文档

二、提交规范 (Conventional Commits)

<type>(<scope>): <简短描述>

feat(agent): 添加成本追踪仪表盘
fix(voice): 修复 TTS 0.5s 重开麦失效
docs(readme): 更新安装说明
refactor(config): 提取配置解析逻辑
test(api): 添加 MCP gateway 集成测试
chore(deps): 升级 openai 到 2.0

原则

• 每个提交做一件事（原子性）
• 提交信息用祈使句（"添加"而不是"添加了"）
• 标题不超过 72 字符
• 需要解释"为什么"时加 body（空一行后写）
• 不在提交中包含不相关的改动（不改格式化、不修无关 bug）

三、环境管理

development  → 本地开发，随意测试
staging      → 预发布，和线上一致的环境
production   → 生产环境，只读默认

环境一致性

• 用 .venv 锁定 Python 版本
• 用 requirements.txt / pyproject.toml 锁定依赖版本
• 用 .env 管理密钥（不提交到 git）
• Docker 确保环境完全一致

四、测试策略

测试金字塔

       /\
      /E2E\      少量端到端测试（关键流程）
     /------\
    /集成测试\    中等数量（模块间交互）
   /----------\
  /  单元测试  \  大量（函数/方法级别）
 /--------------\

规则

• 新功能必须有测试
• Bug 修复必须先写复现测试
• 提交前跑全部测试
• 测试覆盖率目标 > 80%
• CI 中测试不过 = 不能合并

五、代码审查（Google 标准）

核心原则：只要 CL 让代码整体健康度提升就批准，不追求完美。

审查者做什么

1. 设计是否合理？
2. 功能是否符合需求？
3. 复杂度是否可控？
4. 有没有测试？
5. 命名是否清晰？
6. 注释是否解释"为什么"而非"是什么"？
7. 有没有安全/性能隐患？

提交者做什么

1. CL 尽量小（< 500 行）
2. 写清楚 CL 描述（做了什么、为什么、怎么测的）
3. 审查前自审一遍 diff
4. 回应每条评论（修改或解释）

六、发布流程

1. 所有 PR 合并到 develop
2. 从 develop 切 release/x.y.z
3. 在 staging 环境测试
4. 确认通过后合并到 master
5. 打 tag vx.y.z
6. master 回合并到 develop

七、日志规范

• ERROR：需要立即关注的问题
• WARNING：可能需要关注的异常
• INFO：关键业务流程节点
• DEBUG：调试信息（生产环境关掉）

永远不记录：密码、密钥、个人身份信息。

八、文档原则

• README.md：项目是什么、怎么跑、怎么部署
• CONTRIBUTING.md：怎么参与开发
• CHANGELOG.md：每个版本的变更
• docs/：详细文档
• 代码内注释：解释"为什么"，不是"是什么"