AI 编程任务动手前如何设置范围闸门

“帮我修一下支付页面”之类的请求缺少行为目标、允许修改的范围和完成证据。编程 Agent 只能自行补全这些空白，于是一次局部缺陷可能演变成接口调整、依赖升级或无关重构。等方向被证伪后，再要求它撤回改动，既难确认是否恢复完整，也会掩盖原始问题。更稳妥的流程是在写文件前设置范围闸门：先用只读证据形成计划，明确禁止变化与验收命令，再允许最小修改。本文给出可直接套用的任务合同和检查步骤。

任务合同只需要五部分

开始前写清：

目标：最终要改变的可观察行为
范围：允许读取和修改的目录或模块
证据：复现步骤、首个错误和相关环境
约束：不能改变的接口、数据或依赖
验收：证明行为变化和回归安全的命令

例如：

目标：空用户名提交时返回现有的必填错误，不进入数据库查询。
范围：认证入口及其测试；可读取相邻验证模块。
证据：目标测试当前失败，实际进入查询函数。
约束：不修改公共响应结构，不新增依赖，不改数据库迁移。
验收：新增回归测试先失败；修复后目标测试与认证测试集通过。

任务合同不是实现方案。它限定问题和完成条件，根因仍需通过代码和测试确认。

第一闸门：计划阶段只读

计划阶段允许读取相关文件、搜索符号和运行不会改变仓库状态的诊断命令，不允许编辑文件。计划应回答：

• 原始现象是否能够复现；
• 哪些事实已经由代码或命令确认；
• 有哪些候选根因，各自需要什么证据；
• 最小修改可能涉及哪些文件；
• 将先写哪条失败测试；
• 哪种结果会要求停止并扩大调查范围。

若计划直接把猜测写成根因，或没有复现原始问题，不应进入实施。

第二闸门：检查修改范围

动手前逐项检查：

每个计划修改的文件是否直接服务于目标？
是否打算更改任务合同中禁止的接口？
是否包含“顺便”重构、升级或格式化？
测试能否在没有实现时因目标行为缺失而失败？
验证是否同时覆盖原始问题和相邻回归？

发现范围不足时，可以先扩大读取范围，但不能默认扩大写入范围。若根因确实位于范围外，报告证据和拟新增文件，由负责人重新确认合同。

第三闸门：先观察测试失败

修复或新增行为前，先编写一条最小测试并运行。合格的 RED 证据包括：

执行命令
退出码
失败用例名
预期值与实际值
失败确实来自缺失行为，而不是语法或环境错误

如果测试立即通过，说明它没有覆盖目标缺陷，应调整测试而不是开始实现。如果测试因依赖缺失报错，先修复测试环境，不能把错误当作行为失败。

第四闸门：每次只实施一个行为变化

实现应以通过当前失败测试为边界。不同时升级依赖、重命名模块或统一代码风格。实现后先运行目标测试；通过后再运行相关测试集，最后执行任务合同要求的全量验证。

验证失败时，根据首个相关错误回到定位阶段。不要连续尝试多个修复后只在最后看结果，否则无法确定哪项改动有效。

第五闸门：审查差异而不是相信摘要

完成修改后检查版本控制差异：

• 修改文件是否都在批准范围；
• 是否存在无关格式变化或生成文件；
• 是否删除了原有错误处理或日志；
• 新测试是否能在撤销实现时重新失败；
• 配置、密钥和调试输出是否意外进入差异。

Agent 的文字总结不能替代实际差异。若发现跑偏，先确认已发生的修改，再决定逐项修正或从已知检查点恢复。

给长任务设置证据检查点

在根因确认、多文件修改、数据迁移、外部操作和最终交付前暂停，记录：

当前结论及证据
下一步将修改的文件
预期行为变化
将运行的验证命令
仍未覆盖的风险

检查点应保存在任务记录中，而不是只留在会话历史。中断后可以从最近一个已验证状态继续。

可直接使用的开场模板

目标：[唯一的可观察行为变化]
范围：[允许读取和修改的路径]
证据：[复现步骤、失败命令和错误摘要]
约束：[禁止改变的接口、依赖、配置或数据]
验收：[目标测试、相关回归和全量验证]

执行约束：
1. 先只读调查并复现问题。
2. 区分事实、假设和待验证项。
3. 提交最小计划，列出拟修改文件，等待确认后再编辑。
4. 先添加并运行失败测试，再做最小实现。
5. 每个检查点报告实际命令和结果。
6. 最后审查差异并列出未覆盖限制。

结论与限制

范围闸门把 AI 编程从“先改再看”变成证据驱动流程：任务合同定义边界，只读计划验证根因，失败测试证明目标，差异审查确认没有越界。它不能消除错误，但能让错误更早暴露并停在较小改动范围内。

本文不依赖特定编程 Agent 的计划、检查点或回滚命令。不同工具能否阻止写入、保存会话或恢复文件需要依据当前版本验证；涉及不可逆数据和外部系统时，仍应由独立权限与备份机制控制。