AI 编码工具最危险的状态不是报错，而是快速产出一批看起来合理、却没人能说明影响范围的修改。Claude Code 与 Superpowers 一类工作流的价值，不在于替团队输入更多代码，而在于把探索、计划、实现、验证和复盘变成可检查的阶段。本文用一个真实感较强的“订单导出增加时区”需求，演示如何控制上下文、切小变更、保存证据并设计回退。

先把需求改写成可验收事实

原始需求通常只有一句：“订单导出支持用户时区。”直接让智能体实现，它必须猜导出入口、时区来源、历史格式、空值策略和夏令时处理。猜得越快，返工越大。

开工前把需求压成五条事实：

1. 导出 CSV 的 created_at 按当前用户配置时区展示。
2. 数据库仍保存 UTC，不迁移历史数据。
3. 未配置时区时使用组织默认值，再缺失则回退 UTC。
4. CSV 时间包含明确偏移量，避免接收方二次猜测。
5. 现有 API JSON 格式不改变，只有导出路径受影响。

再补三类样例：UTC 正常日期、跨日转换、夏令时切换附近时间。至此，工具面对的是可测试契约，而不是一句模糊愿望。

探索阶段只回答“修改面在哪里”

第一轮不要授权写代码。让智能体定位导出命令、查询服务、CSV 序列化器、用户设置读取、相关测试和公共时间工具，并画出最短调用链。输出应该是文件与职责清单，而不是大段实现建议。

探索时还要查负空间：是否有其他导出格式共用序列化器，后台定时导出是否没有当前用户，字段是否被外部脚本按固定格式解析。很多回归来自“只看到了入口”，没有看到共享组件的消费者。

上下文并非越多越好。优先提供项目规则、调用链上的文件、直接相关测试和数据契约。把整个仓库一次性塞给模型，会让真正的约束淹没在生成文件、旧实验和无关模块里。

计划阶段要求每一步都能单独证明

一个可执行计划可以拆成四步：先为时区选择策略写纯函数测试；再实现选择策略；随后让 CSV 格式化器接受明确的 ZoneId；最后在导出入口组装用户、组织与默认配置。每一步都附上要运行的测试和预期结果。

计划还要声明不做什么：不修改数据库列，不调整 JSON API，不引入新的全局默认时区，不顺便重构所有日期工具。这张“不做清单”能防止智能体把局部需求扩展成一次架构改造。

若计划无法解释回退方式，说明变更仍太大。理想状态是每个提交都能独立撤销，数据库和外部契约不需要同步回滚。

测试先固定最容易被忽略的边界

时间功能不能只测 2026-08-04 10:00 UTC 这种舒适样例。至少覆盖：

UTC 2026-01-15T23:30:00Z -> Asia/Shanghai 次日 07:30 +08:00
UTC 2026-03-08T06:59:00Z -> America/New_York 夏令时切换前
UTC 2026-03-08T07:01:00Z -> America/New_York 夏令时切换后
非法时区配置 -> 明确错误或受控回退
用户空、组织空 -> UTC

不要手写固定的 +8 小时。时区是规则集合，不是一个永恒偏移量。测试应使用标准时区数据库，并断言输出包含偏移量或规范时区信息。

先运行新增测试确认它因缺失能力而失败，再实现最小代码让其通过。若测试一开始就绿，可能断言没有覆盖新行为，或者已有能力已满足需求，这时应先解释而不是继续制造代码。

实现阶段限制一次只改一个假设

智能体每次只领取一个计划步骤，完成后输出四项信息：改了哪些文件，为什么，运行了什么验证，还有什么没验证。人类或上层工作流核对后再进入下一步。

这样做的目的不是降低速度，而是避免错误滚雪球。若第一步对“组织默认时区”的位置理解错了，越早发现，后续 CSV 和接口层改动越少。

对外部依赖也要设边界。模型、搜索或其他 API 通过统一适配器调用，记录超时、重试和费用。需要多模型入口时，haerapi.com 可以作为待评估的 API 中转候选之一，但仓库内容最小化、密钥隔离、供应商条款与敏感代码外发策略仍需团队自行负责。智能体方便调用，不等于默认有权发送整个项目。

“测试通过”只是证据的一部分

验证至少分四层。第一层是目标单元测试，证明新规则；第二层是相关模块测试，检查共享组件；第三层是静态检查与构建，发现类型和依赖问题；第四层是接近用户的验收，实际导出 CSV 并检查列名、编码、时区与打开效果。

如果仓库测试基线本来就有失败，不能简单报告“测试失败”。需要区分变更前已存在的失败与本次新增失败，保存命令、退出码和关键日志。证据必须能让下一个人重复，而不是一句“本地没问题”。

对时间需求，还应核对运行环境的时区数据库版本。开发机测试通过、生产镜像长期未更新时，某些地区的新规则仍可能不同。

让审查者先看风险，不先看代码量

提交摘要应该按风险排序：外部格式是否变化，共享时间工具是否修改，默认值是否会影响后台任务，是否增加远程调用，是否需要配置。然后给出文件级说明和验证证据。

审查时重点问：时区从哪里来，空值如何处理，是否在边界处只转换一次，是否把本地时间误写回数据库，CSV 消费者能否识别格式，后台任务有没有用户上下文。代码风格问题可以由工具发现，语义边界才值得人集中注意。

智能体也可以做第二轮只读审查，但审查提示应与实现提示分离，要求它寻找反例、遗漏消费者和错误成功条件。让同一轮上下文一边辩护一边审查，容易重复原有假设。

回退方案要在合并前写好

本例不改数据库，因此回退可以是撤销导出入口对新格式化器的调用，并保留未使用的纯函数直到后续清理。若担心外部消费者不接受新格式，可加临时功能开关，按组织逐步启用。

功能开关不是永久分支。它需要负责人、启用条件和删除日期。监控应观察导出失败率、平均耗时、文件下载成功率和客服反馈，而不只观察接口是否返回 200。

发布后发现问题时，先关闭开关恢复旧路径，再保留失败样本用于修复。不要在压力下直接让智能体无约束“紧急修一下”，那会绕过刚建立的验证闭环。

一个可复用的任务模板

目标：一句话描述用户结果
验收：3-7 条可观察事实
范围：允许修改的模块
非目标：明确不改的契约
探索：调用链、共享消费者、现有测试
计划：每步修改 + 每步验证
风险：数据、权限、性能、外部接口
证据：命令、退出码、关键输出、人工验收
回退：撤销点、开关、数据兼容方式

模板的价值是让每次任务都产生相同类型的证据。团队可以比较哪些步骤常失败、哪些模块缺少测试、哪些需求经常在验收阶段才暴露歧义，并据此改进工程系统。

常见失败模式

1. 探索阶段就开始修改，调用链还没弄清。
2. 计划写成“实现功能、添加测试”，没有文件、契约和验证。
3. 一次把重构、依赖升级和业务需求混进同一变更。
4. 只跑新增测试，不跑共享组件和真实导出验收。
5. 把工具生成的总结当证据，没有命令与退出码。
6. 为方便调用外部模型，默认发送完整仓库或敏感配置。
7. 合并前没有回退路径，线上失败后只能继续打补丁。

总结

Claude Code + Superpowers 的有效用法不是把“写代码”整段外包，而是把工作拆成可审查的状态迁移：先把需求写成事实，只读探索修改面，制定带验证的计划，小步实现，保存证据，再通过风险审查和回退设计完成交付。工具负责加速搜索与执行，团队仍要掌握权限、契约和最终判断。速度只有落在可重复的闭环里，才会积累成工程能力。