跳到正文
擎天文档返回官网 ↗
文档/方法参考

验收契约方法

本页内容

激活与身份#

进入本方法时先建立 active acceptance ledger,而不是只引用设计或计划中的被动清单:

  • contract-id 标识本次整体契约,parent-goal 固定用户最终结果;
  • 为每个会改变整体完成判断的标准分配 stable acceptance ID,登记 Required: true | false、合同、Status: not-run | passed | failed | blocked | stale、当前证据和失效原因;
  • 优先复用用户或已有权威文档中的稳定 ID;无 ID 时按契约内稳定前缀递增,重命名实现、阶段或版本不得重编号;
  • 设计、计划、issue 或发布说明只是候选来源;只有登记到 active ledger 的条目才参与阶段更新和 completion gate。

passed 只表示证据仍匹配当前实现、范围、环境与场景版本;相关事实变化后立即转为 stale。blocked 是未完成状态,不能通过改成非必需来消失。

跨架构交付的双向对账#

更换运行宿主、存储归属、能力目录或主要用户链路时,在原 active contract 中对照三类事实:旧产品实际能力(旧入口与代表性使用路径)、用户当前要求(原始输入及有效修订)、候选方案及产物能力。设计阶段用拟交付的触发路径检查覆盖范围;实现后改用新入口与运行证据判定实际能力,不把方案当事实。只登记本次触达且可能改变用户结果的能力。分别检查旧→新有无未经解释的变化或退化,以及目标→新有无未实现、未验证的必需结果;不另建平行账本。

每个 Required 结果拆到用户动作与可观察结果能够独立判定;含条件分支时逐分支留证。passed 须有可触发入口、实际执行和结果的正向证据;“没有工具”或“无人触发”不能证明按需能力。设计把 Required 能力列为未来扩展时,Design Ready 前须将它纳入当前实现和验证设计,或取得用户确认的范围变更。缺可行触发证据记 not-run/blocked,确认缺实现记 failed;其它分支成功或发布成功不能改写它。

建立整体契约#

先基于已确认的用户目标与事实写最小整体契约;未知项明确标记,不用猜测补齐。大型交付默认保存为 docs/work/YYYY-MM-DD-<delivery-slug>/acceptance-contract.md;项目已有等价载体则在工作入口明确映射,不另抄标准。日期取创建日,跨天沿用。

讨论转入执行或用户纠偏时及时保存预期与来源:区分用户明确要求、已确认选择、授权内 AI 决定和未确认假设;沉默不算确认。来源可用消息链接,不能稳定定位时保留日期与必要原话。重要取舍保留理由,模糊表达的具体化注明推断;只有影响决策的歧义才澄清。稳定 ID 用于重要标准,不给每句聊天或普通观察编号。

大型交付的原始输入、材料版本与用途、原意及后续补充保存在 docs/logs/ 的“原始输入与约束”章节或其链接文件;本合同引用该记录及相关来源,拥有当前有效标准与生效变更,不复制原始材料清单。提炼时反查原件,不能因账本遗漏而排除用户已要求的结果;已确认的新约定可替代旧要求,但保留来源与替代关系。

  1. 最终结果:一句话描述用户最终能完成什么,而不是列实现组件。
  2. 必须成立:只保留缺失后用户会认为“没有交付完整”的结果、关键链路与产品能力。
  3. 必须不发生:只记录本任务真实高风险的退化、漂移、数据损坏、安全越界或错误兼容。
  4. 架构不变量:只约束 owner、数据/事件归属、公共 contract 或单一路径等长期意图;不锁定可替换的临时实现。
  5. 代表性场景:用少量真实用户任务覆盖主要机制、数据状态、失败边界和适用生命周期;不按 API 数量机械穷举。
  6. 交付边界:区分本地可交付、安装/升级、发布/部署和需要授权的外部动作。
  7. 真实边界:只记录用户明确排除、与最终结果无关、需要新增授权或受外部条件阻塞的内容;AI 不得为了让任务有限而自行制造“本轮非目标”。

当响应速度、吞吐、资源消耗或成本是用户目标,或足以改变架构选择时,将其登记为可判定的 Required 结果:实现前固定代表性任务、数据量、并发或活跃用户、冷/热状态、用户可感知的起止点、统计口径、基线或目标门槛及测量环境。成本在相同使用条件下区分固定与边际开销;比较方案时保持负载、模型和计费假设一致。门槛取自用户要求、现状证据或说明依据的设计目标,不凭空设通用数值,也不在看到实现结果后调低。条件不同的路径分别判定,功能通过不能抵消性能或成本 Required 项失败。

