多 Agent + Git 协同开发流程设计 (v2.2)

沉淀日期：2026-05-27 最近更新：2026-05-28（基于 v2.1 分析，8 项改进集成）版本变更：v2.1 → v2.2（CRRC 项目适配、交付验证改革、编译自检、自动化测试、回溯流程、分层抽查、日志度量）

一、核心理念

每个需求/任务以文档为启动点，初始化为 Git 仓库。多个不同职能的 Agent 团队按阶段接力开发，通过 Git 分支隔离工作，里程碑合并汇总成果。贯穿全流程的业务领导角色负责审批和管控。

设计原则

少即是多：只保留真正必要的流程，避免为流程而流程
职责清晰：每个角色只做自己擅长的事
可执行：每个流程步骤都必须有明确的执行者和可操作的方法
闭环验证：每个交付物都必须有可验证的检查方式

v2.1 核心改进（相比 v1.0）

改进项	解决的问题
业务领导提炼上下文	子Agent无状态导致上下游信息断裂
并行开发合并策略	多团队并行时文件冲突无预案
返工升级路径	返工死循环无兜底方案
代码质量抽查	编译通过≠质量合格
环境就绪检查	M3→M4 环境问题导致阻塞
交付物可验证	防止交付物检查流于形式
测试重点指定	防止测试阶段缺乏策略指导

v2.2 核心改进（相比 v2.1）

改进项	解决的问题
CRRC 项目适配（附录 C）	流程与实际 Gradle 多模块项目不匹配
覆盖度检查替代行数校验	行数校验流于形式，无法反映交付质量
对上团队的问题通道	下游发现问题时无快速反馈机制
Team C 编译自检门控	编译验证依赖业务领导手动执行
Team D 自动化测试集成	测试交付物缺少可执行测试代码
跨阶段回溯流程	M3/M4 发现上游问题时无标准化处理流程
风险导向分层抽查	单一文件抽查覆盖率过低
项目日志过程度量	缺少阶段耗时、失败原因分类等改进数据

二、组织架构

业务领导 (Business Owner)
  │  贯穿全流程，负责：
  │  - 定义项目目标、验收标准
  │  - 审批每个里程碑是否达标
  │  - Go / No-Go 决策
  │  - 返工决策和方向调整
  │  - 最终验收
  │  - 维护项目生命周期日志
  │  - 派单时提炼关键上下文传递给下游团队
  │
  ├── Team A  需求分析师
  ├── Team B  架构师
  ├── Team C  开发者
  └── Team D  测试工程师

角色分工

角色	模型	职责
业务领导	GLM-5.1	全局管控、审批、决策、派单、上下文传递。不参与具体执行
需求分析师	MiniMax M2.7	产出需求规格、用例、约束条件
架构师	MiniMax M2.7	产出架构设计、接口定义、技术选型
开发者	MiniMax M2.7	按架构编码，分模块分阶段提交
测试工程师	MiniMax M2.7	基于业务领导指定的测试重点，执行测试，提交报告

上下文传递机制

原则：由业务领导在派单时提炼关键上下文，同时要求当前团队在 DELIVERY-MANIFEST.md 中填写"给下游团队的关键信息"。

双重保障：

当前团队填写：在 DELIVERY-MANIFEST.md 中填写"给下游团队的关键信息"
- 他们最清楚自己的决策和约束
- 业务领导审查时可以补充或修正
业务领导提炼：派单时将关键信息嵌入 prompt
- 来源：DELIVERY-MANIFEST.md 中的"给下游团队的关键信息" + 业务领导自己的判断
- 不是简单复制，而是提炼和筛选

示例（业务领导派单给Team B时的prompt片段）：

## 上游关键信息

### Team A 的关键决策
- 用户认证采用JWT方案，原因是系统需要支持移动端
- 权限控制采用RBAC模型，每个用户绑定一个角色

### 隐含约束
- 数据库必须使用MySQL 5.7（客户环境限制）
- 所有接口必须支持租户隔离（tenant_id字段）

### 特别注意
- 需求中的"报表导出"功能优先级较低，可简化设计

三、整体流程

[业务领导] 制定项目目标 + 验收标准
     │
     ▼ git init main
     │  1. 创建 .gitignore（排除 target/、*.class、.idea/、*.iml、.DS_Store、*.log）
     │  2. 提交 .gitignore 到 main
     │  3. 提交 docs/charter.md、docs/acceptance-criteria.md
     │
[业务领导] 派单 → Team A（prompt中明确项目目标和验收标准）
     │
┌─ Team A 需求分析 ──→ branch: phase/01-requirement
│    输出: spec.md, use-cases.md, constraints.md, DELIVERY-MANIFEST.md
│         │
│         ▼ merge request → main
│         │
[业务领导] 审查 DELIVERY-MANIFEST.md → Go/No-Go
     │  （含对上团队问题处理）
[业务领导] 派单 → Team B（prompt中嵌入 Team A 的关键信息）
     │
┌─ Team B 架构设计 ──→ branch: phase/02-architecture
│    输出: design.md, api-definition.md, tech-stack.md, DELIVERY-MANIFEST.md
│         │
│         ▼ merge request → main
│         │
[业务领导] 审查 DELIVERY-MANIFEST.md → Go/No-Go
     │  （含对上团队问题处理）
[业务领导] 派单 → Team C（prompt中嵌入 Team B 的关键信息）
     │
