跳到主要内容

Git 团队协作

AI 辅助开发改变了代码产出的速度，但没有改变协作的根本逻辑：让每一次改动都可追溯、可回滚、可理解。本文结合现代 IDE（Cursor）与 AI 的使用场景，讲解 RentHub 团队的 Git 实践。

1. 分支策略​

1.1 主干结构​

main          ← 生产环境，保持随时可部署
  └─ dev      ← 集成分支，功能完成后合入
       └─ feature/<name>   ← 功能开发
       └─ fix/<name>       ← Bug 修复
       └─ chore/<name>     ← 依赖/配置/文档等非功能性改动
  • main 只接受来自 dev 的 PR，不允许直接 push
  • dev 可以接受功能分支 PR，合并后删除功能分支
  • 分支名全小写、连字符分隔，见名知意：feature/order-pagination、fix/login-crash

1.2 分支生命周期​

  1. 从最新的 dev 切出功能分支
  2. 开发 → 提交 → Push → 开 PR → Review → Merge
  3. Merge 后删除远程与本地分支

AI 辅助开发容易产生大量改动，更应该坚持小分支原则，避免一个分支堆积数百个文件的修改。

2. Commit 规范​

请勿使用源代码管理（Source Control）面板里、提交说明（Message）输入框右侧的星标 / 闪亮图标：那是 IDE 内置的「按暂存改动生成 commit message」，通常只做简短概括，不会走 RentHub 要求的 Conventional Commits 体例，也不会像团队 Skill 那样结合 git diff 判断是否需要拆分多个 commit、并在 body 里强调「为什么」。正式提交请统一使用下文 §2.2 中的 /renthub-commit Skill，由 Skill 起草说明、你确认后再执行 git commit。

Cursor / VS Code 源代码管理：Message 框右侧星标为内置生成入口，请勿作为 RentHub 规范下的提交方式

2.1 格式​

采用 Conventional Commits 格式，由三部分构成：

<type>(<scope>): <subject>

[可选 body：解释为什么，而非做了什么]

逐段解释：

部分含义是否必填示例
type这次改动的类型必填feat、fix、chore
(scope)影响的模块或范围，用括号包裹可省略(order)、(auth)、(admin)
: subject一句话描述做了什么，动词开头，不加句号必填支持订单分页查询
空行 + body另起一段，解释为什么要做这个改动可省略见下方示例

常用 type：

type用途
feat新功能
fixBug 修复
refactor重构（不新增功能，不修 bug）
chore依赖、配置、构建脚本等非业务改动
docs纯文档变更
test测试相关
style格式、空格等不影响逻辑的改动

示例对比：

# 只有标题行（scope 可省略）
fix: 修复登录页面空白问题

# 带 scope
feat(order): 支持订单分页查询

# 带 scope + body（解释为什么）
feat(order): 支持订单分页查询

后台数据量增大后全量查询性能下降，改为游标分页。
前端传入 lastId 参数，每次返回 20 条。

body 写“为什么”，不写“做了什么”。“做了什么”代码本身就能说明，但“为什么这样做”只有你知道，三个月后的队友看到 body 才能真正理解这次改动的背景。

2.2 让 AI 帮你写 commit message（推荐）​

写好一条 commit message 需要思考，但 AI 可以承担大部分起草工作。本仓库已内置 renthub-commit skill，封装了完整的提交流程。

使用方式：

在 Cursor Composer 中输入 /renthub-commit，skill 会自动：

  1. 读取 git status 与 git diff 分析当前改动
  2. 判断是否需要拆分为多个 commit
  3. 按规范起草 type(scope): subject + body
  4. 展示给你确认，确认后执行 git commit

整个过程不需要手动打一行命令。

注意事项：

  • AI 起草的 message 仍需人工确认再执行，不要无脑放行——尤其是 body 部分，AI 描述的是“做了什么”，你需要补充“为什么”
  • 若改动涉及多个目的，告诉 AI“拆成 N 个 commit”，它会分批暂存和提交

2.3 Commit 纪律​

AI 能快速生成大量代码，但这不是“一个 commit 提交所有改动”的理由。

  • 每个 commit 只做一件事：AI 改了 5 个文件，但如果涉及 3 个不同目的，就应该拆成 3 个 commit
  • 审查 AI 起草的 message：AI 倾向于描述“做了什么”，好的 message 应该解释“为什么”，提交前确认
  • WIP commit 不进 PR：WIP（Work In Progress，进行中）是开发过程中随手保存进度的临时 commit，message 通常是 wip、tmp、test 等无意义内容。开 PR 前用 git rebase -i 把这些临时 commit 合并或重写成有意义的提交，不要把“草稿”带入正式记录
  • 不提交生成物：AI 生成的调试代码、临时日志、注释掉的旧代码，清理后再提交

3. Pull Request 规范​

3.1 PR 大小​

一个 PR 解决一个问题，目标是 Reviewer 能在 15 分钟内理解并完成 Review。

指标建议范围
改动文件数< 20 个
新增/删除行数< 400 行
涉及功能点1 个

AI 生成代码速度快，PR 容易膨胀。如果发现 PR 超出上述范围，考虑拆分。

3.2 PR 描述模板​


---

## 背景

