在 agent 写代码前框定任务
编码 agent 能很快完成清晰的任务，也能很快完成不清晰的任务。速度相同，代价不同。
类型： Learn + Build 语言： Python（标准库） 前置要求： 阶段 14 第 31 和 36 课 预计时间： ~60 分钟
学习目标
- 在编辑前把请求转成边界清晰的任务框架。
- 区分仓库事实、假设和未决问题。
- 定义允许路径、禁止路径和验收证据。
- 判断何时已完成足够的侦察，可以开始工作。
代价高昂的失败
“为重复邮箱加保护”听起来很具体，其实不是。唯一性应该放在 API、领域服务还是数据库？比较是否区分大小写？哪种错误形状已经是公开契约？允许迁移吗？哪项测试能证明行为？
有能力的 agent 会用看似合理的选择填补这些空白。这恰恰危险：实现可以干净、测过，却仍与系统不兼容。
因此，编码 agent 工作的第一单位不是一次编辑，而是由仓库证据支撑的任务框架。
任务框架
一个有用的框架包含六个字段：
| 字段 | 问题 |
|---|---|
| 目标 | 哪个可观察行为必须改变？ |
| 仓库事实 | 你在代码、测试、配置或历史中核实了什么？ |
| 允许路径 | 改动可以落在哪里？ |
| 禁止路径 | 哪些内容必须保持不动？ |
| 验收证据 | 哪些命令或观察能证明目标达成？ |
| 未知项 | 哪些决定仍需要证据或人工判断？ |
事实需要凭据。只有能指出既有测试或处理器时，“API 对重复项使用 409”才是事实。文件路径和行号已经足够；涉及行为时，命令结果更好。
flowchart LR
R[请求] --> I[检查仓库]
I --> F[有证据支撑的事实]
F --> B[边界明确的任务框架]
B --> D{未知项会阻碍设计吗？}
D -->|会| Q[询问或调查]
D -->|不会| P[规划变更]侦察是在寻找约束
不用读完整个仓库。搜索会约束这次改动的接触面：
- 当前行为及其调用方。
- 最接近的既有测试。
- 公开契约或序列化形状。
- 约束该路径的项目说明。
- 构建和验证命令。
- 能揭示本地模式的相似已完成改动。
当每个计划中的决定都有证据支撑、已被明确委托，或列为未知项时就停下。超过这个点继续阅读，往往是在回避行动。
未知项不是失败
未知项是受控的缺口；假设则是对这个缺口不受控的回答。
给每个未知项分类：
- 可发现： 仓库或运行中的系统能回答它。
- 可决定： 任务契约授予 agent 选择的权限。
- 人工： 这个选择会改变产品行为、成本、风险或公开兼容性。
- 延后： 选择不在这个切片内，属于非目标。
agent 应继续处理可发现和已委托的未知项。在某个选择被埋进代码前，遇到人工未知项就应暂停。
实现之前先写验收
在补丁之前写下证明。证明可以是：
- 聚焦的单元或集成测试命令；
- 指定视口和预期状态的浏览器旅程；
- 线上的请求与精确响应契约；
- 带阈值的性能测量；
- 确认没有无关文件改动的范围检查。
“测试通过”不是证明计划。写出权威测试及它支撑的断言。
动手构建
实验创建 TaskFrame，验证它的边界和证据，并写入 outputs/task-frame.md。
从本课目录运行：
python3 code/main.py
PYTHONPATH=code python3 -m unittest discover code/tests -v用四种方式破坏示例：移除目标、移除事实凭据、让允许路径和禁止路径重叠，以及移除验收命令。验证器应以不同理由拒绝每个框架。
在真实仓库中使用
让 agent 编辑前：
- 把目标写成行为，而不是文件改动。
- 记录两三条带精确证据的事实。
- 写出最小的允许路径集。
- 明确写出负空间。
- 写下闭合任务的命令或观察。
- 列出你尚未赢得答案的决定。
框架应能放进一屏。放不下时，任务可能含有多个可独立验证的改动。
练习
- 为你某个仓库的真实 bug 建立框架，但不要提出方案。
- 找出框架中实际上属于假设的一条主张，用证据替换它。
- 加入一个答案会改变公开契约的人工未知项。
- 把一个宽泛的允许路径拆成最小安全集合。
- 在验收证据中加入范围凭据。
延伸阅读
- Nuseibeh and Easterbrook, Requirements Engineering: A Roadmap，了解如何把实现锚定在现实目标和不断演变的约束上。
- Yang et al., SWE-agent: Agent-Computer Interfaces Enable Automated Software Engineering，了解编码 agent 周边接口如何影响其效果的证据。
拿去用
保留 outputs/task-frame.md。下一课会把它变成由证据支撑的执行计划。