┌─ Team C 编码实现 ──→ branch: phase/03-coding
│    输出: 代码 + DELIVERY-MANIFEST.md
│         │
│         ▼ 编译自检（Team C 执行）
│         │  cd {affected_module} && ./gradlew compileJava
│         │  通过 → 自检结果写入 DELIVERY-MANIFEST.md → 提交 merge request
│         │  失败 → 修复后重新自检
│         │
│         ▼ merge request → main
│         │
[业务领导] 风险导向分层代码抽查 + 审查 DELIVERY-MANIFEST.md → Go/No-Go
     │  （含对上团队问题处理）
     ▼ 环境就绪检查（./gradlew bootRun + 冒烟，在具体模块目录内执行）
     │
[业务领导] 派单 → Team D（prompt中嵌入测试重点 + Team C 的关键信息）
     │
┌─ Team D 测试验收 ──→ branch: phase/04-testing
│    输出:
│      - test-cases.md          # 测试用例说明
│      - test-report.md         # 测试执行报告
│      - bug-list.md            # Bug 清单
│      - DELIVERY-MANIFEST.md   # 交付清单
│      - {module}/src/test/java/  # 可执行的自动化测试代码
│    执行:
│      1. 手动验证核心接口（冒烟）
│      2. 编写自动化测试（JUnit 4 + Spring Boot Test）
│      3. ./gradlew test 确认全部通过
│      4. 结果写入 test-report.md
│         │
│         ▼ merge request → main
│         │
[业务领导] 审查 DELIVERY-MANIFEST.md → 最终验收
     │  （含对上团队问题处理）

附录A：并行开发合并策略

当 Team C 拆分为 Backend 和 Frontend 并行开发时：

1. 文件所有权划分（业务领导派单时明确）

Team C-Backend 拥有：
  - src/main/java/**（所有 Java 代码）
  - src/main/resources/mapper/**（MyBatis XML）
  - schema.sql

Team C-Frontend 拥有：
  - src/main/resources/templates/**（HTML 模板）
  - src/main/resources/static/**（CSS/JS/图片）

共享文件（由业务领导预先定义模板）：
  - src/main/resources/application.properties
    → Backend 负责：server.port、数据库配置、MyBatis 配置
    → Frontend 负责：静态资源路径、模板引擎配置
    → 双方只填充各自段落，不得修改对方段落

禁止修改的文件（任何一方都不允许修改）：
  - pom.xml（由业务领导统一管理）
  - .gitignore（由业务领导统一管理）
  - 已合并到 main 的其他团队交付物

2. 合并流程

1. Backend 和 Frontend 各自完成
2. 业务领导对比两方的 DELIVERY-MANIFEST.md 中的修改文件清单
3. 检查清单：
   a. 是否有重叠文件 → 手动解决冲突
   b. 是否有修改"禁止修改"的文件 → 打回
   c. 是否有修改未明确归属的文件 → 业务领导判定归属
4. 无冲突 → 统一 commit

3. DELIVERY-MANIFEST.md 补充字段

## 修改文件清单（Team C 必填）

| 序号 | 文件路径 | 操作类型 | 说明 |
|------|----------|----------|------|
| 1 | src/main/java/.../UserController.java | 新增 | 用户模块 Controller |
| 2 | src/main/resources/application.properties | 修改 | 添加数据库配置（仅 DB 段落） |

附录B：环境就绪检查清单

M3→M4 派单前，业务领导必须完成以下检查：

序号	检查项	状态
1	`./gradlew bootRun` 启动无报错（在具体模块目录内执行）	□
2	启动日志无 ERROR	□
3	核心 API 冒烟测试通过（≥2个）	□

通过：所有检查项均为 ✓
不通过：记录失败项，先修复环境问题，再派单 Team D

检查结果记录到 docs/environment-checklist.md。

四、Git 分支命名规范

main                          # 主分支，每个里程碑合并
phase/01-requirement          # 各阶段工作分支
phase/02-architecture
phase/03-coding
phase/04-testing
rework/01-requirement         # 返工分支
rework/02-architecture
rework/03-coding
backport/arch-api-fix          # 回溯分支：修复架构接口定义
backport/req-clarification     # 回溯分支：澄清需求歧义

Commit Message 规范

[milestone-N] 简述内容
例: [milestone-1] 完成用户模块需求规格

[rework-N] 简述返工内容
例: [rework-1] 补充用户权限约束条件

[backport-N] 简述回溯修改内容
例: [backport-1] 修正 User API 返回值定义，增加 errorCode 字段

五、仓库目录结构

repo/
├── docs/
│   ├── charter.md                  # 业务领导：项目章程、目标、验收标准
│   ├── acceptance-criteria.md      # 业务领导：每个里程碑的通过条件
│   ├── project-log.md              # 业务领导：项目生命周期日志
│   ├── environment-checklist.md    # 业务领导：环境就绪检查（M3→M4）
│   └── reviews/
│       ├── milestone-1-review.md   # 业务领导评审记录
│       ├── milestone-2-review.md
│       └── ...
│
├── deliveries/                     # ===== 各团队交付目录 =====
│   │
│   ├── team-a-requirement/         # Team A 独属目录
│   │   ├── DELIVERY-MANIFEST.md    # 交付清单
│   │   ├── spec.md                 # 需求规格
│   │   ├── use-cases.md            # 用例文档
│   │   └── constraints.md          # 约束条件
│   │
│   ├── team-b-architecture/        # Team B 独属目录
│   │   ├── DELIVERY-MANIFEST.md    # 交付清单
│   │   ├── design.md               # 架构设计文档
│   │   ├── api-definition.md       # 接口定义
│   │   └── tech-stack.md           # 技术选型说明
│   │
│   ├── team-c-coding/              # Team C 独属目录
│   │   ├── DELIVERY-MANIFEST.md    # 交付清单
│   │   └── impl-notes.md           # 实现说明（可选）
│   │
│   └── team-d-testing/             # Team D 独属目录
│       ├── DELIVERY-MANIFEST.md    # 交付清单
│       ├── test-cases.md           # 测试用例
│       ├── test-report.md          # 测试报告
│       └── bug-list.md             # Bug 清单
│
├── com.sayu.service-xxx/   # Team C 代码产物（各业务模块）
│   ├── src/main/java/...              #   业务代码
│   ├── src/main/resources/...         #   配置 + MyBatis XML 映射
│   └── src/test/java/...              #   Team D 自动化测试代码
├── com.sayu.service-common/ # 共享库模块（只读，修改需返工流程）
├── tests/                              # Team D 测试文档目录（deliveries 内的子目录备选）
│
└── rework/                             # 返工请求
    └── rework-01.md                # 返工请求文档

目录归属规则

每个团队只能在自己的 deliveries/team-X-xxx/ 目录下提交交付产物
跨目录修改需要通过返工流程
各业务模块 com.sayu.service-*/src/main/java/ 由 Team C 产出
各业务模块 com.sayu.service-*/src/test/java/ 由 Team D 产出
com.sayu.service-common/ 是共享库模块，修改需通过返工流程，且修改后需优先编译验证

