Skip to content

Commit e1291a4

Browse files
fqzz2000claude
fqzz2000
and
claude
committed
Write evolution chapter and volume 1 conclusion (all three languages)
New content: - evolution-v1.md: spec decay mechanism, agile granularity mismatch, change package workflow with OKR walkthrough (delta-spec demo) - v1-conclusion.md: volume 1 recap connecting spec, verification, and evolution into a coherent system Updated indexes: - SUMMARY.md and README.md in zh/en/ja with new chapter entries Supporting docs: - docs/evolution-v1-outline.md and walkthrough outline Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent c2d0e8c commit e1291a4

14 files changed

Lines changed: 706 additions & 18 deletions

‎docs/evolution-v1-outline.md‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
# Outline: 体系也要迭代：规约与验证的演进
2+
3+
## Chapter Takeaway
4+
5+
闭环控制只解决了 harness 的一半。没有演进机制，闭环会固化过时的意图。像管代码一样管文档，是在 human-in-the-loop 阶段让闭环活下去的方法。
6+
7+
---
8+
9+
## Section 1: 闭环建好了，然后呢
10+
11+
**Motivation**: 02 和 03 完成了 harness 定义的前半部分（闭环），读者需要知道另一半（演进）在实践中意味着什么。
12+
13+
**Takeaway**: 闭环控制让每一次执行可靠，但闭环的参照系，spec，会随着项目迭代而过时。引言已经指出了这个风险：过时的 spec 不是失去保护，而是闭环在保护一个错误的目标。
14+
15+
**内容要点**:
16+
- 连接引言的两个原则：02+03 建立了闭环（规约定义对的标准，验证检查做对了没有）。这是 harness 的第一个原则。引言同时定义了第二个原则，持续演进：闭环本身需要跟着项目演化
17+
- 引言在讨论"无记忆积累"时已经预警过：外化的知识不会自动更新。规约、测试、流程文档是你为 Agent 搭建的外部知识体系，替代了人类自带的业务常识和项目记忆。但人脑的知识随项目自动更新，文档不会
18+
- 场景具体化：OKR feature 成功后，新需求来了。如果你直接跟 Agent 聊新需求（回到 vibe coding），spec 停在上个版本，验证体系在验证旧行为，闭环静默失效。引言说的"偏差在闭环的保护下被制度化"，这就是它的具体表现
19+
- 让文档跟着代码一起演进，这不是 AI 时代发明的问题。传统软件工程在几十年前就面对过，并且有成熟的方法论。但这些方法论能直接搬过来吗？
20+
21+
---
22+
23+
## Section 2: 敏捷的原则对，粒度不对
24+
25+
**Motivation**: "持续迭代的文档管理"不是新问题，敏捷方法论就是为此设计的。读者可能会想直接套用，需要先承认相关性再指出适配问题。
26+
27+
**Takeaway**: 敏捷的迭代思维完全适用，但执行粒度需要重新校准，AI 的执行单元远大于人类开发者的一个 story，逐 story 走完整流程反而成为瓶颈。
28+
29+
**内容要点**:
30+
- 持续迭代中保持文档和代码同步，这不是 AI 时代的新挑战。敏捷方法论的核心就是为"需求持续变化"设计的：小步迭代、持续反馈、拥抱变化
31+
- BMAD 是最完整的敏捷→AI 移植（epic→story→task，12+ agent persona，每个 story 完整文档+审批流程）。问题不是思路错，是粒度错
32+
- 02 章建立的 context 容量概念可以解释这个错配：一个 Agent session 能有效处理的信息量远超一个人类开发者一个 sprint 的工作量。Ryan 的实践佐证了这一点，他的单个 feature（spec + task + checklist + implement + verify）在规模上相当于 BMAD 的多个 story。把每个 story 都走完整敏捷流程，人的心智负担反而比不用框架还重。Ryan："几句话说完的需求，走 BMAD 花了一天"
33+
- 根因：敏捷的粒度是为人类团队校准的（一个 story ≈ 一个人几天）。AI 改变了执行单元的大小，但迭代管理的原则不需要变
34+
35+
**证据**: BMAD 流程重量（5+ 文档/feature，12+ agent persona）、Ryan 的 BMAD 使用体验
36+
37+
---
38+
39+
## Section 3: 像管代码一样管文档
40+
41+
**Motivation**: Section 2 保留了敏捷的迭代原则，否定了它的执行粒度。需要回答：适配 AI 开发的文档演进具体怎么做？
42+
43+
**Takeaway**: 代码管理早已解决了"多人持续修改同一组文件"的问题，核心机制是增量变更、版本归档、同步检测。文档演进直接借鉴这三个机制。
44+
45+
**内容要点**:
46+
- 总论：文档管理面临的挑战（多次迭代、需要追溯历史、需要检测不一致）和代码管理面临的挑战结构相同。代码管理用 git 解决了这些问题，文档管理借鉴同样的机制
47+
- 三个机制按文档生命周期的时序排列：变更时怎么改、完成后怎么存、下次开始前怎么查
48+
- **增量变更（变更时）**：不全量重写 spec，用 delta 方式描述变更（新增/修改/删除了什么）。OpenSpec 的 `changes/` 目录是一个参考实现
49+
- **版本归档（完成后）**：每个 feature 完成后，spec/task/checklist 归档，可追溯但不污染当前工作区。Ryan 的 feature archive：通过 feature id 索引历史文档
50+
- **同步检测（下次开始前）**：project-context 作为活索引，每次新 feature 前检查当前状态与 spec 是否一致。Spec Kit 的 spec sync 思路
51+
- 收束：这三个机制让 spec 本身也变成了被管理的对象。02 章说"人是意图的唯一裁判"，在演进中这个角色不变：人判断 spec 是否还忠实于当前意图
52+
53+
**证据**: OpenSpec delta spec、Ryan feature archive、Spec Kit sync（轻引，提取原则）
54+
55+
---
56+
57+
## Section 4: 收束 → 卷二
58+
59+
**Motivation**: 界定这套方法的适用边界，为卷二建立期待。
60+
61+
**Takeaway**: Human-in-the-loop 下的文档维护成本随项目规模增长。feature 越多，每次变更需要对账的已有 spec 越多，维护闭环的成本倒逼自动化，这是卷二的起点。
62+
63+
**内容要点**:
64+
- 当前阶段（一个人、几个并行 feature），人能发现 spec 过时并主动更新，三个机制的成本可控
65+
- 成本增长的机制：每个新 feature 不仅要维护自己的 spec，还要检查它和已有 spec 的一致性。feature 数量从 5 个增长到 50 个时，交叉检查的工作量不是线性增长的。Ryan 的下一步计划（PM agent、上层拆分 agent）正是对维护成本的回应
66+
- 卷一建立的是 harness 的完整定义（闭环 + 演进），但执行主体还是人。卷二的问题是：怎么让 Agent 自己维持更多的闭环，而人退到更高层的监督位置
67+
68+
---
69+
70+
## 素材映射
71+
72+
| 素材 | 用在哪 | 怎么用 |
73+
|------|--------|--------|
74+
| 引言的两个原则（闭环+演进） | Section 1 | 直接连接，不重新推导 |
75+
| 引言"无记忆积累"段落 | Section 1 | 引用其"外化知识不会自动更新"的结论 |
76+
| 02 章漂移概念 | Section 1 | 引用，不重复定义 |
77+
| BMAD 流程研究 | Section 2 | 作为"敏捷粒度不对"的证据 |
78+
| Ryan 采访（BMAD 体验） | Section 2 | "几句话说完的需求花了一天" |
79+
| OpenSpec delta spec | Section 3 | 增量变更的参考实现 |
80+
| Ryan feature archive | Section 3 | 版本归档的实践案例 |
81+
| Spec Kit spec sync | Section 3 | 同步检测的思路 |
82+
| Ryan 下一步计划 | Section 4 | 维护成本倒逼自动化的真实案例 |

