冲刺合同与增量式进度

Sprint Contracts (迭代契约) 与增量式进展

“一键式”陷阱：为什么 AI Agent 在处理大型任务时会失败

如果你让一个自主 AI Agent “构建一个全栈电子商务应用程序”，它几乎肯定会试图一次性完成所有工作。这种现象被称为“一键式陷阱”（One-Shot Trap）。Agent 会试图在一次庞大的输出流中同时生成数据库模式（schema）、前端 React 组件、后端 API 以及 CSS 样式。不可避免的结果是什么？一个混乱、充满幻觉且无法编译的半成品代码库。

可以把它想象成雇佣建筑工盖房子。如果他们试图同时进行浇筑混凝土基础、布线和粉刷墙壁，项目注定会以灾难告终。为了构建健壮、长期的应用程序，你的 Harness（脚手架/支撑系统）必须强迫 AI Agent 放慢速度，将工作分解为可管理的片段，并进行增量式开发。

引入 Sprint Contracts

为了人为地限制 Agent 的野心，我们使用一种称为“Sprint Contract”（迭代契约）的技术。在编写任何功能代码之前，Harness 要求达成一份正式的、结构化的协议，详细说明接下来要构建的原子化、小规模的功能片段。

这份契约充当了生成器（Generator，即编写代码的 Agent）与评估器（Evaluator，即审查工作的 Agent）之间的约束协议。一个稳固的 Sprint Contract 基于三个核心支柱：

严格的范围限制 (Strict Scope Limit)：对功能进行紧密限定的描述（例如：“仅创建用户登录 UI 组件，不连接后端认证 API”）。
具体的验收标准 (Concrete Acceptance Criteria)：一份布尔条件列表，必须全部满足才视为功能完成。
验证计划 (Verification Plan)：评估器将运行的确切终端命令或自动化测试，以机械地证明代码按预期工作。

协商阶段

Sprint Contract 的真正魔力在于协商阶段。在一个设计良好的多 Agent 架构（Multi-Agent Architecture）中，规划器（Planner）或生成器会起草初步契约。然而，在评估器 Agent 明确批准之前，它不能进入执行阶段。如果评估器认定范围太广或验收标准过于模糊，它会提出反对意见并要求修改。

以下是该契约结构在底层可能是的样子（以 JSON 格式表示），Agent 使用此格式进行协商：

{
  "sprint_id": "spr_004",
  "focus": "实现电子邮件验证工具",
  "scope": {
    "included":[
      "针对标准电子邮件格式的正则表达式验证",
      "验证逻辑的单元测试"
    ],
    "excluded":[
      "数据库集成",
      "前端 UI 组件"
    ]
  },
  "acceptance_criteria":[
    "函数 isValidEmail(email) 对有效的电子邮件返回 true。",
    "函数 isValidEmail(email) 对缺少 '@' 或顶级域名的电子邮件返回 false。"
  ],
  "verification_command": "npm test src/utils/email.test.js"
}

编排增量式循环

一旦契约锁定，Harness 就会编排一个严格的、重复的循环。该循环确保 Agent 始终专注于当前契约，而不会偏离去构建未批准或超出范围的功能。

阶段	动作	责任 Agent
1. 提案	起草下一个小任务的范围和标准。	生成器
2. 评审	根据复杂性和清晰度批准或拒绝契约。	评估器
3. 执行	编写代码以仅满足当前活跃契约。	生成器
4. 验证	运行商定的测试以确保完全合规。	评估器

严谨的端到端自我验证

拼图的最后一块是自我验证。绝不允许 Agent 随意宣布“我完成了！”相反，Harness 必须机械地执行 Sprint Contract 中约定的验证命令。

如果测试失败，Harness 会拦截错误日志并将其直接反馈给生成器，强制其重试。只有当评估器收到通过的测试信号并验证所有验收标准均已满足时，该功能才会被标记为“已完成”。这种程序化边界有效地防止了 AI 产生“成功”的幻觉。

以下是一个 Python 伪代码示例，展示了你的 AI Harness 如何强制执行这种增量验证循环：

# 用于在 Harness 中强制执行 Sprint Contract 的 Python 伪代码

def execute_sprint(generator, evaluator, sprint_contract):
    max_retries = 3  # 最大重试次数
    attempt = 0

    while attempt < max_retries:
        # 1. 生成器根据严格的范围编写代码
        code_diff = generator.implement(sprint_contract.scope)
        apply_to_workspace(code_diff)

        # 2. Harness 机械地运行约定的验证命令
        test_results = run_command(sprint_contract.verification_command)

        # 3. 评估器根据验收标准检查结果
        evaluation = evaluator.review(sprint_contract, test_results)

        if evaluation.is_approved:
            print(f"迭代 {sprint_contract.sprint_id} 已成功完成！")
            return True
        else:
            # 将确切的失败原因（日志）反馈给生成器
            generator.add_context(evaluation.failure_feedback)
            attempt += 1

    raise Exception("迭代在达到最大重试次数后仍未满足契约标准。")

通过将你的 Agent 封装在这种严格的、契约驱动的 Harness 中，你彻底消除了“一键式陷阱”。你将它们从不稳定的“快速编码员”转变为严谨、有条理的工程师，能够一次一个可靠且经过全面验证的代码块来构建庞大的系统。