六、交付清单机制 (DELIVERY-MANIFEST.md)

每个团队在提交最终交付前，必须在自己的交付目录下维护一份 DELIVERY-MANIFEST.md。

清单模板

# 交付清单 — [团队名称]

## 里程碑信息
- 阶段: [需求分析 / 架构设计 / 编码实现 / 测试验收]
- 里程碑编号: milestone-N
- 提交时间: YYYY-MM-DD HH:MM
- 负责团队: Team X

## 交付产物

| 序号 | 文件路径 | 说明 | 覆盖度检查 | 核心内容摘要 |
|------|----------|------|------------|--------------|
| 1 | deliveries/team-a-requirement/spec.md | 需求规格文档 | 模块数: 3/3, 功能点: 12/12 | 包含用户模块、订单模块、报表模块 |
| 2 | deliveries/team-a-requirement/use-cases.md | 用例文档 | 用例数: 20/20, 覆盖需求: 全部 | 覆盖所有功能点 |

## 修改文件清单（Team C 必填，其他团队可选）

| 序号 | 文件路径 | 操作类型 | 说明 |
|------|----------|----------|------|
| 1 | src/main/java/.../UserController.java | 新增 | 用户模块 Controller |

## 交付说明
（简要说明本次交付的核心内容、关键决策）

## 给下游团队的关键信息（必填）
- 关键决策：（本次交付中最重要的技术/业务决策）
- 隐含约束：（下游必须遵守的限制）
- 特别注意：（需要提醒下游的事项）

## 对上团队的问题（可选）
（当前团队在工作中发现的、需要上游团队澄清或修正的问题。
  业务领导审查时应当关注这些问题，必要时触发跨阶段回溯。）
- 问题：（描述问题，引用上游交付物中的具体章节/行号）
- 期望：（期望上游如何修正）
- 影响范围：（问题影响哪些下游工作）

## 待确认事项
（如有需要业务领导确认的问题，列在此处）

覆盖度检查字段说明

每个团队的覆盖度检查含义不同：

团队	覆盖度定义	示例
Team A	spec.md 模块数 / charter.md 总模块数；use-cases.md 功能点 / charter.md 总功能点	模块数: 3/3
Team B	api-definition.md 接口数 / spec.md 功能点数；DDL 表数 / 需求实体数	接口数: 8/8
Team C	实现接口数 / api-definition.md 接口数；编译自检通过的模块数	接口实现: 8/8
Team D	测试用例数 / use-cases.md 用例数；核心接口测试 / 领导指定核心接口	用例覆盖: 20/20

为什么不用行数？ 行数不反映质量。500 行可能是模板填充或注释堆砌，50 行可能是高度精炼。"覆盖度检查"让审查者一眼看出交付物是否完整覆盖了上游定义的预期范围，且覆盖度描述本身迫使团队核算交付完整性。

业务领导查验流程

1. 团队提交 merge request
2. 业务领导读取 DELIVERY-MANIFEST.md
3. 按清单逐项查验：
   a. 用 Glob 工具确认文件存在
   b. 检查清单中的"覆盖度检查"和"核心内容摘要"是否合理
   c. 用 Read 工具抽查 1 个文件，核对内容与清单描述是否一致
   d. 检查"给下游团队的关键信息"是否完整
   e. 检查"对上团队的问题"字段 —— 如有问题，优先处理：
      - 可立即澄清的：业务领导直接回复
      - 需上游修改的：触发跨阶段回溯流程（见第九章回溯部分）
4. M3 阶段：执行风险导向分层代码抽查（见第八章）
5. 输出评审文档 docs/reviews/milestone-N-review.md
6. 做出决策：
   - Go → merge to main，记录日志
   - No-Go → 打回，附具体修改意见，记录日志

Prompt 模板嵌入（强制执行）

为确保子 Agent 严格按模板输出交付清单，在 delegate_task 的 prompt 末尾必须嵌入以下指令：

你必须在交付目录下创建 DELIVERY-MANIFEST.md，严格按以下格式：

# 交付清单 — [团队名称]

## 里程碑信息
- 阶段: [需求分析 / 架构设计 / 编码实现 / 测试验收]
- 里程碑编号: milestone-N
- 提交时间: YYYY-MM-DD HH:MM
- 负责团队: Team X

## 交付产物

| 序号 | 文件路径 | 说明 | 覆盖度检查 | 核心内容摘要 |
|------|----------|------|------------|--------------|
| 1    | ...      | ...  | ...        | ...          |

## 修改文件清单（Team C 必填）
| 序号 | 文件路径 | 操作类型 | 说明 |
|------|----------|----------|------|
| 1    | ...      | 新增/修改/删除 | ... |

