AGENTS.md 团队 Git 协作规则模板落地版

1. 文档目标

这份文档解决的是"规则落不了地"的问题：

团队知道要规范 Git 使用，但没有统一模板
知道要写 AGENTS.md，但不知道该写多细
知道要约束 Codex，但不知道如何把 Git 协作规则嵌进去
每个人都按自己的习惯分支、提交和回滚，团队一致性很差

读完后，你应该能够：

理解为什么 Git 协作规则值得写进 AGENTS.md
拿到一份可直接使用的 AGENTS.md Git 协作模板
按项目类型做二次调整
把 commit、分支、回滚、验证规则固化成团队默认习惯

2. 为什么 Git 协作规则要写进 AGENTS.md

很多团队会单独写一份 Git 规范，但在 Codex 场景下，只写在 Wiki 里往往不够。

原因是：

Codex 真正执行任务时，需要在上下文里明确知道团队怎么用 Git
团队成员每次口头补充 Git 要求，成本很高
没有项目内规则文件时，AI 很容易回到泛化习惯

所以，把 Git 协作规则写进 AGENTS.md 的价值是：

让 Codex 每次都基于同一套规则做事
让团队对"分支、提交、回滚"的默认认知保持一致
让规则靠近代码仓库，而不是漂浮在外部文档中

3. 一份好的 AGENTS.md Git 协作规则应包含什么

建议至少包含下面几类内容：

分支使用原则
commit 粒度原则
commit message 规范
高风险改动前的快照要求
合并前验证要求
回滚决策原则
禁止事项

4. 推荐的文档结构

下面是一种非常适合团队使用的结构：
AGENTS.md
项目与模块说明
AI 工作方式
Git 协作规则
分支规则
commit 规则
合并前检查
回滚策略
禁止事项

5. 可直接复制的 AGENTS.md Git 协作规则模板

下面是一份可以直接复制到仓库里的模板，你可以按团队实际情况替换细节。

md 复制代码

# AGENTS.md

## 1. 项目说明

- 本项目为团队协作项目，所有 AI 辅助开发行为必须遵守统一的 Git 协作规则。
- AI 在执行任务时，应优先遵循"先分析、再小步修改、再验证、再提交"的工作方式。

## 2. AI 工作原则

- 先理解需求和项目上下文，再开始修改代码。
- 优先最小改动，不做无关重构。
- 复杂任务先拆分，再逐步推进。
- 高风险任务必须先说明影响范围和验证方式。
- 修改后必须给出验证建议。

## 3. 分支使用规则

- 一个需求、一个高风险修复、一个重构任务，尽量使用一个独立分支。
- 不要在同一个工作分支中混入多个不相关任务。
- 高不确定性尝试、实验性修改、重构探索，建议使用独立实验分支。
- 紧急修复问题应优先使用独立修复分支，避免污染正常需求分支。

## 4. commit 规则

- 一个 commit 应尽量只对应一个清晰的阶段目标。
- commit 前应完成基本局部验证，不要提交明显不稳定的中间状态。
- 高风险改动前应优先保留基线快照。
- 每轮稳定的小步迭代结果，应考虑形成阶段性 commit。
- 不要把无关修改混入当前 commit。

## 5. commit message 规范

- 推荐格式：`类型: 本轮目标`
- 常用类型：`feat`、`fix`、`refactor`、`test`、`docs`、`chore`
- commit 信息应明确说明本轮做了什么，不要使用模糊描述。

### 推荐示例

- `feat: 打通 customerLevel 后端字段流转`
- `fix: 修复订单分页手机号筛选失效`
- `refactor: 抽离订单金额计算公共方法`
- `test: 补充订单分页筛选回归验证`
- `chore: 保留会员字段扩展开发前基线快照`

## 6. 合并前检查

- 合并前必须确认当前分支目标是否完成。
- 合并前必须完成关键功能验证。
- 合并前必须检查是否混入无关改动。
- 合并前必须检查 commit 粒度是否清晰，是否适合 review。
- 多任务并行场景下，合并前必须做冲突检查和统一收口。

## 7. 回滚策略

- 如果问题集中在某个 commit，优先考虑 commit 级回滚。
- 如果整个分支方案方向错误，优先考虑分支级回滚。
- 如果线上稳定性已受影响，应优先恢复稳定，再分析根因。
- 回滚后必须补回归验证，不得只回滚不验证。

## 8. 高风险场景特别规则

- 涉及数据库结构、事务边界、权限控制、支付逻辑、公共基础组件时：
  - 必须先说明影响范围
  - 必须先保留基线快照
  - 必须优先最小改动
  - 必须说明验证步骤和回滚思路

## 9. 禁止事项

- 不要把多个不相关任务混在一个分支中。
- 不要把多个无关修改混在一个 commit 中。
- 不要在未验证前将明显不稳定状态作为正式提交。
- 不要在高风险任务中跳过基线快照。
- 不要在回滚后跳过回归验证。

## 10. AI 输出要求

- AI 在建议修改方案时，应同时给出：
  - 当前任务是否建议独立分支
  - 当前轮是否适合形成单独 commit
  - 若出问题，优先回滚 commit 还是分支
  - 当前轮应做哪些验证

6. 这份模板每一段为什么要写

下面解释一下模板里的几个关键部分。

6.1 `分支使用规则`

作用：

防止多个任务混在一起
让回退和 review 更清楚

6.2 `commit 规则`

作用：

明确"什么时候该提交"
限制提交粒度失控

6.3 `合并前检查`

作用：

防止还没稳定的内容进入共享分支

