把一项失败测试转成有明确边界的智能体请求

提供精确输入、断言、相关实现，以及证明预期结果正确的需求依据，失败测试就能为编程智能体提供有用的起点。在修改实现或断言之前，先让智能体检查：究竟是哪一方与需求不符。

Python 的 Python 3.13 unittest 文档将测试用例描述为：检查特定输入是否得到特定响应。它的 assertEqual 方法检查两个值是否相等。断言说明测试期望什么；需求依据则说明这项期望是否合理。

将需求放在失败用例旁边

本文使用一个虚构的预订显示函数。需求、文件、输入和测试都是原创教学示例。选定的教学运行时为 Python 3.13。没有执行任何示例，文章也不包含捕获的失败输出或测试通过输出。

给定的产品说明 AV-2 规定：

remaining_slots(capacity, booked) 返回仍然空余的名额数量。
范围内的输入为非负整数。
如果 booked 小于 capacity，返回 capacity 减去 booked。
如果 booked 等于或大于 capacity，返回零。
这是显示计算，不是创建预订的权限。

availability.py 中的实现是：

def remaining_slots(capacity, booked):
    return max(capacity - booked, 1)

tests/test_availability.py 中的相关测试是：

import unittest
from availability import remaining_slots


class AvailabilityTests(unittest.TestCase):
    def test_full_capacity_has_no_open_places(self):
        self.assertEqual(remaining_slots(4, 4), 0)

人工计算可知，对 (4, 4)，capacity - booked 为零，而所示函数会选择零和一中的较大值。因此它应当返回一，但断言期望零。这是预测的断言失败，不是已记录的运行。

这里，测试期望与 AV-2 一致。实现把下限设为一，是需要调查的具体分歧。请求可以明确指向这项边界，而不授权改变预订创建、存储或周边界面。

沿同一需求检查两个分支

单凭测试变红，无法决定哪个文件错了。用同一需求检查两种可能情况。

分支 B 是另一种示例，不是应当加进分支 A 的第二项测试。其中有冲突的断言会是：

# Alternative scenario only: this expectation conflicts with AV-2.
self.assertEqual(remaining_slots(4, 4), 1)

也许有人曾想显示“至少一个名额”，或把错误示例复制进了测试。这种说法不是证据。如果当前需求仍是 AV-2，期望一就没有依据。如果更新的权威需求与 AV-2 矛盾，应先确定适用哪项需求，再改变行为。

这个区别能避免两种相反错误：为了满足错误断言而改变正确代码，或为了迁就错误代码而削弱有效断言。

用几个边界用例定义修复

分支 A 的候选修正是：

def remaining_slots(capacity, booked):
    return max(capacity - booked, 0)

以下预期通过人工推理由 AV-2 得出：

这些是针对具名函数选定的边界。它们不覆盖应用的全部行为，也不为负值、字符串、小数、并发或预订授权引入需求。

保留原先针对恰好满额的断言。只在新增聚焦用例能检查规则中有意义的部分时，才添加它。例如：

class AvailabilityTests(unittest.TestCase):
    def test_full_capacity_has_no_open_places(self):
        self.assertEqual(remaining_slots(4, 4), 0)

    def test_over_capacity_never_displays_negative_places(self):
        self.assertEqual(remaining_slots(4, 5), 0)

    def test_one_place_left_is_preserved(self):
        self.assertEqual(remaining_slots(4, 3), 1)

    def test_zero_capacity_has_no_open_places(self):
        self.assertEqual(remaining_slots(0, 0), 0)

    def test_no_bookings_leave_capacity_open(self):
        self.assertEqual(remaining_slots(4, 0), 4)

这是同一测试模块中一个用于说明的替换类，使用上方已有的导入。添加重复项之前，必须先在实际仓库核实这些断言是否已存在于其他位置。

复制这份完整修复请求

依据需求 AV-2，修复 availability.py 中的 remaining_slots。

需求 AV-2：
范围内的输入为非负整数。booked 小于 capacity 时返回 capacity 减去
booked；否则返回零。函数只计算显示数量，不授权创建预订。

当前实现：
def remaining_slots(capacity, booked):
    return max(capacity - booked, 1)

tests/test_availability.py 中的现有断言：
self.assertEqual(remaining_slots(4, 4), 0)

失败状态：
人工推理预测实际值为1、预期值为0。本例没有提供终端运行。
检查当前仓库，不要声称这里已经复现了故障。

首先：
确认当前实现与断言。检查是否有更新的需求替代 AV-2。
带文件引用说明：是实现还是预期值与适用需求冲突。

允许编辑：
仅 availability.py 与 tests/test_availability.py。
保留函数名、参数顺序、范围内输入的返回类型，以及现有正确预期。
保留恰好满额的测试。

需要检查的行为：
(4,0)->4; (4,3)->1; (4,4)->0; (4,5)->0; (0,0)->0.
已有覆盖时复用它。添加聚焦的遗漏用例，
不修改无关测试，也不替换测试框架。

范围之外：
预订写入、数据库规则、界面重新设计、并发、依赖、
对契约外输入新增校验或类型转换行为，以及发布。

在获授权的开发环境中验证：
使用仓库文档规定的测试命令。给定教学目录结构提示可从根目录执行
python -m unittest discover -s tests；
运行之前，先核实它是否符合实际项目。

返回：
小范围 diff；需求到变更的解释；实际运行的精确命令与结果，
或明确的未运行原因；剩余缺口。绝不把人工求值写成测试运行。
如果权威需求缺失或冲突，先报告冲突，再考虑改变预期值。

分开记录推理与执行

智能体可以在没有复现问题的情况下，解释一项可能的一行修正。只要交付说明完成的是哪个阶段，这仍是有用分析。已记录的测试通过会为选定用例增加证据，但不能证明每个预订流程都正确。

接受补丁之前，先将其行为与 AV-2 比较，再阅读测试结果和剩余缺口。如果一项有效的需求断言消失了，或没有需求变更却改变了预期值，原问题可能只是被隐藏，而非修复。

在 CueSpec 会话步骤中，发出修复请求之前先阅读最新回答。将精确断言和需求文本与任务放在一起，避免口述解释取代数字或边界条件。