## 交付说明
（核心内容、关键决策）

## 给下游团队的关键信息（必填）
- 关键决策：（本次交付中最重要的技术/业务决策）
- 隐含约束：（下游必须遵守的限制）
- 特别注意：（需要提醒下游的事项）

## 对上团队的问题（可选）
（列出需要上游团队澄清的问题，包括问题描述、期望、影响范围）

## 待确认事项
（需要业务领导确认的问题）

⚠️ 不按此格式输出视为交付不完整。
⚠️ "给下游团队的关键信息"缺失视为交付不完整。
⚠️ 发现上游交付物有歧义或矛盾时，必须在"对上团队的问题"中记录，不得保持沉默。

七、项目生命周期日志 (project-log.md)

业务领导维护一份贯穿项目全生命周期的日志文档。

日志模板

# 项目生命周期日志

## 项目基本信息
- 项目名称: XXX
- 启动时间: YYYY-MM-DD
- 项目目标: （一句话描述）
- 当前状态: [进行中 / 已交付 / 已暂停]

---

## 日志记录

### [YYYY-MM-DD HH:MM] 项目启动
- 动作: 初始化项目仓库，定义项目章程
- 产出: docs/charter.md, docs/acceptance-criteria.md

### [YYYY-MM-DD HH:MM] Milestone 1 — 需求分析派单
- 动作: 派单给 Team A
- 预期交付: 需求规格、用例、约束条件

### [YYYY-MM-DD HH:MM] Milestone 1 — 审查
- 审查结果: [通过 / 不通过]
- 意见: （评审意见）
- 决策: [Go / No-Go]
- 提取的关键信息: （将传递给 Team B 的内容）

### [YYYY-MM-DD HH:MM] 返工（如有）
- 原因: （具体问题）
- 返工次数: 第 X 次
- 处理: （修改意见）

...（后续里程碑同理）

### [YYYY-MM-DD HH:MM] 项目交付
- 最终状态: 所有里程碑通过
- 交付版本: tag v1.0
- 统计: 返工 X 次，一次通过率 X%，总历时 Xh Xm

过程改进数据

以下数据由业务领导在项目执行过程中持续更新，用于评估流程效果和指导后续迭代改进。

阶段耗时统计

阶段	派出时间	交付时间	总耗时	说明
M1 需求分析	YYYY-MM-DD HH:MM	YYYY-MM-DD HH:MM	Xh Xm	-
M2 架构设计	YYYY-MM-DD HH:MM	YYYY-MM-DD HH:MM	Xh Xm	-
M3 编码实现	YYYY-MM-DD HH:MM	YYYY-MM-DD HH:MM	Xh Xm	含返工/回溯
M4 测试验收	YYYY-MM-DD HH:MM	YYYY-MM-DD HH:MM	Xh Xm	含返工/回溯

返工统计

阶段	返工次数	团队	最常见原因
M1 需求分析	X	Team A	需求遗漏 / 约束不完整 / ...
M2 架构设计	X	Team B	接口定义不覆盖需求 / 技术选型不合理 / ...
M3 编码实现	X	Team C	编译错误 / 与接口定义不一致 / ...
M4 测试验收	X	Team D	用例遗漏 / 测试未通过 / ...

一次通过率

阶段	一次通过率
M1 需求分析	X%
M2 架构设计	X%
M3 编码实现	X%
M4 测试验收	X%
项目整体	X%

失败原因分类（Top N）

排名	失败原因	出现次数	涉及阶段
1	接口定义与实际实现不一致	X	M2→M3
2	测试用例未覆盖核心接口	X	M4
3	数据库 Schema 遗漏字段	X	M2
...	...	...	...

说明：阶段耗时由业务领导在日志中自动计算（派出时间与审查时间的差值）。返工次数和一次通过率在每次审查/返工时累计。失败原因分类在每次 No-Go 决策时记录。这些数据用于下一轮迭代的过程改进，不在当前交付中强制要求。

日志维护规则

每个关键动作（派单、审查、返工、决策、交付）都必须追加一条日志
日志按时间顺序排列，不可删除或修改历史记录
业务领导在每次决策后立即更新日志

八、里程碑与审批机制

每个里程碑结束时，业务领导执行审批：

1. 读取该阶段团队的 DELIVERY-MANIFEST.md
2. 按清单逐项查验：
   a. 用 Glob 工具确认文件存在
   b. 检查清单中的"覆盖度检查"和"核心内容摘要"是否合理
   c. 用 Read 工具抽查 1 个文件，核对内容与清单描述是否一致
   d. 对照 acceptance-criteria.md 中的通过条件
   e. 检查"对上团队的问题"字段 —— 如有问题，优先处理或触发回溯
3. 交叉验证：
   M1 评审 → 对照 charter.md 核对需求覆盖度
   M2 评审 → 对照 spec.md 核对 API 覆盖度
   M3 评审 → 对照 api-definition.md 核对实现 + 复核编译自检结果 + 风险导向分层代码抽查
   M4 评审 → 对照 use-cases.md 核对测试用例覆盖度 + 验证自动化测试通过
4. 检查"给下游团队的关键信息"是否完整
5. 输出评审文档 docs/reviews/milestone-N-review.md
6. 更新 docs/project-log.md
7. 做出决策：
   - Go → merge to main
   - No-Go → 打回，附具体修改意见

量化验收指标