‎docs/evolution-v1-walkthrough-outline.md‎

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
# Walkthrough Outline: OKR 项目的第二个 Feature
2+
3+
## 目的
4+
5+
用 OKR 项目的第二个 feature（跨部门 OKR 对齐）走一遍文档演进的完整流程。读者看完应该知道"具体怎么做"。
6+
7+
## 前置状态
8+
9+
第一个 feature（OKR 基础 CRUD）已完成并归档。当前 project-context 记录了：
10+
- 已有模块：OKR 目标管理、KR 管理
11+
- 已有业务规则：每个目标最多 5 个 KR（BR-002）、新增页面默认选中当前季度（BR-004）
12+
- 已有 API：目标 CRUD、KR CRUD
13+
14+
---
15+
16+
## Step 1: 新需求到达，创建 change 包
17+
18+
**Takeaway**: 每个变更是一个自包含的 feature 包，从用户故事到验收条件完整覆盖所有层级。不是代码级 diff，是 spec 级的完整描述。
19+
20+
**内容要点**:
21+
- 产品说：支持跨部门的 OKR 对齐，部门负责人可以把自己的目标关联到上级部门的目标
22+
- 创建 change 包目录：`changes/cross-dept-alignment/`
23+
- 包内文件结构（展示目录树）：
24+
```
25+
changes/cross-dept-alignment/
26+
├── story.md # 用户故事：谁，做什么，为什么
27+
├── design.md # 架构影响：新增 alignment 模块，修改目标查询接口
28+
├── delta-spec.md # 对主 spec 的增量修改（ADDED/MODIFIED/REMOVED）
29+
├── tasks.md # 任务分解
30+
└── checklist.md # 验收检查项
31+
```
32+
- 重点展示 delta-spec.md 的内容格式：
33+
- ADDED：对齐关系的 CRUD、对齐视图的查询接口、对齐权限（只有部门负责人能操作）
34+
- MODIFIED：目标查询接口需要返回对齐状态字段
35+
- REMOVED：无
36+
- 每条 requirement 带 acceptance scenario（GIVEN/WHEN/THEN）
37+
- 关键原则：delta-spec 不只写"加了什么"，还要显式声明"没改什么"。BR-002（最多 5 个 KR）在这次变更中不受影响，但 delta 中需要注明这条规则仍然有效。这是防止引言场景（规则被静默覆盖）的关键
38+
39+
---
40+
41+
## Step 2: 创建时验证
42+
43+
**Takeaway**: change 包在编码之前就跑验证，这是成本最低的拦截点。发现问题只需要改文档，不需要改代码。
44+
45+
**内容要点**:
46+
- 两层验证：
47+
- **自动化验证**：delta-spec 中 MODIFIED 的每条 requirement 在主 spec 中是否存在且 base 匹配（防止基于过时 base 修改）。新增的 requirement 是否和已有规则冲突（比如新加的对齐功能是否隐含地修改了 KR 数量限制）。design.md 声明的受影响模块是否覆盖了 delta-spec 中所有变更涉及的模块
48+
- **人工审查**：用户故事是否准确反映产品意图。架构影响是否完整。delta-spec 的变更范围是否正确（改对了没有，改漏了没有）
49+
- 人是意图的唯一裁判，但自动化验证替人过滤掉了一致性层面的问题，让人聚焦在意图层面
50+
- 审查通过后，change 包成为 Agent 执行的输入
51+
52+
---
53+
54+
## Step 3: 执行闭环（略写）
55+
56+
**Takeaway**: 执行阶段和 02/03 章完全一致，不需要新的方法。
57+
58+
**内容要点**:
59+
- Agent 根据 delta-spec 和 tasks 执行实现
60+
- 验证对照 checklist，测试对照 acceptance scenario
61+
- 这一步不展开，引用 02/03 章
62+
63+
---
64+
65+
## Step 4: 合并 delta 到主 spec + 合并时验证
66+
67+
**Takeaway**: 合并后跑一次文档级的验证，确认新 delta 合入主 spec 后整体仍然一致。这和验证章的测试基建是同一个思路：代码合并后跑测试，spec 合并后也要跑验证。
68+
69+
**内容要点**:
70+
- **合并逻辑**：ADDED 追加到主 spec 对应模块，MODIFIED 替换原有 requirement 的完整内容，REMOVED 删除
71+
- **合并后验证**（callback 到验证章的测试基建思路）：
72+
- 合并后的主 spec 是否存在内部矛盾（比如新增的对齐功能的权限模型和已有的 KR 编辑权限是否冲突）
73+
- 新增的 acceptance scenario 和已有 scenario 之间是否有矛盾（比如新接口的返回值格式和已有接口是否一致）
74+
- 已有的业务规则（如 BR-002）在合并后是否仍然完整存在
75+
- **更新 project-context**：新增"对齐"模块到已有模块列表，更新 API 列表
76+
- 合并后，主 spec 反映系统当前的完整状态
77+
78+
---
79+
80+
## Step 5: 归档 change 包
81+
82+
**Takeaway**: 归档保留完整上下文，让未来的问题可追溯。
83+
84+
**内容要点**:
85+
- change 包移动到 `archive/YYYY-MM-DD-cross-dept-alignment/`
86+
- 归档内容包括：原始的用户故事、架构分析、delta-spec、task list、checklist、执行结果
87+
- 为什么要全部保留：三个月后如果对齐功能出了问题，你能回到这个归档，看到当时的完整决策链路（为什么做、怎么设计、验证了哪些条件）
88+
89+
---
90+
91+
## Step 6: 下一个 feature 开始前的同步检测
92+
93+
**Takeaway**: 同步检测是下一次迭代的安全门。即使前面的验证都通过了，开发过程中仍然可能产生 spec 和代码的不一致，同步检测是最后的兜底。
94+
95+
**内容要点**:
96+
- 第三个 feature 来了（比如：OKR 评分功能）
97+
- Agent 先读 project-context，了解当前系统状态
98+
- 对照主 spec 检查：有没有代码实现了但 spec 没有记录的行为？有没有 spec 声明了但代码没有实现的功能？
99+
- 即使严格走 change 包流程，仍然可能产生不一致：实现过程中 Agent 的残留漂移（验证章讨论过，测试和 review 拦截大部分但不是全部），或者 delta 合并时遗漏了关联模块的更新（比如改了接口返回值，但依赖这个接口的另一个模块的 spec 没有同步）
100+
- 同步检测的结果需要人判断：差异是有意的演进还是无意的遗漏
101+
- 同步检测和 Step 2 的创建时验证形成闭环：Step 2 验证 change 包和主 spec 的一致性，Step 6 验证主 spec 和代码的一致性。两道门覆盖了 spec 生命周期的两端
102+
103+
---
104+
105+
## 篇幅与位置
106+
107+
- 在 Section 3 中，替换目前的三个分散的机制描述
108+
- 总论段保留（代码管理的类比），然后直接进入 walkthrough
109+
- 预估 1000-1500 字
110+
- Step 3 和 Step 5 可以简写（各 2-3 句），重点在 Step 1（change 包结构）、Step 2（创建时验证）、Step 4（合并时验证）、Step 6（同步检测）