完成边界、阶段切片与授权边界#

大型任务必须分开维护三件事:

  • 最终完成边界来自用户想得到的结果和 AI 被委托负责的产品方向。用户把一个方面交给 AI 时,默认包含当前能够独立完成的产品、架构、实现、体验、生命周期、文档、打包与验证闭环,而不是只包含最先出现的任务清单。
  • 阶段切片只决定先后顺序和当前工作量。阶段完成只能表述为“该阶段完成”,不得据此把整体目标改称完成,也不得把后续仍可实施的工作放入“未来”后结束任务。
  • 授权或外部边界只暂停相应动作。commit、发布、部署等需要授权时,先完成其余可做工作并把产物准备到可执行状态;不得把“尚未获准执行外部动作”扩张成整个产品方向的缩减。

MVP、本轮、非目标 或 后续再做 不能由 AI 单方面降低用户结果。只有以下情况才能排除工作:

  1. 用户明确排除或限定;
  2. 证据表明它与最终用户结果无关;
  3. 它需要尚未获得的外部授权、凭据、硬件或第三方状态;
  4. 新事实证明继续建设没有产品价值,并经用户确认停止或缩小。

删除 Required ID、改成 optional、降低合同或把工作移出 parent-goal 都是 scope reduction;先记录 scope-change: proposed,只有用户明确同意后才能写入 scope-confirmation: user-confirmed 并提高 scope-revision。用户补充信息、实现学习、版本或发布时间点不能静默授权缩 scope。

当用户表达“你负责这个方面”“能做的都做掉”或同等委托时,每次阶段收尾必须追问:在不需要用户新增输入和授权的前提下,我现在还能继续闭合什么? 只要答案非空,就只能报告阶段进展,不能报告整体完成。

验收标准定义“什么必须被证明”,Validation 决定“用什么证据证明”。不要复制测试命令或阶段 owner 的通用清单。

标准质量过滤#

每条候选标准必须同时通过:

  • 如果它不成立,用户是否会合理地认为任务未完成?
  • 它是否对应当前任务真实可能出现的失败,而不是泛化想象?
  • 它是否可通过行为、状态、产物或边界证据判断?
  • 它是否保留合理实现空间,没有把临时方案写成永久合同?

再做删除测试:删掉这条后,哪个现实中的坏结果会被错误放行? 无法回答就删除。仓库常驻规则、一般 AI 不会遗漏的常识和与当前任务无关的最佳实践不要重复写入。

分阶段与即时阶段门#

大型交付默认一个阶段,允许多个工作项及跨轮执行。分阶段必须记录:两侧可观察结果、真实证据/外部依赖或风险、合并会出什么具体问题、通过/返工条件。普通排序或提前集成足以解决时不分阶段;文件多、耗时长、需要 plan 均不足以拆分。

方案 Review 检查相邻阶段能否合并,缺依据则合并;同时检查未解决的关键假设,不能为单阶段而盲目展开。新证据消除边界后允许合并;通过阶段门后仍有可执行必要工作就继续,不新增例行人工审批。

每个阶段开始时,基于最新证据即时写阶段门:

  • 本阶段结束时新增的可观察结果;
  • 必须保持的整体契约和架构不变量;
  • 覆盖该结果的代表性成功、状态恢复或失败场景;
  • 本阶段暂不处理但仍属于整体目标的内容;
  • 进入下一阶段前必须关闭的缺口。

阶段结束时只更新受新事实影响的 ID 和后续阶段,不重写稳定契约。每个阶段返回 acceptance_updates 与 parent_status: in-progress | blocked | ready-for-retrospective | ready-for-completion-check;Delivery 和专项 release 只能关闭子目标,随后返回 lifecycle parent。Delivery 成功后先进入复盘,复盘给出明确决定后才允许完成检查;不能自行把发布、版本或阶段成功升级成整体完成。

学习与漂移控制#

实现中出现新发现时必须归类:

  • 当前验收必需:加入当前阶段并说明遗漏原因;
  • 原标准被事实证明错误:修改契约,记录证据、影响与理由;
  • 有价值且属于最终结果:纳入当前可执行工作或按真实依赖排序,保持未关闭,不为放进“后续”而造阶段;
  • 有价值但与当前委托无关:只有通过真实边界条件时才排除;
  • 与目标无关:丢弃,不因已经发现就扩张范围。

