Imported from gaoqiongxie/skills-ai (backend-change-flow/SKILL.md). Install upstream with npx skills add gaoqiongxie/skills-ai --skill backend-change-flow. Copyright stays with the author.

来源: 自建（蒸馏 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: 没有跑过编译器/测试的代码 = 薛定谔的代码，可能同时对也可能错

防御策略速查表：

阶段 ①：代码理解（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
// [完整代码，含注释]

自检声明

• 本代码在本地编译通过（或：请用户在 IDE 中编译验证）
• 事务边界已标注
• 异常分支已覆盖

⚠️ 需要用户验证

• 请确认 refundOrder() 的入参设计是否符合你的预期
• 请在本地运行 mvn compile / go build / 等，确认编译通过
• 编译通过后，回复"继续"，我将进入 M03

🛡️ 不要一次性给太多代码。如果 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 的关系

最佳实践链：

需求模糊 → openspec-sdd（澄清）→ backend-change-flow（变更闭环）→ quality-gate（提交检查）→ create-pr（生成 PR）
         ↓
    被 AI 逼疯 → ai-collaboration-safety（恢复 + 策略调整）→ 回到 backend-change-flow

"后端变更最怕的不是写错代码——是需求、文档、代码各说各话。"

"和 AI 协作最怕的不是它犯错——是你被它的伪共情和重复错误逼疯后，还在给它机会。"