6.4 `回滚策略`

作用：

让团队提前形成统一判断方式

6.5 `禁止事项`

作用：

直接把最容易踩坑的行为写死

7. 如何按团队类型做二次调整

不是每个团队都需要完全一样的规则，可以按场景微调。

7.1 小团队 / 创业团队

建议：

规则写短，但写硬
重点保留分支隔离、commit 粒度、回滚验证

7.2 中大型研发团队

建议：

加入更清晰的分支类型说明
加入合并前检查清单
加入高风险场景特别规则

7.3 Java / Spring Boot 后端团队

建议重点补充：

SQL 改动前先保留基线快照
事务和权限改动必须写验证与回滚思路
Mapper / XML 改动后要重点检查筛选、分页和回归影响

7.4 前后端联动团队

建议重点补充：

前后端联动任务优先独立分支
后端接口变更、前端展示变更、联调文档应有清晰阶段提交

8. Java / Spring Boot 团队落地示例

下面是一份更贴近 Java / Spring Boot 项目的 Git 协作规则片段。

md 复制代码

## Git 协作补充规则（Java / Spring Boot）

- 涉及 `Controller -> Service -> Mapper -> XML` 链路改动时，应优先按层次分阶段提交。
- 涉及 SQL 动态条件、分页逻辑、事务边界改动时，必须先保留基线快照。
- 涉及接口字段扩展时，建议至少拆成：
  - 对象与接口层
  - Service 逻辑层
  - Mapper / SQL 层
  - 测试与联调说明
- 每个阶段完成后，应进行局部验证，再形成 commit。
- 如果问题仅集中在 SQL 或事务修复方案，优先采用 commit 级回滚。

9. 团队接入流程建议

推荐按下面的步骤落地：

先产出 AGENTS.md 草案
团队评审 Git 协作规则
按项目特点补充细节
正式入库
在真实需求中试运行
复盘并更新模板

10. 实战实例：会员字段扩展需求

场景

团队要给会员资料管理增加 customerLevel 字段。

按模板落地后的执行方式

单独功能分支推进
先保留开发前基线快照
后端、SQL、前端、测试分阶段提交
合并前统一验证

可能的提交节奏

text 复制代码

chore: customerLevel 需求开发前基线快照
feat: 打通 customerLevel 后端对象与接口链路
feat: 支持 customerLevel Service 保存与查询逻辑
feat: 增加 customerLevel SQL 筛选条件
feat: 增加 customerLevel 前端展示
test: 补充 customerLevel 联调与回归清单

这说明什么

这说明 AGENTS.md 不是只写理念，而是能直接影响真实任务怎么推进。

11. 实战实例：复杂 Bug 修复

场景

订单提交流程偶发失败，涉及事务、日志和 SQL 检查。

按模板落地后的执行方式

单独 bug 修复分支
先保留基线快照
修复方案与回归验证分开提交
如果修复方案错误，优先回滚对应 commit

可能的提交节奏

text 复制代码

chore: 订单提交流程修复前基线快照
fix: 修复订单提交事务边界问题
fix: 补充订单提交异常日志
test: 补充订单提交回归验证

12. 常见误区

12.1 误区一：AGENTS.md 只写抽象原则

问题：

不能指导真实提交和分支行为

12.2 误区二：规则太长但没有重点

问题：

团队不愿意执行

12.3 误区三：模板写好了但不更新

问题：

规则和真实实践逐渐脱节

12.4 误区四：只要求 AI 遵守，不要求团队成员遵守

问题：

人和 AI 的协作方式不一致

13. 团队规则建议

如果你要把这份模板真正用起来，建议：

每季度回顾一次规则是否还贴合实际
把优秀 commit 示例补进模板
把高风险回滚案例补进模板
把团队真实踩坑记录沉淀成补充规则

14. 一句话总结

AGENTS.md 里的 Git 协作规则，不该只是"建议"，而应该是一套能直接指导分支、提交、合并和回滚行为的团队默认动作。

15. 快速上手清单

先复制模板到项目里
按项目类型补充细节
团队评审后正式入库
在真实需求中试运行
用真实案例持续迭代模板

AGENTS.md 团队 Git 协作规则模板落地版

1. 文档目标

2. 为什么 Git 协作规则要写进 AGENTS.md

3. 一份好的 AGENTS.md Git 协作规则应包含什么

4. 推荐的文档结构

5. 可直接复制的 AGENTS.md Git 协作规则模板

6. 这份模板每一段为什么要写

6.1 分支使用规则

6.2 commit 规则

6.3 合并前检查

6.4 回滚策略

6.5 禁止事项

7. 如何按团队类型做二次调整

7.1 小团队 / 创业团队

7.2 中大型研发团队

7.3 Java / Spring Boot 后端团队

7.4 前后端联动团队

8. Java / Spring Boot 团队落地示例

9. 团队接入流程建议

10. 实战实例：会员字段扩展需求

场景

按模板落地后的执行方式

可能的提交节奏

这说明什么

11. 实战实例：复杂 Bug 修复

场景

按模板落地后的执行方式

可能的提交节奏

12. 常见误区

12.1 误区一：AGENTS.md 只写抽象原则

12.2 误区二：规则太长但没有重点

12.3 误区三：模板写好了但不更新

12.4 误区四：只要求 AI 遵守，不要求团队成员遵守

13. 团队规则建议

14. 一句话总结

15. 快速上手清单

6.1 `分支使用规则`

6.2 `commit 规则`

6.3 `合并前检查`

6.4 `回滚策略`

6.5 `禁止事项`