不得静默改变最终结果、Required IDs、架构不变量、代表性场景或交付边界。设计学习可以改变实现,不能悄悄改变用户得到的结果。

有效约定与待决提案分开。变更写明原约定、新事实、建议与影响:保持用户结果的授权内实现选择可自主修订;改变用户目标、体验、关键取舍或权限时按原授权决定,无相应授权则等用户确认,旧约定保持有效。生效时记录依据与替代关系,只使受影响证据 stale。普通验收状态变化不提升标准修订号;不能倒改标准追认已偏离的实现。

工作开始/恢复时读取有效约定及相关设计;Review 从实际产物反查约定与用户来源,检查最初提炼是否漏项。多个 AI 产物相互一致不证明理解正确。只更新变动项,不要求每次工具调用重读全部合同。

兼容或legacy保留先按真实存量与兼容证据核对实际消费者/数据/对外承诺,不能用旧草案或聊天路径虚构存量。兼容、fallback、重试或legacy分支进入契约还须写明真实消费者、为何不应显式失败、可观察方式和退出条件;否则采用单一正确路径。

一次契约 Review#

整体契约和每个阶段门各做一次针对性 Review:

  • 是否可能所有条目都通过,用户仍明显只拿到 80% 的结果?
  • 是否由 AI 自己选择了 MVP、单平台或单链路,然后把其它仍可完成的产品工作写成非目标?
  • 当前还有哪些无需用户新增输入或授权就能继续完成的工作?若存在,整体状态必须保持未完成。
  • 是否漏掉与当前产品真实相关的数据、权限、恢复、安装、升级、卸载、失败或 Agent 调用链路?
  • 是否有条目只是重复项目规则、与任务无关或几乎不可能出错?
  • 是否把临时实现、未来平台愿景或主观偏好误写成硬约束?
  • 是否引入没有当前消费者的兼容层、兜底或扩展点?

只修正能改变完成判断的问题,不进行无上限自我辩论或反复改写。

连续性与最终门#

跨会话、交接或上下文压缩前,持久化 active-contract、parent-goal、scope-revision、open-required、最近 acceptance_updates、证据指针和用户确认的 scope decisions。恢复后先重载 ledger,把阶段/发布结果对账到 stable IDs;不得从最新版本号、最近总结或局部成功猜测范围和完成状态。

大型交付还须对账delivery-goals中的规划功能/可执行任务:当前必需项均已完成,证据与当前合同一致;再反查parent-goal有无遗漏。名字不必写成上层效果,每项完成标准须可验收;清单不完整或整体场景失败时,即使所有编码项已完成也不能关闭整体。清单载体沿工作记录协议,不在本合同另复制任务状态。

只有 lifecycle 可以执行 completion gate:全部 Required: true ID 当前均为 Status: passed、证据未失效,且没有未登记但属于 parent-goal 的必要缺口,才允许整体完成。任一 Required ID 为 not-run、failed、blocked 或 stale 时只能继续、返工或真实阻塞;版本发布、文档状态和阶段汇报不能覆盖该结论。

最小活文档#

# 交付合同

## 身份与来源

- contract-id:
- parent-goal:
- scope-revision / scope-confirmation:
- 用户来源(大型交付链接日志中的原始输入记录)、确认性质、适用范围与授权:

## 当前有效约定
- 稳定 ID、表述、来源、适用范围(下列维度按实际需要组织):
- 必须成立:
- 必须不发生:
- 架构不变量:
- 代表性场景:
- 交付边界:
- 真实边界:

### 阶段安排(默认单阶段,必要拆分才展开)
| 阶段 | 可验收结果 | 进入下一阶段的门 | 状态 |

## 验收账本(Active acceptance ledger)
| ID(引用有效约定) | Required | Status | 当前证据 | 失效原因 |

### 当前阶段门
- 结果:
- 保持项:
- 场景:
- 本阶段不做:
- 待关闭缺口:

## 待决变更
- 原约定 / 新事实 / 建议 / 影响 / 待谁决定(没有则写无):

## 生效记录
- 原→新 / 原因 / 授权依据 / 修订 / 受影响 ID(没有则写无):

### 尚未关闭
- open-required、未验证边界、真实外部阻塞或待授权动作:

契约形成后明确说明被删除的主要噪声标准及原因。契约足以支持下一阶段做明确决策后退出。