‎en/README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -77,6 +77,8 @@ The book unfolds along a productivity ladder. Chapter 1 analyzes the structural
7777
* [Test Infrastructure First: Turning Specs into Executable Constraints](chapters/03a-test-first.md)
7878
* [Code Review: Catching Intent Drift That Tests Miss](chapters/03b-code-review.md)
7979
* [In Practice: AILock-Step's Verification Pipeline](chapters/03c-practice.md)
80+
* [Systems Need Iteration Too: Evolving Specs and Verification](chapters/evolution-v1.md)
81+
* [Part I Recap: From Closed Loop to Evolution](chapters/v1-conclusion.md)
8082

8183
### Part II: Scaling Agent Development (10→100x)
8284

‎en/SUMMARY.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@
1414
* [Code Review: Catching Intent Drift That Tests Miss](chapters/03b-code-review.md)
1515
* [In Practice: AILock-Step's Verification Pipeline](chapters/03c-practice.md)
1616
* [Systems Need Iteration Too: Evolving Specs and Verification](chapters/evolution-v1.md)
17+
* [Part I Recap: From Closed Loop to Evolution](chapters/v1-conclusion.md)
1718

1819
### Part II: Scaling Agent Development (5-10x → 100x)
1920

0 commit comments

Comments
 (0)