用 Claude Code 实战 Python · 第 02 题 · English

第 2 课：动手之前先写任务契约

检查点 l0210 分自我报告——认领码来自 verify.pyClaude Code 2.x

把"优化一下"变成有边界、可测试的契约——这是与编码 Agent 协作杠杆最大的一项技能。

在用 Agent 做题？一句话开始整门课程：

Read https://flypython.com/skills/flypython/SKILL.md and start the FlyPython course `hands-on-python-with-claude-code`.

第 2 课：动手之前先写任务契约

目标

你能把 TASK.md 读成一组可测试的陈述，把每条陈述对应到 tests/test_report_tool.py 中的测试，并用仓库的任务契约模板为自己的项目写出一条契约。

为什么要有这一课

模糊的需求产出模糊的代码。“把坏数据处理得稳一点”是在允许 Agent 猜； “无效行收集进 errors，带 index 和 reason，有效行照常出报告”既给了它目标，也给了你验收方式。契约是你决定”完成”含义的地方——要在 Agent 用一次看似合理的重写消耗掉你的信任之前决定。

课程内容

打开 TASK.md。注意每一行的共同点：它描述可观察的行为，而不是实现方式。契约中的四条陈述及其锚定测试：

契约陈述	锚定测试
JSON 数据文件按对象列表加载	`test_load_json_records_returns_list_of_dicts`
不支持的扩展名抛出 `ValueError`	`test_unsupported_suffix_raises_value_error`
无效行以 `{"index", "reason"}` 隔离；有效行照常汇总	`test_invalid_records_are_isolated_with_reasons`
分组总计保留两位小数	`test_group_totals_are_rounded_to_two_decimals`

再注意边界条款——说明变更”不可以”做什么的行：不新增依赖、只改 starter/report_tool.py、只用标准库。边界条款的作用，是防止 Agent 出于”帮忙”的重写吞掉你的整个文件。

完整模板在配套仓库（templates/TASK_CONTRACT.md）。字段包括：用户结果、当前行为、期望行为、输入输出、允许触碰的文件、明确不做的事、失败与恢复、验收命令、权限（网络/提交/推送）。你留空的每个字段，都是你交给机器替你做的决定。

练习

下一个契约由你自己来写，小而真实：

选一个你真正拥有的脚本（报表、爬虫、同步任务）。
按上面的表格形式为它写三条契约陈述——写行为，不写实现。
为每条陈述写出锚定它的测试名。
加一条边界条款（Agent 不可触碰的文件，或不可新增的依赖）。

让 Agent 参照 TASK.md 点评你的契约——它应该找出歧义，而不是加功能。

检查点

把你的四行内容给 Agent 看，问：“这几条里哪一条你能靠作弊满足——测试过了但行为没做到？“如果你们都找不到作弊路径，契约就足够具体。修掉任何没通过这一关的行。

预期证据

你的契约（4 行）和作弊评审结果。第 3 课中 Agent 只按课程的 TASK.md 编码——你自己的契约在第 5 课投入使用。

提示

卡住了？逐条打开。

提示 1 —— 这个检查点考什么

考你能不能把 TASK.md 读成可测试的语句而不是散文。每个以函数名开头的句子都是套件能断言的契约行。

提示 2 —— 把一行契约对到一个测试

挑一行契约——比如 total = valid + invalid must hold——在 tests/test_report_tool.py 里找到断言它的测试。然后为你自己的一个脚本写一行契约：输入、输出、错误路径，以及『完成 = 某命令退出 0』。

提示 3 —— 可测试性检查

判断一句话是否可测试：套件能否不读你的心思就断言它？看数字、退出码、磁盘上的文件——不看感觉。

提交

做完了？记录它。

提交 verify.py progress 为本检查点打印的 8 位认领码——浏览器里交，或让你的 Agent 直接交。

你浏览器

提交认领码

你的 Agent自动提交

让 Agent 解题并自动提交

把这题交给它（悬停出现复制按钮）——解题、验证、提交全程自动：

请完成 FlyPython 挑战课程「用 Claude Code 实战 Python」（course id course-claude-code）的检查点 l02。
机读简报：https://flypython.com/api/challenges/hands-on-python-with-claude-code
打开课程文件夹，先读 TASK.md——它就是契约。
规则：最小变更、不新增依赖、绝不修改 tests/ 或 solution/。
用 python verify.py 检查直到门控通过，把每个认领码告诉我。
目标：只做检查点 l02 这一道题，完成后立即提交。

用你Agent 页生成的令牌（环境变量 FLYPYTHON_TOKEN），它可以直接记录结果：

curl -X POST https://flypython.com/api/claims \
  -H "Authorization: Bearer $FLYPYTHON_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"claims":[{"course":"hands-on-python-with-claude-code","checkpoint":"l02","code":"<8-char code>"}]}'

或一次性安装完整的 FlyPython Agent Skill，连粘贴都省了。

官方示范 · Pro

看一个真人怎么带 Agent 做这道题

本检查点的官方示范——任务契约怎么交、什么时候叫停 Agent、未剪裁的失败纠正、verify.py 过闸全程。含在 Pro 内；无免费试看，题目本身仍免费。

打开示范（Pro）→

文件

starter 与验证器

解题在你的机器上运行——Agent 通过 /api/challenges/hands-on-python-with-claude-code/files 自己取回课程文件，你无需手动下载。想直接读源码？在 GitHub 上查看文件夹 ↗