里程碑	量化检查项
M1 需求	spec.md 每个功能模块有独立章节；use-cases.md 覆盖 charter.md 中每个功能点；"给下游团队的关键信息"完整
M2 架构	api-definition.md 接口数 ≥ spec.md 功能点数；DDL 每张表有字段注释；"给下游团队的关键信息"完整
M3 编码	DELIVERY-MANIFEST.md 中注明编译自检结果；业务领导复核 `./gradlew compileJava`（受影响的模块）零错误；每个 Controller 方法对应 api-definition.md 中一个接口；风险导向分层抽查通过
M4 测试	测试用例数 ≥ use-cases.md 用例数；自动化测试 `./gradlew test` 通过（新增测试 + 已有测试）；Bug 清单含复现步骤+严重等级；测试覆盖业务领导指定的重点场景；核心接口测试覆盖率 ≥ 80%

风险导向代码分层抽查（M3 阶段）

业务领导在 M3 审查时，按以下分层策略执行抽查：

分层抽样策略

根据变更文件总数决定抽样深度：

变更文件数	抽样基数	抽样策略
1-5 个	全量	100% 文件抽查
6-15 个	至少 4 个	高风险层 100% + 中风险层抽样 2 个
16-30 个	至少 6 个	高风险层 100% + 中风险层 3 个 + 低风险层 1 个
30+ 个	至少 8 个	高风险层 100% + 中风险层 4 个 + 低风险层 2 个

风险分层

第一层（高风险 — 100% 抽查）：

Controller 类（涉及用户输入）
MyBatis XML 文件（涉及 SQL，需检查 ${} 注入）
涉及权限校验的文件
涉及金额计算的业务逻辑

检查项：无硬编码密钥/密码、用户输入有校验（@Valid、参数校验注解）、SQL 全部使用 #{} 参数化（无 ${} 字符串替换）、无敏感数据硬编码、文件不超过 500 行

第二层（中风险 — 按比例抽样）：

Service/Application 类（业务逻辑）
公共工具类
切面类（Aspect）

检查项：命名符合项目规范、异常处理合理（有 try-catch 或 throws 声明）、关键路径有日志、文件不超过 500 行

第三层（低风险 — 抽样 1-2 个）：

常量/枚举类
VO/DTO 类
配置类

检查项：命名符合项目规范、无明显的拼写错误或模板残留

CRRC 专项补充

当变更文件清单中包含 MyBatis XML 文件时，必须额外执行：

