制定由证据支撑的执行计划
计划不是更好看的待办清单。它是一张依赖图：每项改动都有理由，每个终点都有证明。
类型： Learn + Build 语言： Python（标准库） 前置要求： 阶段 14 第 43 课 预计时间： ~65 分钟
学习目标
- 把任务框架转为带证据和证明的工作项。
- 将顺序建模为依赖，而非散文式步骤。
- 在编辑前发现缺失事实、未知依赖和环。
- 区分可并行的步骤与必须等待的步骤。
为什么 agent 计划会失败
薄弱的计划只是用将来时复述请求：
- 更新 API。
- 添加测试。
- 更新文档。
这份列表没有说明发现了什么、为何这些文件正确、哪个契约应先变，或者哪些事可以并发。agent 即使遵循每一步，仍可能制造返工。
强计划为每个工作项作出五项承诺：
| 承诺 | 作用 |
|---|---|
| 标识符 | 用于依赖和交接的稳定引用 |
| 改动 | 最小的行为或契约变更 |
| 证据 | 证明改动合理的仓库事实 |
| 依赖 | 开始前必须成立的工作 |
| 证明 | 闭合该项的精确检查 |
先规划契约，再规划实现
多个接触面依赖同一行为时，先定义行为。测试、实现、文档和集成都能共享一个契约，而不是各自发明四个版本。
mermaid
flowchart LR
C[契约] --> I[实现]
C --> D[文档]
I --> G[集成门禁]
D --> G这张图显出安全的并发：契约固定后，实现与文档可以同时进行；集成要等两者完成。
证据会改变计划
仓库证据不是装饰，它应当有能力改变工作安排：
- 既有辅助函数取消了新增抽象的计划。
- 兼容性测试迫使你加入迁移步骤。
- 部署约束把 schema 变更移到另一项任务。
- 公开响应类型改变了实现和文档的先后顺序。
若证据不能改变计划，它大概不是这项决定的证据。
为中断而设计
编码 agent 会话可能意外结束。可恢复的计划应让工作项足够小，以便另一会话能确定：
- 哪一项已完成；
- 哪个证明已运行；
- 哪些产物已改变；
- 哪些依赖现在已解除；
- 下一项安全的工作是什么。
不要只把状态写在聊天中的勾选框里。把计划和工作放在一起。
计划验证
执行前遇到以下情况就拒绝计划：
- 标识符重复；
- 工作项没有证据；
- 工作项没有证明；
- 依赖指向未知项目；
- 图中存在环；
- 在相关不确定性解决前就发生第一项不可逆操作。
前五项是机械检查，最后一项需要判断，应该明确标出。
动手构建
code/main.py 对工作项建模，验证凭据，使用拓扑排序计算执行波次，并写入 outputs/evidence-plan.json。
运行：
bash
python3 code/main.py
PYTHONPATH=code python3 -m unittest discover code/tests -v示例会产生三个波次：先定义契约；实现和文档同时进行；最后是集成关卡。
与编码 agent 一起使用
要求 agent 在改文件前产出计划，从三个方面审阅：
- 每条路径和行为主张都有仓库凭据。
- 每一项都有一个清晰的完成证明。
- 图会把昂贵或不可逆的工作推迟到它依赖的不确定性解决之后。
批准这份计划，而不是一句含糊的“我会小心”。
练习
- 加入一项需要明确人工批准的迁移工作。
- 制造一个环，并解释其背后隐藏的产品分歧。
- 拆分一个带两条证明命令的工作项。
- 添加一个可在第二波运行、且不触碰任一既有分支的工作项。
- 在保持 JSON 为真相源的前提下，把计划渲染为 Markdown。
延伸阅读
- Nuseibeh and Easterbrook, Requirements Engineering: A Roadmap，了解目标、规格、协商与演进之间的迭代关系。
- Barry Boehm, A Spiral Model of Software Development and Enhancement，了解围绕风险消解而不是固定线性顺序安排开发。
拿去用
保留 outputs/evidence-plan.json。下一课会把它作为委派契约。