| name | backend-change-flow |
| description | 后端需求驱动变更工作流：读取代码→解析需求→明确修改点→需求文档代码对齐→编码→循环Review→最终一致性确认。当用户说'帮我改这个接口'、'根据需求改代码'、'实现这个功能'、'代码变更'、'需求对齐'、'确认修改点'时触发。核心特点：七阶段闭环、需求追踪矩阵、影响范围分析、三一致校验（需求/文档/代码）、AI幻觉防护（原子输出/确定性验证/熔断机制）。 |
来源: 自建（蒸馏 dev-flow + systematic-debugging + quality-gate 的后端变更场景，融合 AI 协作安全机制）
发布时间: 2026-05-25
理念: "后端变更不是直接写代码——是先对齐，再动手，最后验证三一致。同时，防止 AI 的重复错误和伪共情把开发者逼疯。"
🔄 Backend Change Flow — 后端需求驱动变更工作流
从需求到代码的七阶段闭环，确保每一次变更都有依据、有范围、有验证。
同时内置 AI 协作安全机制，防止 AI 的以下问题把你逼疯：
- 重复犯错 → 用原子输出 + 检查点打断循环
- 伪共情道歉 → 用确定性验证替代信任
- 无限责任滑移 → 用修改点清单锁定范围
- 幻觉代码 → 用编译/测试作为唯一真理标准
🎯 七阶段闭环
┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ ① 代码理解 │ → │ ② 需求解析 │ → │ ③ 影响分析 │ → │ ④ 三对齐确认 │
└─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘
↑ ↓
┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ ⑦ 一致性确认 │ ← │ ⑥ 循环Review │ ← │ ⑤ 编码实现 │ ← │ ④ 三对齐确认 │
└─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘
🛡️ AI 协作安全总则（贯穿全阶段）
记住三条铁律，否则你会被 AI 逼疯：
铁律1: AI 的道歉 = token 排列，≠ 真诚理解 ≠ 下次会改
铁律2: AI 说"根据你的代码"时，50% 概率它在 hallucinate，务必验证
铁律3: 没有跑过编译器/测试的代码 = 薛定谔的代码，可能同时对也可能错
防御策略速查表：
| AI 危险行为 | 你的防御动作 | 为什么有效 |
|---|
| 一次输出 200 行代码 | 要求"原子输出"：每次只写一个方法/一个文件 | 错误在检查点被发现，不累积 |
| "抱歉我理解错了，这次一定对" | 不要原谅，要求解释具体哪里错了 | 迫使 AI 显式回溯，而非换种说法继续错 |
| 自信满满给出"最终方案" | 反问"你的判断依据是代码的哪一行？" | 幻觉最怕被追问具体出处 |
| 遗漏边界条件/异常处理 | 每写完一段，强制要求列出3 个反例 | 补全思维盲区 |
| 用户自己开始暴躁 | 立即熔断：停止对话，离开屏幕，回来后换一个角度提问 | 防止情绪崩溃 + token 浪费 |
阶段 ①：代码理解（Read & Comprehend）
目标：让 AI 完整理解现有代码上下文，但不盲信 AI 的理解。
执行清单
□ 读取用户指定的入口文件（Controller/Service/Handler）
□ 递归读取直接依赖（调用链上下游）
□ 读取相关配置（DB表结构、API路由、中间件）
□ 读取现有测试文件（定位回归风险点）
□ 输出【代码上下文摘要】
⚠️ AI 安全提示：
□ AI 声称"理解了" → 要求它复述关键数据流，用户验证是否正确
□ AI 提到某行代码的逻辑 → 要求它给出**具体文件路径 + 行号**
□ AI 说"根据你的架构" → 追问"具体依据哪几个文件？"
输出模板：代码上下文摘要
## 代码上下文摘要
### 模块边界
- **入口**: `XxxController.java` / `xxx_handler.go` / `xxx.routes.ts`
- **核心服务**: `XxxService`（业务逻辑层）
- **数据层**: `XxxRepository` / `XxxMapper`（DB 交互）
- **外部依赖**: 调用了哪些下游服务/第三方接口
### 关键数据流
[请求] → Controller → Service → Repository → DB
↓ ↓
参数校验 业务规则/事务
↓ ↓
返回DTO 异常处理
### 现状标记
- 🟢 无需改动（但需了解）
- 🟡 可能受影响（关联逻辑）
- 🔴 必须改动（直接需求点）
### ⚠️ AI 理解自校验（用户必须确认）
- [ ] AI 复述的数据流与实际代码一致？
- [ ] 提到的文件路径和行号真实存在？
- [ ] 没有遗漏关键的拦截器/过滤器/AOP 逻辑？
阶段 ②：需求解析（Parse Requirements）
目标：把模糊需求拆成可验证、可追踪的条目。防止 AI 遗漏隐性需求。
执行清单
□ 区分功能需求 vs 非功能需求（性能/安全/兼容）
□ 提取显性需求（用户明确说的）
□ 挖掘隐性需求（默认值、边界、异常、权限）
□ 识别验收标准（什么算"做完了"）
□ 输出【结构化需求清单】
⚠️ AI 安全提示：
□ AI 容易遗漏隐性需求 → 强制追问："这个需求的反例是什么？"
□ AI 容易忽略权限/日志/监控 → 单独列一个"横切关注点"检查项
□ AI 给出的验收标准可能不量化 → 要求"这个标准如何自动化验证？"
输出模板：结构化需求清单
## 需求清单（Req-XXX）
| ID | 类型 | 需求描述 | 优先级 | 验收标准 | 状态 |
|----|------|---------|--------|---------|------|
| R01 | 功能 | 新增订单退款接口 | Must | 传入订单号+金额，返回退款流水号 | 🔲 |
| R02 | 功能 | 退款金额不能超过订单实付金额 | Must | 超限抛业务异常，错误码 REFUND_EXCEED | 🔲 |
| R03 | 非功能 | 退款接口 QPS ≥ 100 | Should | 压测通过 | 🔲 |
| R04 | 边界 | 重复退款请求需幂等 | Must | 同一订单号+金额，返回相同流水号 | 🔲 |
| R05 | 异常 | 下游支付通道超时，需降级记录 | Should | 落异常表，定时任务补偿 | 🔲 |
### 横切关注点（AI 容易遗漏）
| 检查项 | 是否相关 | 说明 |
|--------|---------|------|
| 权限校验 | ☐ | 需要哪些角色/数据权限？ |
| 操作日志 | ☐ | 是否需要审计日志？ |
| 监控告警 | ☐ | 失败率/延迟是否需要告警？ |
| 数据迁移 | ☐ | 历史数据是否需要处理？ |
### 反例清单（防止 AI 思维盲区）
1. 如果订单不存在怎么办？
2. 如果并发请求同时退款同一订单怎么办？
3. 如果退款金额 = 0 或负数怎么办？
阶段 ③：影响分析（Impact Analysis）
目标：定位精确修改点，评估回归风险。
执行清单
□ 逐条需求映射到具体文件/方法/字段
□ 识别数据库变更（新字段/新表/索引/迁移脚本）
□ 识别 API 变更（入参/出参/路径/版本兼容）
□ 识别下游调用变更（消息队列/HTTP/RPC）
□ 评估回归风险（哪些现有逻辑可能被影响）
□ 输出【修改点清单 + 风险矩阵】
⚠️ AI 安全提示：
□ AI 容易高估自己的理解 → 修改点必须映射到**具体文件 + 方法名**
□ AI 容易遗漏回归风险 → 要求"列出至少 2 个可能被破坏的现有功能"
□ AI 的"低风险"判断不可信 → 用户必须手动确认风险等级
输出模板：修改点清单
## 修改点清单
### 🔴 直接修改（需求驱动）
| ID | 需求 | 文件 | 方法/字段 | 变更类型 |
|----|------|------|----------|---------|
| M01 | R01 | OrderController.java | 新增 `refund()` | 新增 |
| M02 | R01 | OrderService.java | 新增 `refundOrder()` | 新增 |
| M03 | R01 | RefundRepository.java | 新增 `insertRefundRecord()` | 新增 |
| M04 | R02 | OrderService.java | `refundOrder()` 内加校验逻辑 | 修改 |
| M05 | R04 | RefundRepository.java | 唯一索引 `(order_no, amount)` | 新增索引 |
### 🟡 关联影响（需回归验证）
| 文件 | 原因 | 验证方式 |
|------|------|---------|
| OrderQueryService.java | 退款后订单状态变化，查询逻辑可能受影响 | 跑现有查询单测 |
| order_status_enum.sql | 可能需新增 REFUNDING 状态 | 检查状态机流转 |
### ⚪ 文档同步
| 文档 | 变更内容 |
|------|---------|
| API.md | 新增退款接口契约 |
| CHANGELOG.md | 记录本次变更 |
### 风险矩阵
| 风险项 | 概率 | 影响 | 缓解措施 | AI 判断 | 用户确认 |
|--------|------|------|---------|---------|---------|
| 幂等逻辑遗漏导致重复退款 | 中 | 高（资金损失） | 数据库唯一索引 + 代码幂等校验 | ⚠️ | ☐ |
| 下游支付超时未处理 | 高 | 中（用户体验） | 异常落表 + 补偿任务 | ⚠️ | ☐ |
> ⚠️ **注意**：AI 的风险判断仅供参考，用户必须根据实际情况确认。**AI 经常低估风险。**
阶段 ④：三对齐确认（Alignment Check）
目标：确保需求、文档、代码现状三者一致，动手前冻结共识。
这是最重要的防幻觉关卡。没有用户明确说"继续"，AI 不得进入编码阶段。
执行清单
□ 需求 ↔ 现有文档：文档是否覆盖全部需求？是否有 outdated？
□ 需求 ↔ 现有代码：代码现状是否支持需求实现？是否有冲突？
□ 文档 ↔ 代码：现有文档是否准确描述当前代码？
□ 输出【对齐检查报告】，用户确认后才进入编码
⚠️ AI 安全提示：
□ AI 可能急于编码 → 明确告诉它："用户确认前，不生成任何代码"
□ AI 可能"假装"对齐 → 要求它指出具体的**矛盾点**，而非笼统说"一致"
输出模板：对齐检查报告
## 三对齐检查报告
### ✅ 需求 ↔ 现有文档
| 检查项 | 结果 | 说明 |
|--------|------|------|
| 文档是否包含退款流程？ | ❌ 缺失 | 需新增退款接口文档 |
| 订单状态枚举是否完整？ | ⚠️ 过时 | 文档缺少 REFUNDING 状态 |
### ✅ 需求 ↔ 现有代码
| 检查项 | 结果 | 说明 |
|--------|------|------|
| 是否有退款相关代码？ | ❌ 无 | 从零实现 |
| 订单金额字段是否支持退款计算？ | ✅ 支持 | `actual_pay_amount` 字段可用 |
### ✅ 文档 ↔ 代码
| 检查项 | 结果 | 说明 |
|--------|------|------|
| API 文档与 Controller 路径一致？ | ✅ 一致 | /api/v1/order/* |
---
### 🚦 准入判定
- [x] 需求已全部拆解为可验证条目
- [x] 修改点已定位到具体文件/方法
- [x] 回归风险已识别并制定缓解措施
- [x] 文档缺口已标记
- [ ] **用户确认：以上分析正确，可以进入编码**
> ⚠️ **用户确认前，不生成任何代码。**
>
> 🛡️ **AI 安全声明**：如果用户表现出焦躁（如"你到底行不行"、"别废话了"），AI 应：
> 1. 停止当前输出
> 2. 简洁总结当前进度
> 3. 询问"你希望我从哪里继续？"而非继续长篇大论
阶段 ⑤：编码实现（Implement）
目标：按修改点清单逐项实现，每完成一项自检。原子输出，防止 AI 一次给太多导致错误。
执行原则（含 AI 安全机制）
1. 严格按【修改点清单】顺序实现，不跳项
2. 每完成一个修改点，标记 ✅ 并附【自检结果】
3. 保持现有代码风格（命名/异常处理/日志规范）
4. 新增方法必须写 JavaDoc / GoDoc / 注释
5. 涉及事务的，显式标注事务边界
🛡️ 原子输出原则（防止 AI 逼疯你）：
6. 每次只输出【一个修改点】的完整代码，不超出一个文件
7. 输出后等待用户确认，再继续下一个修改点
8. 如果用户说"继续"，先复述上一个修改点的关键决策，确保上下文未丢失
🛡️ 幻觉对抗原则：
9. AI 引用任何框架 API / 类库方法时，必须同时给出**官方文档链接或源码路径**
10. AI 写的 SQL / 正则 / 复杂表达式，必须附带** explain / 测试用例**
11. 用户有权要求 AI 对任何一行代码解释"为什么这么写"
输出模板：编码进度（原子输出）
## 编码进度（原子输出模式）
| 修改点 | 文件 | 状态 | 自检结果 |
|--------|------|------|---------|
| M01 | OrderController.java | ✅ | 路径 /api/v1/order/refund，参数校验注解完整 |
| M02 | OrderService.java | ⏳ | 待实现（当前聚焦） |
| M03 | RefundRepository.java | 🔲 | 等待 |
| M04 | OrderService.java | 🔲 | 等待 |
| M05 | V20260525__add_refund_unique_idx.sql | 🔲 | 等待 |
---
### 当前修改点：M02 - OrderService.java 新增 refundOrder()
```java
// [完整代码，含注释]
自检声明
⚠️ 需要用户验证
🛡️ 不要一次性给太多代码。如果 AI 一次输出了 M02-M05，请打断它，要求"只完成 M02，等确认"。
---
## 阶段 ⑥：循环 Review（Iterative Review）
**目标**：发现需求遗漏、代码缺陷、文档不同步，反复修正直到达标。**同时识别 AI 自己的 Review 盲区。**
### Review 维度
```markdown
## Review 检查清单
### 维度1: 需求覆盖度
□ 每条需求（R01-R05）都有对应的代码实现？
□ 边界条件（空值/越界/重复/超时）是否处理？
□ 异常场景是否有兜底？
### 维度2: 代码质量
□ 是否符合团队编码规范（命名/格式/注释）？
□ 是否有重复代码？能否提取公共方法？
□ 圈复杂度是否过高（>10 需拆分）？
□ 日志是否完整（入参/出参/异常/关键分支）？
### 维度3: 数据一致性
□ DB 事务边界是否正确？
□ 并发场景是否安全（锁/乐观锁/幂等）？
□ 状态机流转是否闭环？
### 维度4: 接口契约
□ 入参校验是否完整（@Valid / 手动校验）？
□ 出参是否与文档一致（字段名/类型/必填）？
□ 错误码是否新申请/复用合理？
### 维度5: 测试配套
□ 单元测试是否覆盖主路径 + 边界 + 异常？
□ 是否需要集成测试（DB/下游 Mock）？
□ 现有测试是否全部通过（回归）？
### 维度6: 文档同步
□ API 文档是否更新？
□ CHANGELOG 是否记录？
□ 复杂逻辑是否有代码注释/设计说明？
🛡️ 维度7: AI 盲区检查（容易被 AI 自身忽略）
□ AI 是否遗漏了横切关注点（日志/监控/权限）？
□ AI 是否假设了不存在的前提（如某个字段一定非空）？
□ AI 是否忽略了框架版本差异（如 Spring Boot 2 vs 3）？
□ AI 写的测试是否真的验证了业务逻辑，还是只是"凑覆盖率"？
□ 用户修改了需求后，AI 是否只改了代码而忘了改文档？
循环机制 + AI 安全熔断
Review 发现 Gap
↓
定位到具体修改点（M01-M05）
↓
回到阶段 ⑤ 修正代码
↓
重新跑阶段 ⑥ Review
↓
直到全部检查项通过
🚨 熔断条件（防止无限循环）：
- 同一个修改点被修正超过 3 次 → 停止编码，分析根因（是需求不清？还是 AI 根本不懂这个技术栈？）
- 用户情绪明显焦躁（出现"大傻子"、"到底行不行"、"又错了"）→ 立即停止输出，简洁总结进度，询问用户希望如何处理
- Review 发现 AI 连续两次犯同类错误（如两次都遗漏异常处理）→ 怀疑 AI 对该模式理解不足，要求用户介入决策
Review 报告模板
## Review 报告（第1轮）
| 检查项 | 结果 | 问题描述 | 修正措施 | AI 盲区？ |
|--------|------|---------|---------|----------|
| R04 幂等 | ❌ | 代码只有 DB 唯一索引，没有前置查询拦截 | M02 增加先查后插逻辑 | 是，AI 以为索引就够了 |
| 日志 | ⚠️ | 退款失败没有记录 userId | M02 补充日志字段 | 否 |
| 单元测试 | ❌ | 缺少重复退款场景的测试 | 新增 RefundServiceTest#testDuplicateRefund | 是，AI 只写了主路径 |
### 需修正的修改点：M02, M05（测试）
### 修正后重新 Review：是
⚠️ **本轮 Review 发现 2 个 AI 盲区**，修正后请用户特别关注这两个点。
阶段 ⑦：最终一致性确认（Final Consistency Check）
目标：交付前最后验证——需求、文档、代码三者完全一致。AI 不得自行宣布完成，必须等待用户确认。
执行清单
□ 需求清单（R01-R05）全部打勾 ✅
□ 修改点清单（M01-M05）全部打勾 ✅
□ Review 检查清单全部通过 ✅
□ 单元测试/集成测试全部通过 ✅
□ API 文档与代码一致 ✅
□ CHANGELOG 已更新 ✅
□ 输出【一致性确认书】
⚠️ AI 安全提示：
□ AI 倾向于"急着交卷" → 明确告诉它"不要催我确认"
□ AI 可能遗漏"AI 盲区检查项" → 确认书里必须包含"已知 AI 盲区及用户验证项"
输出模板：一致性确认书
# ✅ 一致性确认书
## 项目: xxx-service
## 变更主题: 订单退款功能
## 日期: 2026-05-25
---
### 三一致校验
| 维度 | 校验结果 | 证据 |
|------|---------|------|
| 需求 → 代码 | ✅ 一致 | 需求 R01-R05 均有对应代码实现，见修改点清单 |
| 代码 → 文档 | ✅ 一致 | API.md 已更新退款接口，参数/返回值与代码匹配 |
| 需求 → 文档 | ✅ 一致 | 文档覆盖全部需求条目，无遗漏 |
### 质量门控
| 检查项 | 结果 |
|--------|------|
| 单元测试覆盖率 | 85% ✅（阈值 80%） |
| 单元测试通过率 | 100% ✅ |
| 集成测试通过率 | 100% ✅ |
| 代码规范检查 | 通过 ✅ |
| 安全扫描（敏感信息） | 通过 ✅ |
### 变更范围
新增文件:
- RefundRepository.java
- V20260525__add_refund_unique_idx.sql
- RefundServiceTest.java
修改文件:
- OrderController.java（+ refund 方法）
- OrderService.java（+ refundOrder 方法）
### ⚠️ 已知 AI 盲区 & 用户验证项
以下项目由 AI 生成，**存在幻觉风险，用户必须手动验证：**
| 检查项 | AI 声明 | 用户验证状态 |
|--------|---------|-------------|
| 幂等逻辑在并发下有效 | AI 认为唯一索引+先查后插足够 | ☐ 请用户用 JMeter/Gatling 压测并发退款 |
| 事务回滚场景 | AI 假设所有异常都会触发回滚 | ☐ 请用户手动抛异常验证回滚 |
| 下游超时降级 | AI 建议落异常表，未实现补偿任务 | ☐ 请用户确认是否需要补充定时任务 |
### 确认人
- AI 自检：通过 ✅
- 用户确认：________（请回复"确认"完成交付）
---
> 🎉 三一致确认完成，可以进入 Code Review / 提 PR 阶段。
>
> 🛡️ 如果你此时对 AI 的任何结论有疑问，**不要客气，直接追问"依据是什么？"**。AI 不会受伤，但你的代码会受益。
🚀 快速入口
用户：帮我实现订单退款功能
AI（进入 backend-change-flow）：
1. 【阶段①】读取 OrderController、OrderService、相关表结构...
⚠️ 用户验证：AI 复述的数据流是否正确？
2. 【阶段②】解析需求：退款接口、金额校验、幂等、超时处理...
⚠️ 用户验证：反例清单是否完整？
3. 【阶段③】影响分析：需改 Controller/Service/Repository/DB...
⚠️ 用户验证：风险等级是否合理？
4. 【阶段④】三对齐确认：文档缺少退款流程，需新增，用户确认吗？
→ [用户说"继续"]
5. 【阶段⑤】原子输出：先只写 M01 Controller...
→ [用户编译通过，说"继续"]
6. 【阶段⑤】再写 M02 Service...
→ [用户发现异常分支遗漏，打断]
7. 【阶段⑥】Review：修正异常处理，重新 Review...
8. 【阶段⑦】输出一致性确认书 + AI 盲区清单，用户最终确认
🆚 与现有 Skill 的关系
| Skill | 关系 | 何时用 |
|---|
| dev-flow | 互补 | dev-flow 管全流程导航，backend-change-flow 管编码变更的精细闭环 |
| systematic-debugging | 前置 | 如果变更涉及 Bug 修复，先用 systematic-debugging 根因定位，再进入本流程 |
| quality-gate | 后置 | 本流程阶段⑥ Review 完成后，用 quality-gate 做最终提交前检查 |
| create-pr | 后置 | 一致性确认后，用 create-pr 生成规范 PR 描述 |
| openspec-sdd | 前置 | 如果需求不清晰，先用 openspec-sdd 输出 Gherkin 验收场景，再进入本流程 |
| ai-collaboration-safety | 平行 | 如果感到被 AI 的重复错误逼疯，切换到 ai-collaboration-safety 进行情绪恢复和策略调整 |
最佳实践链：
需求模糊 → openspec-sdd（澄清）→ backend-change-flow（变更闭环）→ quality-gate（提交检查）→ create-pr（生成 PR）
↓
被 AI 逼疯 → ai-collaboration-safety（恢复 + 策略调整）→ 回到 backend-change-flow
"后端变更最怕的不是写错代码——是需求、文档、代码各说各话。"
"和 AI 协作最怕的不是它犯错——是你被它的伪共情和重复错误逼疯后，还在给它机会。"
