演进：规约与验证的持续迭代
引言定义了 harness 的两个原则：闭环控制和持续演进。前两章建立了闭环，用规约定义意图，用验证确认执行。但我们还没有触碰第二个原则。
代码在完成的那一刻不是生命的终点，而是生命的起点。上线之后，用户反馈会来，产品需求会变，功能会增加也会修改。你写好的 spec 和测试在第一个版本中运转良好，但第二个需求来了怎么办？
直觉的做法有两个，都有问题。第一个是回到 vibe coding：直接跟 Agent 聊新需求，跳过 spec。前两章已经解释了为什么这不 work，注意力衰减、意图丢失、验证失去锚点，所有旧问题都会重现。
第二个是手动更新所有文档：把新需求的影响逐一反映到 spec、测试、project-context 中。方向是对的，但如果 spec 做得认真，文档量会很大，而且功能之间相互纠缠，改一条业务规则可能影响三个模块的测试和两份 spec 的约束条件。手动维护的成本随项目规模快速增长。
这一章处理的就是 harness 的第二个原则：怎么让闭环跟着项目一起演进，而不是在第一次迭代时就开始腐烂。
为什么 spec 一定会过时
Spec 过时不是疏忽，是结构性必然。闭环的参照系是 spec，所有验证动作都以 spec 为锚点。Spec 是对的，闭环就能保证产出是对的。但 spec 本身不会自动更新。
引言在讨论 Agent 的无记忆积累特征时已经指出了这一点：你为 Agent 搭建的外部知识体系（规约、测试、流程文档）替代了人类自带的业务常识和项目记忆，但人脑中的知识随项目演化自动更新，文档不会。你重构了一个模块，你对这个模块的理解同步更新了。文档还停在重构之前。
每一次迭代都在制造 spec 和代码之间的漂移。新 feature 改变了系统行为，但 spec 不知道。旧 feature 的测试还在验证已经不存在的前提。积累几轮之后，spec 和代码的距离越来越远，闭环不是失去了保护，而是在保护一个错误的目标。引言预警的场景就是这样发生的：偏差在闭环的保护下被制度化。
让文档跟着代码一起演进，这不是 AI 时代发明的问题。传统软件工程在几十年前就面对过，并且有成熟的方法论。但这些方法论能直接搬过来吗？
敏捷的原则对，粒度不对
敏捷方法论的迭代原则直接适用于 spec 维护：小步迭代、持续反馈、拥抱变化。但敏捷的执行粒度是为人类团队校准的，直接搬到 AI 开发中会产生严重的效率倒挂。
BMAD 框架是目前 AI 开发社区中最完整的敏捷移植。它把 epic 分解到 story，每个 story 配备 5 份以上的文档，12 个 agent persona 分工协作，每个 story 走完整的审批门禁。这套流程确保每一步都有文档、每一步都被审查。但一个 story 对应的是一个人类开发者几天的工作量，为这个大小的工作量配备完整流程，在人类团队中成本和收益是匹配的。
Agent 的执行单元远大于此。规约章建立的 context 容量概念可以解释这个错配：一个 Agent session 能有效处理的信息量足以覆盖多个传统 story 的工作量。在我们的示例项目 AILock-Step 中，一个 feature 包含完整的 spec、task list、checklist、实现和验证，在规模上相当于 BMAD 的多个 story。把每个 story 级别的工作都走一遍完整的敏捷流程，人在流程管理上投入的精力反而超过了 Agent 在执行上节省的时间。实际使用中这种效率倒挂很明显：几句话就能说清楚的需求，走完整的敏捷流程可能花掉一整天。
根因是执行单元的大小变了，但流程的粒度没有跟着变。敏捷的迭代管理原则仍然适用，需要重新校准的是每一步的大小。
像管代码一样管文档
以 feature 为单位迭代，每个 feature 内部走完整的 spec → implement → verify 闭环。剩下的问题是：跨 feature 的文档怎么管？每次迭代都在修改同一组 spec 文件，需要追溯修改历史，需要检测不一致。这些挑战和代码管理面临的挑战结构相同。代码合并后跑测试，spec 合并后也要跑验证。代码有版本历史，spec 也需要归档。代码开发前拉最新，spec 开发前也要检查一致性。
用规约章 OKR 案例的后续来走一遍这个流程。
前置状态
第一个 feature（OKR 基础 CRUD）已完成。主 spec 包含三个子功能（目标管理、KR 管理、季度总览），5 条业务规则（BR-001 到 BR-005），6 个 API 端点。Out of Scope 列表中明确排除了 8 项功能，其中一项是"目标对齐"。
现在产品说：下个版本要支持跨部门的 OKR 对齐，部门负责人可以把自己的目标关联到上级部门的目标。这正是之前显式排除的功能。
创建 change 包
每个变更是一个自包含的 feature 包，从用户故事到验收条件完整覆盖所有层级。不是代码级 diff，是 spec 级的完整描述。
changes/cross-dept-alignment/
├── story.md # 用户故事
├── design.md # 架构影响分析
├── delta-spec.md # 对主 spec 的增量修改
├── tasks.md # 任务分解
└── checklist.md # 验收检查项
story.md 描述用户价值：部门负责人需要在设定季度 OKR 时，将自己的目标关联到上级部门的目标，这样组织可以追踪目标从公司层到部门层的对齐关系。
design.md 分析架构影响：新增 alignment 模块（对齐关系表、CRUD 接口），修改现有目标查询接口（返回对齐状态字段），修改目标详情页面（展示对齐关系）。
delta-spec.md 是核心。它用 ADDED、MODIFIED、REMOVED 三个区块描述对主 spec 的增量修改，每条 requirement 带完整的 acceptance scenario：
## ADDED Requirements
### Feature: 目标对齐 (Objective Alignment)
**User Story**: As a 部门负责人, I want to 将部门目标关联到上级部门目标
so that 组织可以追踪从公司到部门的目标对齐关系。
**Acceptance Criteria**:
- [ ] 目标详情页显示"对齐到"字段，可选择上级部门的目标
- [ ] 对齐关系建立后，季度总览页面展示对齐链路
- [ ] 只有部门负责人角色可以设置对齐关系
**Business Rules**:
| # | Rule | Condition | Outcome |
|---|------|-----------|---------|
| BR-006 | 对齐方向 | 设置对齐关系时 | 只能对齐到上级部门的目标，不能平级或反向 |
| BR-007 | 对齐可选 | 创建目标时 | 对齐关系非必填 |
**API Contract**:
| Endpoint | Method | URL |
|----------|--------|-----|
| 设置对齐 | POST | /system/okrAlignment |
| 查询对齐链路 | GET | /system/okrAlignment/chain |
## MODIFIED Requirements
### Feature: 目标管理 (Objective Management)
**变更说明**: 目标查询接口增加 alignedTo 字段，返回该目标对齐的上级目标信息。
目标列表页增加"对齐状态"列（已对齐/未对齐）。
### Out of Scope
**变更说明**: 移除"目标对齐"条目。该功能已纳入本次开发范围。
## UNCHANGED (显式声明)
BR-002（每个目标最多 5 个 KR）、BR-003（完成率范围 0-100）等已有业务规则
在本次变更中不受影响。
UNCHANGED 区块是防止引言场景的关键机制。不显式声明"哪些没变"，Agent 在实现新功能时可能无意间覆盖已有规则。显式声明把保留规则从隐性假设变成可审查的文档。
创建时验证
change 包在编码之前就跑验证。这是成本最低的拦截点，发现问题只需要改文档。
自动化验证检查一致性层面的问题：delta-spec 中 MODIFIED 的每条 requirement 在主 spec 中是否存在。新增的 API 端点和已有端点是否有路径冲突。新增的 BR-006、BR-007 和已有的 BR-001 到 BR-005 之间是否有矛盾。design.md 声明的受影响模块是否覆盖了 delta-spec 中所有变更涉及的模块。
人工审查聚焦意图层面：用户故事是否准确反映了产品意图。对齐方向的业务规则（只能对齐到上级）是否正确。MODIFIED 的范围是否完整，有没有遗漏受影响的模块。
审查通过后，change 包成为 Agent 执行的输入，从这里开始走规约章和验证章建立的闭环。
执行闭环
Agent 根据 delta-spec 和 tasks 实现功能，验证对照 checklist 和 acceptance scenario。这个阶段和前两章完全一致，不需要新的方法。
合并与合并后验证
实现和验证完成后，delta 合入主 spec。合并本身是 requirement 粒度的操作：ADDED 的内容追加到主 spec 对应模块，MODIFIED 的替换原有 requirement 的完整内容，REMOVED 的删除（这里是从 Out of Scope 中移除"目标对齐"）。
合并后跑一次文档级验证，和验证章的测试基建是同一个思路。检查合并后的主 spec 是否存在内部矛盾：新增的对齐权限模型（只有部门负责人）和已有的目标管理权限（管理员）是否冲突。新增的对齐查询接口的返回值格式和已有接口是否一致。已有的 BR-001 到 BR-005 在合并后是否仍然完整存在。
合并后更新 project-context：模块列表中新增 alignment 模块，API 列表中新增两个端点，Out of Scope 列表移除已实现的条目。
归档
change 包整体移动到 archive/2026-04-cross-dept-alignment/。归档内容包括原始的用户故事、架构分析、delta-spec、task list、checklist 和执行结果。三个月后如果对齐功能出了问题，这个归档提供完整的决策链路：为什么做、怎么设计、验证了哪些条件。
归档的原则是可追溯但不污染当前工作区。当前 Agent 只加载主 spec 和它正在做的 feature 的文档，不被历史归档淹没。
下一个 feature 前的同步检测
第三个 feature 来了（比如 OKR 评分功能）。开始之前，Agent 先读 project-context 了解当前系统状态，再对照主 spec 检查一致性。
即使严格走 change 包流程，仍然可能产生不一致：实现过程中 Agent 的残留漂移（验证章讨论过，测试和 review 拦截大部分但不是全部），或者 delta 合并时遗漏了关联模块的更新。同步检测是这些残留问题的兜底。
同步检测和创建时验证形成闭环：创建时验证 change 包和主 spec 的一致性，同步检测验证主 spec 和代码的一致性。两道门覆盖了 spec 生命周期的两端。检测结果需要人判断：差异是有意的演进还是无意的遗漏。
Change 包流程把文档演进从"记得去更新"变成了一个可重复的工程动作。每次变更有完整的 spec 级描述，有两道验证门（创建时和合并后），有归档保留决策链路，有同步检测兜底残留漂移。引言定义的第二个原则，持续演进，到这里有了具体的操作方式。
Harness Engineering Playbook · AgentsZone Community