AI Agent / 系统课时
实施并验证功能
实施并验证功能
功能实现不是“让 Codex 改完文件就结束”,而是把计划转成可验证的小步改动:先确认验收标准,再修改代码、补测试、更新文档,最后用命令和差异检查证明结果成立。遇到失败时,重点是缩小问题范围,而不是跳过验证。
学习目标
- 把功能计划转换为代码、测试和文档三类可验收改动。
- 用“最小验证 → 完整验证 → diff 检查”形成稳定的交付闭环。
- 区分代码失败、测试环境失败和权限失败,并采用不同恢复方式。
从验收标准开始实施
开始前先把计划压缩成可判定的结果,例如“合法折扣返回两位小数”“非法百分比拒绝”“README 说明边界”。给 Codex 的任务也应同时包含允许修改的范围和必须运行的验证命令,避免它为了修复一个局部问题顺手扩大改动面。
Codex 的沙箱与审批机制意味着,普通工作区修改和越界操作应被区别处理;当任务需要额外网络、路径或其他高风险权限时,应让执行停在边界并说明原因,而不是把权限失败误判成代码失败。:contentReference[oaicite:3]{index=3}

用最小改动完成代码与测试
下面用一个独立的 Python 示例演示“实现 + 测试”的最小闭环。目标是实现折扣函数:金额不能为负,折扣百分比必须在 0~100 之间,结果统一保留两位小数。
pricing.py:
from decimal import Decimal, ROUND_HALF_UP
def apply_discount(amount: Decimal, percent: int) -> Decimal:
if amount < 0:
raise ValueError("amount must be non-negative")
if not 0 <= percent <= 100:
raise ValueError("percent must be between 0 and 100")
ratio = Decimal(100 - percent) / Decimal(100)
return (amount * ratio).quantize(Decimal("0.01"), rounding=ROUND_HALF_UP)tests/test_pricing.py:
import unittest
from decimal import Decimal
from pricing import apply_discount
class ApplyDiscountTests(unittest.TestCase):
def test_applies_discount_and_rounds_to_cents(self):
self.assertEqual(apply_discount(Decimal("19.99"), 15), Decimal("16.99"))
def test_rejects_negative_amount(self):
with self.assertRaises(ValueError):
apply_discount(Decimal("-1.00"), 10)
def test_rejects_invalid_percent(self):
with self.assertRaises(ValueError):
apply_discount(Decimal("10.00"), 101)
if __name__ == "__main__":
unittest.main()测试不是为了“证明代码已经写过”,而是把验收标准变成自动检查。若业务行为还会影响用户使用方式,应同步修改 README 或接口文档,至少写清输入边界、异常行为和一个正常示例;文档与测试应描述同一份契约。
例如 README 可以补上与测试一致的边界说明:
### Discount calculation
`apply_discount(amount, percent)` accepts a non-negative `Decimal` amount and
an integer percentage from 0 through 100. The result is rounded to two cents
using `ROUND_HALF_UP`. Invalid input raises `ValueError`.先跑最小验证,再跑完整验证
改动完成后,先运行与当前功能最相关的测试,确认局部逻辑成立;随后再运行完整测试、语法或静态检查,最后检查 diff 中是否混入了无关文件。Codex 本身也被设计为通过运行命令验证输出,但团队仍应把验证入口明确写进任务和项目规范。:contentReference[oaicite:4]{index=4}
python -m unittest discover -s tests -v
python -m compileall -q pricing.py tests
git diff --check预期输出
test_applies_discount_and_rounds_to_cents (test_pricing.ApplyDiscountTests.test_applies_discount_and_rounds_to_cents) ... ok
test_rejects_invalid_percent (test_pricing.ApplyDiscountTests.test_rejects_invalid_percent) ... ok
test_rejects_negative_amount (test_pricing.ApplyDiscountTests.test_rejects_negative_amount) ... ok
----------------------------------------------------------------------
Ran 3 tests in <TIME>s
OKcompileall -q 与 git diff --check 成功时通常不输出内容;实际测试耗时会不同。若项目还有 lint、类型检查、构建或集成测试,应继续运行仓库约定的完整入口,而不是只以这三个命令作为通用标准。
失败时按来源恢复
测试失败时,先重跑最小失败项并阅读断言、堆栈和实际值,再判断是实现错误还是测试假设错误。不要通过删除断言、扩大容差或跳过测试来制造“绿色结果”;修复后先重跑失败项,再回到完整验证。
如果失败来自缺少依赖、环境变量、数据库或外部服务,应先确认这是可修复的环境前置条件还是当前任务之外的基础设施问题。能够在当前范围内修复时,做最小环境修正并重新验证;不能修复时,保留失败证据并明确说明未完成的检查。
如果失败来自沙箱、网络或权限边界,不要自行把权限切到无限制。说明哪个命令、资源或域名被阻止,以及它为什么是完成任务所必需的;获得授权后只执行所需动作,然后回到原验证链。
交付前最后看一次 git diff:功能代码、测试和文档应共同指向同一验收标准,验证命令应全部通过,任何未运行的检查都要明确写出原因。这样得到的是一份可审查、可复现的功能实现,而不是一组“看起来已经改完”的文件。