<!-- 为什么要做这个改动？解决了什么问题？ -->

---

## 改动内容

<!-- 做了什么，不需要逐行解释，说清楚思路即可 -->

---

## 测试方式

<!-- 如何验证改动是正确的？ -->

---

## 注意事项

<!-- Reviewer 需要特别关注的地方，或已知的 trade-off -->

3.3 AI 生成代码的 PR 特别要求​

  • 在描述中注明哪些部分是 AI 辅助生成的
  • AI 生成的逻辑（尤其是业务逻辑、权限判断、金额计算）必须逐行 Review，不能因为“AI 写的应该没问题”而跳过
  • 对 AI 生成的测试用例，验证其确实覆盖了边界情况，而非只是看起来像测试

3.4 GitHub Projects 与 PR 关联​

RentHub 使用 GitHub 自带的 Projects（组织或仓库下的 Project，表格 / 看板视图）追踪需求、Bug 与任务，而不是完全依赖口头同步或外部表格。

基本要求：

  • 每条纳入迭代的工作应有 Project 中的对应条目（通常与某个 Issue 或任务描述对应）。
  • 打开 Pull Request 时，必须在 GitHub Projects 界面把该 PR 关联（link）到对应条目，以便在 Project 的 「Linked pull requests」（或等价列）中可见代码改动与需求的对应关系；合并后也能从看板追溯「哪条需求由哪次 PR 完成」。
  • 若 PR 仅对应已有 Issue，可在 PR 描述中用 Fixes #123 / Closes #123 等关键字建立关闭关系，并仍应在 Project 中确认该 Issue 所在行已挂上本 PR（以团队 Project 字段为准）。

下图为表格视图示例：按优先级（P0 / P1 / P2）分组，列中包含标题、状态（如未开始 / 正在进行 / 大功告成）、类型（Bug / Task / Feature）、标签、负责人、关联的 Pull Request、规模估算、开始结束时间等。具体列名与视图以组织内实际 Project 为准。

GitHub Project 表格视图示例：租汇平台开发看板，含优先级分组与 Linked pull requests 列

实践提示： 开 PR 前先在 Project 中找到自己的任务行，合并后把状态拖到「完成」或团队约定状态；Review 时 Reviewer 也可对照 Project 上的类型与优先级判断是否需额外关注（如 P0 Bug）。

4. Code Review​

4.1 Reviewer 职责​

Review 的目的是提升代码质量与团队共识，不是找茬。

关注顺序：

  1. 逻辑正确性：功能是否符合需求，边界和异常是否处理
  2. 安全性：权限校验、输入验证、敏感数据处理
  3. 可维护性：命名是否清晰、逻辑是否可读、是否重复造轮子
  4. 性能：明显的性能问题（N+1 查询、大循环等），不要过早优化
  5. 风格：格式问题交给 linter，不在 Review 里讨论

4.2 使用 AI 辅助 Review​

Cursor 提供 Agent Review 功能（Source Control → Agent Review），可以作为人工 Review 的前置补充，不能替代：

  • AI Review 适合发现：明显逻辑错误、未处理的异常、潜在的类型问题
  • AI Review 不擅长：业务上下文的正确性、团队约定的合规性、架构层面的问题

流程建议：提交 PR 前先跑一次 AI Review，把低级问题解决掉，再请人工 Reviewer。

4.3 Review 反馈规范​

使用前缀标注反馈的严重程度：

前缀含义
[blocking]必须修改才能合并
[suggestion]建议修改，作者决定
[question]有疑问，需要解释
[nit]细节/风格，可忽略

5. AI 开发场景的特殊处理​

5.1 大规模 AI 重构​

AI 能快速做大范围重构（重命名、移动文件、统一写法），这类改动有几个注意点：

  • 单独一个 PR，不和功能改动混在一起
  • PR 描述中说明重构的动机和范围
  • 确保测试在重构前后都通过
  • Reviewer 重点验证“行为是否一致”，而非逐行读新代码

5.2 并行 Subagent 产生的冲突​

多个 AI Agent 并行工作时，容易产生冲突。预防措施：

  • 每个 Agent 分配到不同的文件范围或模块，减少交叉改动
  • 使用 Cursor 的 Worktree 功能让 Agent 在独立分支工作
  • Merge 前先 rebase 到最新 dev，解决冲突后再开 PR

5.3 不应提交的 AI 产物​

类型处理方式
AI 生成的临时调试代码删除后提交
过度注释（逐行解释代码做什么）删除，只保留解释“为什么”的注释
被注释掉的旧代码删除，git 有历史记录
未使用的 import / 变量清理后提交
生成的 mock 数据文件加入 .gitignore 或删除

6. 常用 Git 操作速查​

分支切换、rebase、reset、log 等命令与工作区概念见 Git 基础入门。

7. 总结：AI 时代 Git 协作的核心变化​

传统做法AI 时代调整
commit 粒度由人工速度自然控制需要主动拆分 AI 批量生成的改动
PR 大小自然受限需要有意识控制 PR 范围
Review 重点在逻辑增加对 AI 生成逻辑的“可信度验证”
commit message 反映人的思考不能直接用 AI 生成的 message，需人工审查
冲突较少多 Agent 并行时需要提前规划文件范围

8. 延伸阅读​