实战：从一句需求到功能上线
系列入口：如何使用 Agent。本篇是 M9 场景实战第 1 篇，综合运用 M0–M8 的方法。
一、场景设定
需求来自群里的一句话："导出报表时，希望能勾选只导出某个时间范围内的数据。"——模糊、口语化，没有说默认范围、格式、权限，也没说要改哪些文件。这种需求如果直接丢给 Agent 让它"开干"，大概率得到一个做了一堆假设、还漏了边界的结果。
下面按真实节奏走完它，分五个阶段：澄清与规划 → 建基线 → 分步实现 → 验收与修正 → 提交发布。每个阶段都标出人做什么、Agent 做什么。
二、阶段一：澄清与规划（不要急着写代码）
第一步不是打开编辑器，而是先用 Plan 模式让 Agent 帮你把模糊需求变成清晰方案，而不是直接产出代码。
你可以这样开场："需求是给报表导出加时间范围筛选。先不要改代码，请先调研：导出功能现在在哪几个文件、参数怎么传、有哪些调用方；然后列出需要澄清的问题和你的初步方案。"Agent 会去读代码，回一份调研 + 待澄清清单。这一步你要亲自把关的是澄清项，典型包括：
- 默认时间范围是什么（最近 30 天 / 全部 / 必填）？
- 时间用什么格式、含不含边界、时区怎么处理？
- 有没有权限或数据范围限制（用户只能看自己的数据）？
- 旧的调用方不传新参数时行为如何，要不要保持兼容？
把这些问清楚（必要时回去问提需求的人，而不是让 Agent 替业务拍板），再让 Agent 输出一份具体实施计划：改动文件清单、每处改动、测试计划、风险点。计划必须经你确认后再进入实现——这是你是驾驶员的核心体现，也是最便宜的一次纠偏机会。
三、阶段二：建基线与分支
确认方案后、让 Agent 动手前，先建好安全网。
建一个独立的 feature 分支，并确认工作区干净，作为本次工作的基线；随后约定每完成一个有意义的小步就提交一次检查点。这样一旦某步走偏，可以轻松退回上一个干净节点，而不是在一团乱麻里挣扎（详见 Git 快照与回滚）。
可以让 Agent 在实现时也遵循这个节奏：每完成一个小步、测试通过后提示你验收，而不是一口气改完几十个文件才交付。分支 + 检查点把"一次性巨大终审"变成了"一连串可回退的小确认"。
四、阶段三：分步实现，测试先行
实现阶段让 Agent 按计划拆成小步推进，而不是一次性铺开。
一个合理顺序是：先打通参数接收与传递，再实现筛选逻辑，最后处理默认值、边界和兼容。 每一步都尽量测试先行：让 Agent 先写一个能描述期望行为的测试（此时应失败），再写实现让它变绿。对本需求，至少要覆盖：正常区间、含边界时刻、默认 30 天、不传参数的兼容、越权范围、非法日期。
每完成一小步，做轻量验收并提交检查点。这里要特别警惕 Agent 的两个老毛病：一是为了快而写"返回 200 就行"的空泛测试；二是顺手"统一"改掉无关的公共方法。这两点都要在每步的 diff 里盯住。宁可小步多确认，也不要等几百行后才发现早期方向错了。
五、阶段四：验收与打回修正
全部小步完成后，做一次整体验收，顺序沿用 如何验收产出。
先对需求：最初确认的每条（含默认 30 天、时区、权限、兼容）是否都有对应代码和测试。再读全量 diff：确认没有越界改动、删除合理、改动对症。然后跑全量测试、构建和 lint，并用"故意改坏一处看测试是否变红"抽查新增测试是否真有效。最后回源核对它声称复用的函数、改动的调用方是否属实。
发现问题时，打回要具体、可验证、限定范围，例如："默认范围当前是全部，应为最近 30 天；请修改并补一个能区分二者的测试，改完跑全量。"打回回来后重新验证，留意它为修 A 是否碰了 B。反复出现的同类问题，当场写进项目规则或验收清单，让它下次不再犯。
六、阶段五：提交、发布与上线观察
验收通过后，把零散的检查点整理成清晰的提交（必要时 squash 成一个可读的 feature 提交），写清"做了什么、为什么、有无兼容/配置变更"，然后走团队正常的评审与发布流程——Agent 不能替代人对合并和上线的审批。
上线后做一小段观察：导出功能的报错、超时、用户反馈是否异常，筛选后的结果量是否符合预期。准备好快速回滚方案（保留旧逻辑或开关），万一新参数在真实大数据量下引发性能问题，能立即撤回。发布不是终点，确认"线上行为确实如预期"才算真正完成。
七、中途最容易跑偏的几个时刻
走完一遍后回看，这个需求真正危险的不是技术难度，而是几个"想当然"的时刻，提前知道它们能少走弯路。
一是时区与边界。 "最近 30 天"听着简单，但 stored 时间是 UTC、用户按本地时区理解，边界那一瞬含不含当天，直接决定结果差一天。这类问题在你自己写代码时会意识到，交给 Agent 反而容易被它用一个"标准做法"悄悄带过——所以澄清时刻必须把时区和边界写死。二是权限收窄。 导出功能原本就有"用户只能看自己数据"的约束，新加的时间筛选若绕过了原有过滤，就可能让用户借参数看到不该看的数据。Agent 关注的是"把新功能做出来"，对这种已有的横切约束未必敏感，需要你提醒它复用而非另起。
三是大数据量性能。 时间筛选若让数据库对时间列做函数运算（如对索引列套函数），会导致全表扫描，在真实大表上超时。这在测试的小数据集上完全看不出来。四是旧调用方。 别处可能也调用同一个导出方法，新增参数后它们不传时的默认行为必须兼容，否则一个"内部小改动"会波及没测到的入口。这四个时刻的共同点是：局部、当下、小数据上都正确，问题只在真实约束下才暴露，也正是它们必须进澄清清单和最终验收的原因。
八、这一流程里人的判断点
| 阶段 | 人不可让渡的判断 |
|---|---|
| 澄清规划 | 业务规则（默认范围、权限）拍板、方案确认 |
| 建基线 | 分支策略与回退点 |
| 实现 | 测试是否有效、有无越界、方向是否正确 |
| 验收 | 需求覆盖、事实核对、是否放行 |
| 发布 | 合并审批、上线决策、异常时回滚 |
Agent 承担的是调研、样板实现、写测试初稿、整理提交等"加速"工作；所有需要理解业务意图和承担后果的节点，始终由你把控。
八、常见问题
Q：需求很小，也要先走 Plan 吗？ 按风险伸缩。一两行、低风险、你完全清楚怎么改的，可直接做；但凡涉及业务规则不明、跨多个文件或影响公共接口，先花几分钟 Plan，收益远大于成本。
Q：Agent 老是漏需求怎么办？ 在 Plan 阶段就把澄清结论固化成一份明确的需求条目清单，让它实现与验收时逐条对照；把高频遗漏点写进规则。
Q：检查点提交太碎，最后难看怎么办？ 实现期可以频繁提交以保安全，合并发布前再整理（squash/rebase）成干净的历史，安全与整洁并不冲突。
Q：上线后真出问题，第一反应是什么？ 先按预案回滚或关开关止血，再用日志复现、按调试闭环定位，避免在线上边改边试。
九、把这次经验复用给下一个需求
走完这个需求后，最有价值的动作是把它沉淀成下次能直接复用的资产，而不是让经验只留在记忆里。
具体可以做三件事：把澄清问题模板化——这次问的默认范围、时区、权限、兼容、性能，几乎是任何"给查询加筛选参数"类需求的通用清单，存成一个斜杠命令或需求核对模板，下次开场直接用，避免重复遗漏。把验收标准固化——"筛选逻辑必须有能区分命中与不命中的测试""不得修改未涉及的公共方法"这类本次靠人工盯的点，写进项目的验收清单或 AGENTS.md，让 Agent 下次默认遵守。
把踩坑做成回归样本——如果中途确实发现过时区或权限的偏差，把它补进评测/回归集，确保以后不复发。这样，每完成一个需求，整个"人 + Agent"的协作系统就聪明一点：下一个同类需求从澄清到实现到验收都会更快、更稳。这也正是本系列反复强调的闭环——单次交付是结果，把结果转成可复用的规则和模板，才是能力的累积。
十、用对话记录还原一次真实交互
为了让流程更可感，下面还原几段关键对话，展示人在每个节点实际说了什么。
开场（Plan）："需求：报表导出支持时间范围筛选。先别改代码。请先找出现有导出逻辑的位置、所有调用方，并列出你需要我澄清的问题。"——刻意压制它立刻动手的冲动。澄清："默认最近 30 天，按用户本地时区、含起始不含结束；必须叠加现有的数据权限过滤；旧调用方不传参数时保持原行为。请据此给出实施计划，等我确认。"——把业务规则一次讲清、并显式保留审批。
实现指令："按计划分步做。每步先写测试再实现，完成一步停下让我看，不要改与本需求无关的公共方法。"——用约束预先堵住越界和假绿。验收打回："第 3 步默认范围仍是全部，与约定不符；另请说明为什么改了另一个导出方法的签名。先修默认值并补测试，其余不要动。"——具体、限定、要求解释。收尾："跑全量测试和构建，整理成一个提交，信息里写明默认行为和兼容性。"——把最后把关握在手里。这组对话的共同特点是：人始终在给目标、划边界、做确认，而 Agent 只在被划定的范围内加速，这正是"驾驶员"的具体操作含义。
十一、性能与安全的最后确认
发布前有两件在测试小环境里查不出来、却最可能在生产惹祸的事，要单独确认。
性能：让 Agent 解释筛选查询在真实大表上的执行计划——时间列是否走索引、有没有对索引列套函数导致全表扫描、返回大数据集时是否需要分页或上限。必要时在预发用生产量级数据验证导出耗时与内存。安全：确认新参数无法被用来绕过原有的数据权限、构造非法区间，输入经过校验、错误被妥善处理。这两项都属于"代码正确但上线出事"的典型，靠功能测试抓不到，必须以真实规模和攻击者视角再过一遍。
十二、出现这些信号就暂停
推进过程中若出现以下信号，应停下来重新对齐，而不是硬着头皮继续：需求条目 Agent 反复遗漏、diff 不断越界、测试改坏了也不红、它的关键论断在代码里查无实据、或它开始频繁"猜"。这些都说明方向或上下文出了问题，继续只会放大返工。暂停、补充材料、重述约束，往往比将错就错更快。
十三、回退不是失败而是常规选项
很多人不愿建回退预案，是潜意识里把"用回退"当成方案失败；但在端到端实践中，回退是让你敢于快速前进的安全装置，应被当作常规选项而非耻辱。
发布前就准备好开关或保留旧逻辑、明确触发回退的客观条件（错误率、超时、业务异常超阈值），并让回退动作足够简单、一个人能执行。上线后一旦命中条件，先回退止血、再离线复现修正，而不是在线硬撑。正因为退路便宜，你才敢更频繁、更小步地交付——回退预案的存在本身就在提高你的迭代速度，而不只是兜底。 把这种心态立起来，整条"规划—实现—发布"的主线才真正闭环：进可快速推进、退可立刻收手，主动权始终在人手里。
十四、检查清单
- 已澄清默认值/时区/权限/兼容，方案经确认。
- 已建分支与基线，约定分步检查点。
- 测试先行，覆盖正常/边界/默认/兼容/越权。
- 已对需求、读 diff、跑全量、回源核对，打回有复验。
- 提交信息清晰，走正常评审发布，有回滚预案与上线观察。
总结
把一句模糊需求做成上线功能，正确节奏是"先慢后快"：用 Plan 模式调研、澄清业务规则并由人确认方案，建好分支基线，再让 Agent 按小步、测试先行地实现，每步轻验收、最后整体读 diff 并回源核对，问题具体打回、经验沉淀进规则，最后走正常审批发布并做上线观察与回滚预案；Agent 负责加速，人始终守住业务判断和所有要承担后果的节点。