# 多 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 中填写"给下游团队的关键信息"。

**双重保障**：

1. **当前团队填写**：在 DELIVERY-MANIFEST.md 中填写"给下游团队的关键信息"
   - 他们最清楚自己的决策和约束
   - 业务领导审查时可以补充或修正

2. **业务领导提炼**：派单时将关键信息嵌入 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 补充字段**

```markdown
## 修改文件清单（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`。

### 清单模板

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

## 里程碑信息
- 阶段: [需求分析 / 架构设计 / 编码实现 / 测试验收]
- 里程碑编号: 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)

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

### 日志模板

```markdown
# 项目生命周期日志

## 项目基本信息
- 项目名称: 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` 中：

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

### Team D 测试重点指定

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

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

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

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

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

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

### Team D 自动化测试质量要求

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

1. **通过率**：`./gradlew test` 全部通过（不能仅因为新增测试而跳过）
2. **独立性**：每个测试方法独立运行，不依赖其他测试的执行顺序
3. **可重复**：同一测试多次运行结果一致
4. **不修改源代码**：测试代码不得修改 `src/main/java/` 下的任何文件
5. **无网络依赖**：单元测试不应依赖外部服务（使用 Mock）
6. **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 中记录决策和原因
```

### 返工请求模板

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

## 基本信息
- 返工编号: 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 次（仍不通过则进入升级流程） |

#### 回溯请求模板

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

## 基本信息
- 回溯编号: 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/常量后，先编译该模块，再编译依赖它的业务模块

编译验证命令示例：

```bash
# 验证 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`）的免登录、免权限路径配置需在新增公开接口时同步检查


---

## 十三、待定事项

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