第 5 课：把这套方法带回你自己的项目

第 5 课：把这套方法带回你自己的项目

目标

选一个你真实拥有的脚本，写下它的任务契约（第 2 课的练习），并把本 课程中最小可用的一片迁移过去——附测试、一条验证命令，以及一份说明 测试没证明什么的记录。

为什么要有这一课

课程项目是宽容的：数据小、测试现成、契约替你写好。回到你的项目， 习惯要么迁移过去，要么蒸发掉。迁移成功的关键是收缩范围：一个脚本、 一份契约、一个从红变绿的测试——不是一次重写。

课程内容

1. 选脚本。 选一个你反复运行、而且一直有点心里没底的。不是最大 的那个——是最烦人的那个。
2. 写它的契约（第 2 课练习）：三条行为陈述、一条边界条款、一条 验收命令。
3. 为最吓人的那条契约线加一个失败测试。 照抄 tests/test_report_tool.py 的形状——输出用 tempfile、数据内联、 一个行为一个断言。
4. 让 Agent 按第 3 课的规则让它通过： 最小变更、展示 diff、拒绝 顺手重构。
5. 写验证记录（第 4 课）：已验证 / 未验证 / 已知局限。

迁移哪种模式，取决于你脚本真实的故障方式：

如果你的脚本……	迁移本课程的这个模式
一行坏数据就崩溃	以 {"index", "reason"} 收集的错误隔离
打印出 0.30000000000000004	在聚合边界做两位小数舍入
中断时留下写了一半的输出	临时文件 + os.replace 的原子写入
混用两种输入格式	一个加载器 + 明确拒绝不支持的类型
没有办法说”完成”	验证命令：失败的 starter + 可达的目标

验证不能证明什么

同样要看清局限，因为夸大测试的作用只会让项目受伤：

• 测试通过证明的是”被锚定的行为在测试输入上成立”——不等于明天的 数据也对，更不等于其他地方没有 bug。
• 全绿的套件不能说明生产规模文件下的性能，也不能阻止上游系统下个月 改表结构。
• 仓库的测试不等于你的结果。你的结果是一个用户可见的行为（一份正确 的报告送达、一次崩溃被消除），测试只是证据。完整框架请阅读配套 指南”Use Python Well with AI Coding”与产品质量指南（flypython.com 或仓库 guides/ 目录）。

练习

交付这一小片。在项目的干净检出（或同事的机器）上运行你新的验收 命令，确认能复现相同结果。如果不行，说明命令依赖你的机器——修命令， 不要找借口。

检查点

你的项目现在拥有：一份书面契约、一个曾经失败现在通过的测试、一条 能同时演示两者的命令、一份三行验证记录。这就是整门课程压缩进你 代码库的样子。

预期证据

契约、测试输出记录、验证记录。如果这套工作流对你有用，课程落地页 列出了下一步去向——教学偏差请通过 course-feedback issue 表单反馈。