# Backend Change Flow > 后端需求驱动变更工作流：读取代码→解析需求→明确修改点→需求文档代码对齐→编码→循环Review→最终一致性确认。当用户说'帮我改这个接口'、'根据需求改代码'、'实现这个功能'、'代码变更'、'需求对齐'、'确认修改点'时触发。核心特点：七阶段闭环、需求追踪矩阵、影响范围分析、三一致校验（需求/文档/代码）、AI幻觉防护（原子输出/确定性验证/熔断机制）。 - Skill: `gaoqiongxie/backend-change-flow` (Agent Skill) - Install (CLI): `npx skillmds@latest add gaoqiongxie/backend-change-flow` - Raw SKILL.md: https://api.skillmd.com/api/skills/gaoqiongxie/backend-change-flow/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: gaoqiongxie (https://skillmd.com/u/gaoqiongxie) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/gaoqiongxie/backend-change-flow --- > **来源**: 自建（蒸馏 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 说"根据你的架构" → 追问"具体依据哪几个文件？" ``` ### 输出模板：代码上下文摘要 ```markdown ## 代码上下文摘要 ### 模块边界 - **入口**: `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 给出的验收标准可能不量化 → 要求"这个标准如何自动化验证？" ``` ### 输出模板：结构化需求清单 ```markdown ## 需求清单（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 的"低风险"判断不可信 → 用户必须手动确认风险等级 ``` ### 输出模板：修改点清单 ```markdown ## 修改点清单 ### 🔴 直接修改（需求驱动） | 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 可能"假装"对齐 → 要求它指出具体的**矛盾点**，而非笼统说"一致" ``` ### 输出模板：对齐检查报告 ```markdown ## 三对齐检查报告 ### ✅ 需求 ↔ 现有文档 | 检查项 | 结果 | 说明 | |--------|------|------| | 文档是否包含退款流程？ | ❌ 缺失 | 需新增退款接口文档 | | 订单状态枚举是否完整？ | ⚠️ 过时 | 文档缺少 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 对任何一行代码解释"为什么这么写" ``` ### 输出模板：编码进度（原子输出） ```markdown ## 编码进度（原子输出模式） | 修改点 | 文件 | 状态 | 自检结果 | |--------|------|------|---------| | 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 // [完整代码，含注释] ``` ### 自检声明 - [x] 本代码在本地编译通过（或：请用户在 IDE 中编译验证） - [x] 事务边界已标注 - [x] 异常分支已覆盖 ### ⚠️ 需要用户验证 - [ ] 请确认 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 报告模板 ```markdown ## 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 盲区及用户验证项" ``` ### 输出模板：一致性确认书 ```markdown # ✅ 一致性确认书 ## 项目: 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 协作最怕的不是它犯错——是你被它的伪共情和重复错误逼疯后，还在给它机会。"