# 定义完成指南：完成合同、Oracle 与自主交付

本文说明 kit 研发轨的判定核心：怎样把一个需求的"什么叫完成"一次性定义清楚，让 agent 可以自主执行到可证明的完成，而验收时"完完全全就是你想要的"。

## 核心理念

编程工作的胜负在于谁能一次性把"什么叫完成"定义清楚。定义清楚不是写更长的文档，而是让定义具备三个性质：

1. **可编译**：分散在需求、PRD、架构、测试文档里的结论能收敛成一份合同，没有互相矛盾。
2. **可判定**：每条验收标准绑定可复现的验证方法，完成与否由机器状态判定，不由感觉判定。
3. **可冻结**：实现开始后标准不再漂移；要改就显式修订并经用户确认。

## 八维度：一份"定义清楚"的合同长什么样

| # | 维度 | 合同章节 | 检查问题 |
| --- | --- | --- | --- |
| 1 | 底层逻辑拆解 | 数据流与状态机 | 数据从哪来到哪去？谁是唯一真相源？非法状态转移如何被拒绝？ |
| 2 | 技术边界与异常路径 | 失败路径闭环 | 弱网重试与幂等？并发冲突？进程中断？配额耗尽？ |
| 3 | 性能与成本硬约束 | 质量预算 | P95 多少毫秒？包体/内存上限？单用户成本上限？ |
| 4 | 验证可复现性 | 验收 Oracle | 每条标准怎么证明？命令是什么？判定阈值是什么？ |
| 5 | 语义歧义消融 | 术语表 | "快/流畅/稳定"绑定了数字或可观察行为吗？ |
| 6 | 人性与体验直觉 | 体验质量线 | 空/错/载三态齐了吗？错误信息可行动吗？ |
| 7 | 商业北极星锚定 | 北极星挂钩 | 本需求预期移动哪个漏斗指标？ |
| 8 | 组织语境共识边界 | 影响边界 | 允许改什么禁止碰什么？与宪法、规范、specs 冲突吗？ |

八个维度由 `workflow/core/capabilities/definition-lint.md` 在冻结前逐维检查；该能力还内置按项目类型（Web/CLI/扩展/移动/MCP/静态站点）的**定义面试题库**——个人开发者不必精通重试、幂等、内存模型，题库逼着把这些约束变成合同条款或显式假设。

## 完成合同生命周期

```
/new-feature（S/M/L 分级）
   │
   ├─ S 档：/定义完成 生成迷你合同（只填 ★ 节）→ 实现 → 验证
   │
   └─ M/L 档：
      /01 需求 →（/澄清）→ /02 PRD → /02B UI → /03 架构 → /06 测试用例
         │  （各阶段用 [待澄清] 标记未决项；模糊词必须绑定数字）
         ▼
      /定义完成：编译合同 → Definition Lint → 清零待澄清 → 用户确认冻结
         ▼
      /一致性检查（只读交叉检查，BLOCKER 必须先修）
         ▼
      /交付至完成：循环 实现→验证→修复→复验，直到 blocking Oracle 全绿或精确阻塞
      （或手动 /04 → /05 → /07）
         ▼
      /08 发布准备（准入 = blocking 全 PASS/WAIVED）→ /09 → /10（回写 specs/）
```

## Oracle 状态机

每条验收标准是一条 Oracle：`ID + 标准（EARS/GWT 句式）+ 验证方法 + 类型（auto/manual）+ blocking + 状态 + 证据`。

- 状态：`NOT_RUN → PASS / FAIL`；PASS 后相关代码再变更 → `STALE`（必须复验）；`WAIVED` 仅可由用户书面确认。
- 只有 `/交付至完成` 和 `/07-测试执行` 有权翻转状态，且逐次附证据（命令、输出、退出码、commit）。
- **宣布完成 = blocking Oracle 全部 PASS（或 WAIVED 带确认）**；有 NOT_RUN/FAIL/STALE 的 blocking 项时，"基本完成"属违规表述。
- 结构校验：`node bin/check-contract.cjs features/<feature>/00-完成合同.md`（分档必填节、Oracle 表完整性、冻结前置条件、模糊词扫描）。

## 三层长期资产

| 层 | 位置 | 放什么 | 谁读谁写 |
| --- | --- | --- | --- |
| 宪法 | `workflow/constitution.md` | 跨需求不可协商的原则（技术栈偏好、安全底线、成本上限、永不做清单） | 所有阶段读；修订需用户确认 |
| 规范 | `workflow/standards/` | 从代码库提取的可复用规范（命名、错误处理、依赖选型） | `/03` 提取，`/04`/`/05` 遵循，`/10` 沉淀 |
| 行为真相 | `specs/`（living specs） | 已实现并已发布的行为（EARS 句式），brownfield 定义起点 | `/01`/`/定义完成`/`/06` 读；仅 `/10` 发布后回写 |

事实与路径放 `workflow/team-profile.yaml`——原则、规范、行为、事实四者分家，需求阶段不再重复讨论不变的东西。

## 复杂度分级（消灭流程税）

| 档 | 适用 | 路径 |
| --- | --- | --- |
| S | bugfix、文案、单文件小改；不改对外契约、不碰高风险文件 | 迷你合同（★ 节）→ 实现 → 验证 |
| M | 单仓功能，影响面清晰 | 标准路径，可按需豁免单项并记录 |
| L | 跨仓、动数据/契约、高风险文件、新品首发 | 全流程，闸门阶段不得豁免 |

拿不准就近上调一档；分级只压缩文档路径，不豁免授权边界（push、发布、对外动作仍需用户授权）。

## 设计参考

机制设计对照了 2026-07 采集的主流 spec-driven 框架：github/spec-kit（clarify ≤5 问、NEEDS CLARIFICATION 标记、技术无关 Success Criteria、constitution、analyze）、Fission-AI/OpenSpec（change 流水 + living specs、brownfield 优先）、BMAD-METHOD（scale-adaptive 复杂度、风险驱动测试）、Kiro specs（EARS 需求句式）、buildermethods/agent-os（standards 分层）等，并针对个人开发者做了裁剪：一个人没有对抗性角色，就用"合同冻结 + 内建审查视角 + 机器判定"替代组织制衡；时间是最稀缺资源，就用 S/M/L 分级消灭流程税。