# 一个需求从 3 天到 1 天：Agent 工作流拆解实录 **副标题：** 不是 AI 替你写代码，是你设计流程、Agent 跑执行 --- 上周完成了一个后端需求迁移：**把用户权限模块从「角色硬编码」迁到「RBAC 策略引擎」**。 按传统做法，这种活心理预期是 **3 个工作日**： - Day 1：读代码、画改动范围、改接口层 - Day 2：跨包迁移权限判断逻辑、补单测 - Day 3：跑集成测试、修边界 case、写 PR 实际做完，**7 小时收工，当天合并**。 不是代码量变少，而是 **执行层时间被 Agent 吃掉了**——人做的是流程设计和验收标准制定，Agent 跑的是重复劳动。 下面就把整套流水线操作方式拆解出来。 --- ## 一、先说结论：时间省在哪？ | 阶段 | 传统做法 | Agent 工作流 | 耗时变化 | |------|---------|-------------|---------| | 读代码、画范围 | 手动 grep 翻文档 | Claude Code `/init` 结构化扫描 | 4h → 1h | | 接口层改动 | 手写 复制粘贴 | Cursor Tab + Cmd K | 5h → 2h | | 跨包逻辑迁移 | 人工逐文件改 | Claude Code 端到端 + 跑测试 | 8h → 3h | | 集成测试排查 | 反复手动跑、猜 | Agent 读日志循环修 | 4h → 1.5h | | PR / 文档 | 手写 | 模板化生成 + 人审 | 1.5h → 0.5h | | **合计** | **~22.5h（约 3 天）** | **~7h（1 天）** | **~3.2x** | 关键不在于「AI 更聪明」，而是 **把任务拆成了 Agent 能闭环执行的单元**。 --- ## 二、需求背景：为什么这个活适合 Agent？ 这个需求有几个特征： - **改动面大**：8 个包、30+ 文件涉及权限判断 - **模式重复**：大量 `if role == admin` 要换成策略调用 - **验收清晰**：单测 + 集成测试全绿 = 可合并 - **边界明确**：不动数据库 schema，只改应用层 这种任务最适合 Agent：**重复模式多、规则清晰、能用测试自动验收**。 反过来，如果是「重新设计权限模型该长什么样」，那仍然是人主导，Agent 只能辅助。 --- ## 三、开工前：30 分钟搭好「Agent 施工环境」 ### 3.1 写 CLAUDE.md（一次性投入，长期回本） 在项目根目录跑： ``` /init ``` 然后手工补上关键约束： ```markdown # 项目说明 Go 微服务，Gin + PostgreSQL，权限模块在 internal/auth/。 # 本次需求约束 - 目标：角色硬编码 → RBAC 策略引擎 - 不改 DB schema - 所有权限判断统一走 authz.Check(user, action, resource) - 测试必须全绿才能提交 # 常用命令 - 单测：go test ./internal/auth/... - 全量：go test ./... - 集成：make test-integration # 禁止 - 不要改 migrations/ - 不要引入新依赖未经确认 ``` **这一步的价值：** 后面每个 Agent 会话不用重复解释项目，平均每个会话省 5～10 分钟。 ### 3.2 开 Git 分支 + 定义验收标准 ```bash git checkout -b feat/rbac-migration ``` 验收标准写进任务描述（后面直接贴给 Agent）： ``` 完成标准： 1. internal/auth/ 下所有权限判断走 authz.Check 2. go test ./... 全绿 3. make test-integration 全绿 4. 无硬编码 role 字符串残留（grep 验证） ``` **人只做两件事：定边界、定验收。** --- ## 四、Phase 1：摸清改动范围（1 小时） ### 工具：Claude Code（Sonnet） ### Prompt 模板 ``` 请分析本仓库权限相关代码： 1. 列出所有硬编码 role 判断的文件和行号 2. 按改动风险分级（高/中/低） 3. 给出分 3 批迁移的顺序建议 4. 输出为 Markdown 表格 约束：不改代码，只分析。参考 CLAUDE.md。 ``` ### 产出物 Agent 给出一张表： | 文件 | 风险 | 建议批次 | 备注 | |------|------|---------|------| | handler/user.go | 高 | Batch 1 | 入口层先改 | | service/order.go | 中 | Batch 2 | 依赖 auth 包 | | ... | ... | ... | ... | ### 人工动作（15 分钟） - 快速扫一眼有没有漏网文件 - 调整批次顺序（比如先改 auth 包本身） - **确认后再进入执行阶段** > 关键原则：**先 Plan，后 Execute。** 这一步省了后面大量返工。 --- ## 五、Phase 2：接口层 + 单测骨架（2 小时） ### 工具：Cursor（Tab 补全 + Cmd K） 这一层改动文件少、模式固定，Cursor 最高效。 ### 典型操作 1. 打开 `internal/auth/authz.go`，用 Tab 补全 `Check()` 方法骨架 2. 选中旧权限函数，Cmd K： ``` 把这个函数改为调用 authz.Check()，保持原有行为，补上单测 ``` 3. 对 handler 层逐个文件做同样操作 ### 为什么不用 Claude Code？ - 单文件改动，Cursor 的 Diff 预览更直观 - 改一行、看一眼、改一行，节奏快 - 不消耗 Claude Code 的长会话额度 ### 本阶段产出 - `authz.Check()` 核心实现 - handler 层 6 个文件改完 - 对应单测 12 个全绿 --- ## 六、Phase 3：跨包迁移（3 小时，最值钱的一段） ### 工具：Claude Code（Sonnet，一个 Batch 一个会话） ### Prompt 模板（Batch 2 示例） ``` 执行 Batch 2 权限迁移（见上轮分析表格）。 要求： 1. 只改 Batch 2 列出的文件 2. 硬编码 role 判断全部替换为 authz.Check() 3. 每改完一个包，跑 go test .//... 4. 失败就修到绿，再继续下一个 5. 完成后 grep 确认无遗漏 验收：go test ./internal/service/... 全绿 ``` ### Agent 实际执行循环 ``` 读文件 → 改代码 → 跑测试 → 看报错 → 再改 → 再跑 → 绿了 → 下一个 ``` 这要是人来做，最容易卡在「改完忘了跑测试」「报错不知道改哪」。Agent 的优势是 **不知疲倦地重复这个循环**。 ### 需要介入的 3 个时刻 1. **Batch 边界确认**：Agent 想改 Batch 3 的文件，喊停——「只做 Batch 2」 2. **策略语义决策**：`admin` 能否访问 `audit:read`？业务规则人定，Agent 写代码 3. **全量测试前检查**：`grep -r "role ==" internal/` 确认无残留 ### 本阶段产出 - 8 个包迁移完成 - `go test ./...` 全绿 --- ## 七、Phase 4：集成测试排查（1.5 小时） ### 工具：Claude Code（Sonnet） 集成测试挂了 2 个 case，典型报错： ``` --- FAIL: TestOrderCreate_RequiresWritePermission expected 403, got 200 ``` ### Prompt ``` make test-integration 失败了，日志如下： 请： 1. 定位根因（权限策略配置还是调用路径） 2. 修复代码 3. 重跑 make test-integration 直到全绿 4. 说明改了什么、为什么 ``` Agent 两轮修好： - Case 1：策略表缺了一条 `order:create` 规则 → 补上 - Case 2：测试用的 mock user 角色没更新 → 改测试数据 ### 人工动作 - 看 Agent 的解释，确认业务语义没错 - 重点 Review 策略表变更（这是「判断层」，不能盲信） --- ## 八、Phase 5：PR 收尾（0.5 小时） ### Prompt ``` 基于本次改动，生成 PR 描述，包含： 1. 背景和目标 2. 改动范围（按包列出） 3. 测试证据（贴 go test 结果摘要） 4. 风险点和回滚方式 5. 给 Reviewer 的检查清单 风格：简洁技术风，中文 ``` 产出直接贴 GitHub，人工只改了两处措辞。 --- ## 九、完整时间线（一张图） ``` 09:00 - 09:30 搭环境（CLAUDE.md + 分支 + 验收标准） 09:30 - 10:30 Phase 1 分析范围（Claude Code） 10:30 - 12:30 Phase 2 接口层（Cursor） 13:30 - 16:30 Phase 3 跨包迁移（Claude Code × 3 Batch） 16:30 - 18:00 Phase 4 集成测试（Claude Code） 18:00 - 18:30 Phase 5 PR 收尾 ───────────────────────────────── 合计：~7h，当天合并 ``` --- ## 十、踩过的 3 个坑（帮你省返工） ### 坑 1：一上来就让 Agent 「全部改完」 结果：改了 20 个文件，测试红一片，不知道回滚到哪。 **修法：** 分批迁移，每批验收后再进下一批。 ### 坑 2：不写验收标准，只说「帮我做 RBAC」 结果：Agent 自作主张改了 migrations，差点踩红线。 **修法：** 约束写进 CLAUDE.md + 每个 Prompt 重复关键禁止项。 ### 坑 3：全程 Opus，账单飙高 结果：这种重复迁移任务，Opus 和 Sonnet 结果差不多，成本差 3～5 倍。 **修法：** 规划用 Sonnet，只有架构决策才切 Opus。本次全程 Sonnet，API 超量约 $2。 --- ## 十一、可直接复制的「任务分包模板」 以后遇到类似需求，按这个拆： ``` ┌─────────────────────────────────────────────┐ │ Task 0：环境 + 验收标准（人） │ ├─────────────────────────────────────────────┤ │ Task 1：分析范围，输出迁移计划（Agent） │ │ → 人审计划 │ ├─────────────────────────────────────────────┤ │ Task 2：小范围高频改动（Cursor） │ ├─────────────────────────────────────────────┤ │ Task 3：大批量重复迁移（Claude Code） │ │ → 分批 + 每批测试门禁 │ ├─────────────────────────────────────────────┤ │ Task 4：集成测试 / 边界 case（Claude Code） │ │ → 人审业务语义 │ ├─────────────────────────────────────────────┤ │ Task 5：PR / 文档（Agent 生成 + 人审） │ └─────────────────────────────────────────────┘ ``` **判断该用哪个工具，只看一个标准：** > 改动是否「重复、可测试、边界清晰」？是 → Agent 执行；否 → 人主导。 --- ## 十二、什么样的需求不适合这套流程？ 诚实说，不是所有需求都能 3 天变 1 天： | 不适合 | 原因 | |--------|------| | 架构从零设计 | 判断层太重，Agent 只能辅助 | | 需求模糊、反复变 | Agent 会反复返工，比人还慢 | | 无测试覆盖 | 没有自动验收，不敢放权 | | 强合规审批 | 必须人一步步确认 | **Agent 工作流的前提是：你把「模糊需求」先翻译成「清晰任务」。** --- ## 写在最后 这次需求让人更确信一件事： > **3 天变 1 天，靠的不是 AI 替你写代码，是你设计了一条 Agent 能跑完的流水线。** 做指挥官的 4 件事： 1. 定边界（改什么、不改什么） 2. 定验收（怎样算完成） 3. 定分批（每步可回滚） 4. 定人审点（哪些地方必须人看） Agent 做员工的 4 件事： 1. 扫代码、出计划 2. 批量改、跑测试 3. 失败了继续修 4. 产出 PR 草稿 下次接需求，先别问「AI 能不能做」，问： **「这件事能不能拆成带测试门禁的执行单元？」** 能拆，就值得走 Agent 工作流。不能拆，就老老实实人主导——这本身也是专业判断。