MyBatis XML 专项检查（详见附录 C.4）：
- Grep 搜索 \$\{[^#] 确认无字符串替换
- 验证 namespace 与 Java 接口匹配
- 验证 resultType 引用的类存在

抽样记录

业务领导将抽查结果记录在 docs/reviews/milestone-N-review.md 中：

## 代码抽样记录
- 变更文件总数: X 个
- 抽样基数: Y 个（高风险 Z 个）
- 抽查文件列表:
  | 文件 | 风险层 | 检查结果 | 备注 |
  |------|--------|---------|------|
  | ...  | 高     | 通过    | -    |
  | ...  | 中     | 发现问题 | 见下方说明 |
- 发现的问题: （如有）
- 结论: [通过 / 需修改后重审]

Team D 测试重点指定

业务领导派单给 Team D 时，必须在 prompt 中指定测试重点：

## 测试重点（业务领导指定）

### 核心接口（必须测试）
- /api/login — 用户登录
- /api/orders — 订单创建和查询
- /api/users — 用户管理

### 重点场景
- 用户登录成功/失败
- 订单创建成功/参数校验失败
- 并发场景（可选，如时间允许）

### 已知风险
- 订单模块的并发处理未做压力测试
- 报表导出功能性能未验证

### 测试范围
- 功能测试：必须覆盖上述核心接口
- 边界测试：必须覆盖参数校验场景
- 性能测试：可选
- 安全测试：可选

Team D 自动化测试质量要求

Team D 产出的测试代码需满足以下质量要求：

通过率：./gradlew test 全部通过（不能仅因为新增测试而跳过）
独立性：每个测试方法独立运行，不依赖其他测试的执行顺序
可重复：同一测试多次运行结果一致
不修改源代码：测试代码不得修改 src/main/java/ 下的任何文件
无网络依赖：单元测试不应依赖外部服务（使用 Mock）
JUnit 4 风格：使用 @Test 注解，非 JUnit 5

注意：当前项目测试覆盖极少。Team D 的策略是"核心接口优先"——优先为业务领导指定的核心接口编写测试，再视时间补充其他场景。不必追求 100% 覆盖率。

如果产出的测试代码未通过编译，必须在"对上团队的问题"中反馈，不得跳过。

九、返工机制

设计原则

返工由业务领导主动触发
返工不是重做，是针对具体问题的定向修补
返工次数上限 2 次，第 3 次触发升级机制

返工触发方式

1. 业务领导在评审中发现交付不达标
2. 基于 main 开 rework/XX-阶段名 分支
3. 提交 rework-request.md（必须包含具体修改指令）
4. 更新 project-log.md
5. 重新 delegate_task 给原团队
6. 返工完成后重新走 merge → review 流程

返工升级路径

返工1次（原团队修改）：
  - 业务领导提出具体修改意见
  - 原团队修改
  - 业务领导重新审查
  - 通过 → 进入下一阶段
  - 不通过 → 返工2次

返工2次（业务领导介入指导）：
  - 业务领导提供精确到文件、内容的修改指令
  - 原团队按指令执行
  - 业务领导重新审查
  - 通过 → 进入下一阶段
  - 不通过 → 返工3次（升级）

返工3次（升级处理）：
  - 标记为 BLOCKED
  - 业务领导按以下决策树判断：

    ┌─ 问题是否因为任务太复杂？
    │   → 是 → 拆分任务，将大任务拆成多个小任务，分别派单
    │   → 否 ↓
    │
    ├─ 问题是否因为需求不清晰？
    │   → 是 → 重新定义需求，可能需要 Team A 返工
    │   → 否 ↓
    │
    ├─ 问题是否因为子Agent能力不足？
    │   → 是 → 业务领导提供更详细的指令（精确到代码级别），重新派单
    │   → 否 ↓
    │
    └─ 该功能是否为核心功能？
        → 是 → 标记为 BLOCKED，人工介入（如果有开发人员）
        → 否 → 降级需求，从 charter.md 中移除

  - 无论选择哪种，必须在 project-log.md 中记录决策和原因

返工请求模板

# 返工请求 — [阶段名称]

## 基本信息
- 返工编号: rework-N
- 触发时间: YYYY-MM-DD HH:MM
- 目标团队: Team X
- 返工次数: 第 X 次
- 原因类型: [质量问题 / 需求变更 / 任务复杂度]

## 问题描述
（具体描述问题，必须具体到文件、章节、内容）

## 具体修改要求
1. 修改点1：[文件路径] [具体修改内容]
2. 修改点2：[文件路径] [具体修改内容]

## 期望完成标准
（怎样算修改完成）

跨阶段回溯返工

触发条件

当 M3/M4 阶段发现的问题根源在上游阶段（M1/M2），且无法通过当前阶段的局部修补解决时，启动回溯返工：

典型场景：
1. M3 编码时发现 M2 架构设计有缺陷（接口定义不合理、技术选型不支持需求）
2. M3 编码时发现 M1 需求有歧义或遗漏
3. M4 测试时发现 M2 架构设计导致功能不可测试
4. M4 测试时发现 M1 需求定义与用户实际场景不符

回溯流程

[发现者] 在 DELIVERY-MANIFEST.md 的"对上团队的问题"中注明
     │
     ▼
[业务领导] 评估影响范围:
     │  - 问题是否影响其他并行模块？
     │  - 修复需要的工时估算（粗略）
     │  - 是否存在临时绕过方案？
     │
     ├── 影响面小 → 业务领导直接在上游文档中打补丁（inline fix）
     │   ├ 在 docs/reviews/ 中记录补丁说明
     │   └ 继续当前阶段，不中断主线
     │
     └── 影响面大 → 启动回溯返工流程:

         1. 冻结当前阶段的 merge（暂不合并到 main）
         2. 从 main（而非当前工作分支）开回溯分支:
            backport/reason-xxx-description
         3. 业务领导编写 backtrack-request.md:
            - 问题描述（精确到文件、行号）
            - 需要修改的上游文件
            - 修改要求
            - 预期对其他模块的影响
         4. 派出原上游团队（Team A 或 Team B）在回溯分支上修改
         5. 修改完成后，业务领导审查回溯分支
         6. 审查通过 → 合并回溯分支到 main → 打 tag: backtrack-v<N>
         7. 当前阶段团队 rebase 到 main（或重新从 main 开分支）
         8. 继续当前阶段工作

回溯 vs 普通返工的区别

维度	普通返工	回溯返工
触发者	业务领导在审查中发现	下游团队在工作中发现
修改对象	当前阶段的交付物	上游阶段（已合并到 main）的交付物
分支策略	从 main 开 rework/分支	从 main 开 backport/分支
merge 后	正常进入下一阶段	下游团队需 rebase
次数上限	2 次	1 次（仍不通过则进入升级流程）

回溯请求模板

# 回溯请求 — [阶段名称]

## 基本信息
- 回溯编号: backport-N
- 触发时间: YYYY-MM-DD HH:MM
- 目标团队: Team X（被回溯的上游团队）
- 发现团队: Team Y（发现问题的下游团队）
- 触发文件: （下游团队在 DELIVERY-MANIFEST 中记录问题的文件路径）

## 问题描述
（具体描述问题，引用上游交付物中的具体文件、章节、行号）

## 影响范围
- 受影响的并行模块列表
- 预计修复工时
- 是否存在临时绕过方案

## 修改要求
1. [目标文件路径] [具体修改内容]
2. [目标文件路径] [具体修改内容]

## 期望完成标准
（怎样算修改完成）

十、业务领导管控点

管控点	动作	产出文件	检查方式
项目启动	定义目标 + 验收标准	charter.md, project-log.md	-
派单	指定团队 + 提炼上下文 + 下发任务	project-log.md	每次 No-Go 决策时记录失败原因分类
Milestone 审批	查验交付清单 → Go/No-Go	reviews/milestone-N.md, project-log.md	Glob确认文件存在 + Read抽查1个文件
代码抽查（M3）	风险导向分层抽查	记录在 milestone-N-review.md	按风险分层从修改清单中选择，数量取决于变更总数
环境就绪检查	启动 + 冒烟测试	environment-checklist.md	实际执行 `./gradlew` 命令验证
返工决策	决定打回 + 具体修改指令	rework/rework-N.md, project-log.md	-
回溯返工	评估影响 → 开 backport/ 分支 → 派出上游团队 → 审查 → 通知下游 rebase	backtrack-request.md, project-log.md	检查回溯分支修改是否精准、未引入副作用
最终验收	全量审查 → 发布/打回	release tag, project-log.md	-

十一、与 Hermes 的执行映射

我 (GLM-5.1)        → 业务领导：拆任务、审批、决策、维护日志、提炼上下文、指定测试重点
delegate_task       → 派出各职能团队（子 Agent 只负责写文件，不操作 Git）
  Team A prompt     → "你是需求分析师，基于 docs/ 产出需求规格到 deliveries/team-a-requirement/
                       你必须创建 spec.md、use-cases.md、constraints.md、DELIVERY-MANIFEST.md
                       DELIVERY-MANIFEST.md 必须包含'给下游团队的关键信息'字段"
  Team B prompt     → "你是架构师，基于 main 上的需求文档设计架构到 deliveries/team-b-architecture/
                       [业务领导嵌入 Team A 的关键信息]
                       你必须创建 design.md、api-definition.md、tech-stack.md、DELIVERY-MANIFEST.md
                       DELIVERY-MANIFEST.md 必须包含'给下游团队的关键信息'字段"
  Team C prompt     → "你是开发者，基于架构文档编码到各模块 src/main/java/
                       [业务领导嵌入 Team B 的关键信息]
                       你必须在 DELIVERY-MANIFEST.md 中列出修改文件清单
                       DELIVERY-MANIFEST.md 必须包含'给下游团队的关键信息'字段
                       完成编码后，进入每个修改的模块目录执行 ./gradlew compileJava 自检
                       自检结果写入 DELIVERY-MANIFEST.md 的'交付说明'字段"
                       （可拆为 C-ModuleA + C-ModuleB 并行，按模块边界划分文件所有权）
  Team D prompt     → "你是测试工程师，基于代码产出测试:
                       - 测试文档: deliveries/team-d-testing/test-cases.md, test-report.md, bug-list.md, DELIVERY-MANIFEST.md
                       - 自动化测试: {affected_module}/src/test/java/ 目录，JUnit 4 + Spring Boot Test 风格
                       [业务领导嵌入测试重点 + Team C 的关键信息]
                       自动化测试必须可编译、可通过（./gradlew test）
                       测试用例必须覆盖业务领导指定的核心接口和重点场景
                       测试结果写入 test-report.md"
git add/commit      → 业务领导负责
git merge --no-ff   → 业务领导在每个里程碑审批通过后执行
返工                → 重新 delegate_task，附带返工请求中的具体修改指令
回溯返工            → 业务领导开 backport/ 分支 → delegate_task 给上游团队
                      → 上游修改后审查 → merge → 通知下游 rebase
project-log.md      → 每次决策后追加日志

审查流程：
  1. Glob 确认文件存在
  2. 检查 DELIVERY-MANIFEST.md 中的"覆盖度检查"和"核心内容摘要"
  3. Read 抽查 1 个文件，核对内容与清单描述是否一致
  4. M3 阶段：风险导向**分层**代码抽查（含 MyBatis XML 专项检查）
  5. 检查"给下游团队的关键信息"是否完整
  6. 检查"对上团队的问题"字段，如有问题优先处理

⚠️ 关键约束：子 Agent 运行在隔离环境中，无法直接调用 git。
   所有 git 操作必须由业务领导执行。
   子 Agent 的职责仅限于：读取文件 → 分析/编码 → 写入文件到指定目录。

十二、执行保障清单

为确保流程可执行，业务领导在每个关键节点必须完成以下检查：

派单前检查

已读取当前阶段的 DELIVERY-MANIFEST.md
已提取"给下游团队的关键信息"
已在 prompt 中嵌入关键信息
（Team C）已明确文件所有权划分
（Team D）已指定测试重点

审查时检查

已用 Glob 确认所有交付文件存在
已检查"覆盖度检查"和"核心内容摘要"是否合理
已用 Read 抽查 1 个文件，内容与清单一致
已检查"给下游团队的关键信息"是否完整
已检查"对上团队的问题"字段，如有问题已处理
（M3）Team C 已在 DELIVERY-MANIFEST.md 中注明编译自检结果
（M3）业务领导复核 ./gradlew compileJava 通过（受影响的模块）
（M3）已执行风险导向分层代码抽查（抽样记录已写入 milestone-N-review.md）
（M3，CRRC 项目）如有 MyBatis XML 变更，已完成 XML 专项检查
（M4）Team D 编写的自动化测试 ./gradlew test 通过
（M4）测试代码未修改 src/main/java/ 下的文件
（M4）核心接口测试覆盖了业务领导指定的重点场景
已输出评审文档
已更新 project-log.md

返工时检查

已明确返工原因（质量问题/需求变更/任务复杂度）
已提供具体修改指令（精确到文件、内容）
已更新 project-log.md
返工次数未超过 2 次（超过则触发升级机制）

回溯时检查

已评估影响范围，确认是否有临时绕过方案
已确认回溯分支从 main（而非当前工作分支）开出
已提供精确到文件、行号的修改要求
修改完成后，已通知当前阶段团队 rebase
已更新 project-log.md 记录回溯原因和处理

附录C：CRRC 项目适配指南

本附录汇总了 CRRC 项目（Java 8 / Spring Boot 1.5.9 / Gradle 多模块）特有的流程适配点。当流程在 CRRC 项目中执行时，以下约定优先于正文通用描述。

C.1 多模块 Gradle 构建

CRRC 项目是约 20 个独立 Gradle 模块的集合，每个模块拥有独立的 build.gradle 和 gradlew：

根目录没有 settings.gradle，各模块独立编译
必须进入具体模块目录再执行 ./gradlew 命令
service-common 是共享库，修改公共 DTO/VO/常量后，先编译该模块，再编译依赖它的业务模块

编译验证命令示例：

# 验证 service-bill 模块编译
cd com.sayu.service-bill
./gradlew compileJava

# 依赖链编译（先公共库，后业务模块）
cd com.sayu.service-common && ./gradlew compileJava
cd com.sayu.service-bill && ./gradlew compileJava

并行开发时，文件所有权按模块粒度划分（见 C.3）。

C.2 测试框架约定

测试框架：Spring Boot 1.5.x Starter Test + JUnit 4
测试目录：标准 src/test/java/（非 src/main/test/）
已有测试样例：com.sayu.service-message/src/test/main/ServiceTest.java
Team D 不得在 src/main/ 下创建测试文件
项目当前测试覆盖极少 —— Team D 的策略是"核心接口优先"，优先为业务领导指定的核心接口编写测试

C.3 多模块文件所有权模型

替代附录A中的"单模块文件所有权"，CRRC 模式下 Team C 的并行拆分按模块边界划分：

Team C-User 负责：
  - com.sayu.service-user/src/main/java/**（全部 Java 代码）
  - com.sayu.service-user/src/main/resources/**（配置 + MyBatis XML）

Team C-Bill 负责：
  - com.sayu.service-bill/src/main/java/**
  - com.sayu.service-bill/src/main/resources/**

Team C-Gateway 负责：
  - com.sayu.gateway-*/src/main/java/**
  - com.sayu.gateway-*/src/main/resources/**

共享库（任何 Team C 子团队不可擅自修改，需通过返工流程）：
  - com.sayu.service-common/**

禁止修改的文件：
  - 各模块 build.gradle（由业务领导统一管理）
  - .gitignore
  - 已合并到 main 的其他阶段交付物

C.4 MyBatis XML 专项检查

CRRC 项目使用 MyBatis XML 动态 SQL。M3 代码抽查中，必须增加对 XML 的专项检查：

检查项（覆盖所有新增/修改的 XML 文件）：

序号	检查项	说明
1	禁止 `${}` 字符串替换	参数必须使用 `#{}` 语法，`${}` 可能导致 SQL 注入
2	namespace 一致性	Mapper namespace 必须与 Java Mapper 接口全限定名一致
3	resultType 有效性	`resultType` 引用的 VO/Entity 类必须存在（用 Glob 确认）
4	文件路径规范	必须位于 `src/main/resources/mapper/{domain}/`
5	mybatis.base.package	`application.properties` 中的扫描路径需覆盖新增的 mapper 包

${} 排查方法： 用 Grep 搜索 XML 文件中的 $ 符号：

Grep pattern: \$\{[^#]

匹配到的行需要逐一审查，确认是否为合法的动态表名/列名使用（极少场景才允许），或应改为 #{} 参数化。

CRRC 项目既有拼写提醒： 以下拼写是历史遗留，抽查时不要误报：

contanst（非 constant）— 常量/枚举包名
bootstrapt（非 bootstrap）— service-file 模块启动包名
annotion（非 annotation）— 框架注解包名

C.5 目录归属总表

目录类型	归属团队	说明
`com.sayu.*/src/main/java/`	Team C	业务代码
`com.sayu.*/src/main/resources/`	Team C	配置 + MyBatis XML
`com.sayu.*/src/test/java/`	Team D	自动化测试代码
`deliveries/team-a-requirement/`	Team A	需求文档
`deliveries/team-b-architecture/`	Team B	架构文档
`deliveries/team-c-coding/`	Team C	实现说明
`deliveries/team-d-testing/`	Team D	测试文档
`com.sayu.service-common/`	ALL（只读）	共享库，修改需返工流程
`docs/`	业务领导	项目文档

C.6 CRRC 特有的安全注意

仓库中的 application.properties 和 Gradle 发布配置可能包含内部 Nexus 凭据或测试环境密钥，不要复制到新文档或提交说明中
多模块之间的 Feign 调用路径和包名需要与 SERVICE_NAME / SERVICE_CONTEXT_PATH 常量一致
网关层（gateway-pc、gateway-mobile、gateway-management）的免登录、免权限路径配置需在新增公开接口时同步检查

十三、待定事项

~~试水项目选择~~ → 已通过「在线笔记系统」完成试水验证
是否需要增加 Code Review 团队角色
~~返工次数上限~~ → 上限 2 次，第 3 次触发升级机制
~~并行开发支持~~ → 已支持，含合并策略
~~CRRC 多模块适配~~ → v2.2 已新增附录 C，覆盖 Gradle 构建、MyBatis XML 检查、多模块所有权
CI/CD 自动化验证 → 当前设计已覆盖编译自检 + 自动化测试门控，CI/CD 作为可选增强

multi-agent-git-workflow-v2.1.md 43 KB История Исходник

多 Agent + Git 协同开发流程设计 (v2.2)

一、核心理念

设计原则

v2.1 核心改进（相比 v1.0）

v2.2 核心改进（相比 v2.1）

二、组织架构

角色分工

上下文传递机制

三、整体流程

附录A：并行开发合并策略

附录B：环境就绪检查清单

四、Git 分支命名规范

Commit Message 规范

五、仓库目录结构

目录归属规则

六、交付清单机制 (DELIVERY-MANIFEST.md)

清单模板

覆盖度检查字段说明

业务领导查验流程

Prompt 模板嵌入（强制执行）

七、项目生命周期日志 (project-log.md)

日志模板

过程改进数据

阶段耗时统计

返工统计

一次通过率

失败原因分类（Top N）

日志维护规则

八、里程碑与审批机制

量化验收指标

风险导向代码分层抽查（M3 阶段）

分层抽样策略

风险分层

CRRC 专项补充

抽样记录

Team D 测试重点指定

Team D 自动化测试质量要求

九、返工机制

设计原则

返工触发方式

返工升级路径

返工请求模板

跨阶段回溯返工

触发条件

回溯流程

回溯 vs 普通返工的区别

回溯请求模板

十、业务领导管控点

十一、与 Hermes 的执行映射

十二、执行保障清单

派单前检查

审查时检查

返工时检查

回溯时检查

附录C：CRRC 项目适配指南

C.1 多模块 Gradle 构建

C.2 测试框架约定

C.3 多模块文件所有权模型

C.4 MyBatis XML 专项检查

C.5 目录归属总表

C.6 CRRC 特有的安全注意

十三、待定事项

multi-agent-git-workflow-v2.1.md 43 KB

История Исходник