当海风翻页时

1.1 传统模式的四个瓶颈#

传统软件工程的核心难题，是把人的意图精确翻译成机器能执行的指令。这条翻译链走过了机器码、汇编、高级语言、面向对象、框架与库几层抽象，每一层都在降低转化成本，但四个瓶颈一直没解决：

• 需求翻译损失：产品经理的需求文档到开发者的技术规格之间存在语义鸿沟
• 编码带宽：打字速度约 50 WPM，远低于思考速度
• 知识检索成本：在 Stack Overflow、文档和源码之间反复切换
• 上下文切换开销：多任务切换后，平均要 15 到 23 分钟才能回到原来的状态

1.2 LLM 改变了什么#

Matt Pocock 的判断是：AI 没有淘汰软件工程的基本原理，共享理解、TDD、模块化、反馈循环反而比以往更重要。Agent 能写出代码，只有工程纪律才能保证代码的正确性、可维护性和审美质量。

换个说法：AI 辅助软件工程把需求、设计、实现、测试、评审这套方法论搬进了人机协作。Agent 当执行者，人当战略家和审美仲裁者。

1.3 上下文窗口与 Token#

Token 是 LLM 处理文本的最小语义单元。分词（Tokenization）把原始文本转成 token 序列：

1
原始文本: "Matt Pocock 的 AI 编程工作流"
2
Token 序列: ["Matt", "Poc", "ock", "的", "AI", "编程", "工作", "流"]

常见的分词器有 OpenAI 的 tiktoken（BPE，Byte Pair Encoding）和 Anthropic 的专用分词器。

上下文窗口（Context Window）是模型单次推理能看到的 token 上限，属于架构层面的硬限制。它决定了单次对话能装多少历史消息、一次能处理多大的代码库，以及 Agent 的“记忆”能维持多久。

窗口内的注意力计算量随 token 数平方增长：

$C_{\text{attention}} = O(n^2 \cdot d)$

其中 $n$ 是 token 数，$d$ 是每个 token 的嵌入维度。token 翻倍，注意力计算量翻四倍。

实际工作流里有三条管理策略：

1. 用 /clear 重置。上下文超出有效推理区间后，/clear 把 Agent 恢复到系统提示词的初始状态。
2. 把关键信息写进持久文档。决策、设计意图、未解决的问题落到 plan.md、prd.md，新会话直接加载这些已知事实。
3. 少用 Compaction。把长对话压成摘要会丢掉精确的推理路径，Agent 的行为变得不确定，问题也难以复现。Matt Pocock 明确反对这么做。

1
糟糕的做法:
2
  长对话 → compact → 摘要 → 继续工作（行为不确定）
3

4
好的做法:
5
  长对话 → 关键决策写入文档 → /clear → 新会话加载文档 → 继续工作（行为确定）

Token 管理决定了切片粒度、会话生命周期和文档化策略，是整条工作流的硬约束。

1.4 Smart Zone 与 Dumb Zone#

Smart Zone 和 Dumb Zone 是对同一件事的经验划分：上下文里的 token 少时推理稳定，超过约 100K 之后质量断崖式下降。这个概念最初由 Dex Horthy（HumanLayer 创始人）提出，Matt Pocock 在演讲中沿用。

flowchart LR
    subgraph SmartZone["Smart Zone (~0-100K tokens)"]
        S1[推理清晰]
        S2[约束遵循良好]
        S3[输出风格稳定]
        S4[事实一致性高]
    end
    subgraph DumbZone["Dumb Zone (>100K tokens)"]
        D1[推理质量断崖下降]
        D2[丢失先前结论]
        D3[风格漂移]
        D4["Memento 效应"]
    end
    SmartZone -->|"超过阈值"| DumbZone

厂商宣传的窗口可以到 1M token，但可用窗口远小于这个数字，原因有两个。一是注意力稀释，token 数 $n$ 增加后，每个 token 对序列中其他位置的注意力权重被摊薄，有效注意力近似为

$\text{EffectiveAttention}(n) \propto \frac{1}{\sqrt{n}}$

二是位置编码退化，超长序列里位置编码（Positional Encoding）的区分度下降，模型难以精确区分相距较远的两个位置。

经验阈值分三段：

• 约 100K token 以内：Smart Zone，推理质量稳定
• 100K 到 200K：过渡区，质量开始下降但不致命
• 200K 以上：Dumb Zone，Agent 出现“记忆碎片”效应，像电影《Memento》的主角一样接不上早先的上下文

这个模型直接决定了四个设计动作：

Dumb Zone 是当前注意力机制的固有特征。工作流不该对抗它，而是围绕它设计切片粒度、会话生命周期和 Sub-Agent 分配。

2.1 Client Brief 客户需求文档#

Client Brief 是需求阶段的第一份输入文档。它用用户的语言（而不是开发者的语言）回答四个问题：谁是这个功能的用户、他们遇到什么问题、解决到什么程度算成功、有哪些已知约束。

标准模板如下：

1
# Client Brief: [功能/项目名称]
2

3
## 背景 (Background)
4
[描述当前状态和用户痛点]
5

6
## 目标用户 (Target Users)
7
- 用户类型 A：[描述]
8
- 用户类型 B：[描述]
9

10
## 核心需求 (Core Needs)
11
1. [需求 1] — 优先级：P0/P1/P2
12
2. [需求 2] — 优先级：P0/P1/P2
13

14
## 成功标准 (Success Criteria)
15
- [ ] 用户可以在 [场景] 中完成 [动作]
16
- [ ] [量化指标] 达到 [目标值]
17

18
## 约束与假设 (Constraints & Assumptions)
19
- 技术栈：[已有技术栈]
20
- 时间约束：[如有]
21
- 已知限制：[如 API 限制、向后兼容]
22

23
## 范围外 (Out of Scope)
24
- [明确不做什么]

这份文档的粒度决定了后面所有阶段的效率。写得太模糊，Grilling Session 要大量追问；写得太技术，会过早收敛到实现细节；写得刚好，Agent 知道“为什么做”，同时“怎么做”还留着探索空间。

一句话原则：Client Brief 说 What 和 Why，PRD 说 How。

回到方法论上，Client Brief 是需求捕获（Requirements Elicitation）在 AI 协作里的落地形式。它继承了用户故事（User Story）和需求规格的做法，区别是更结构化、更显式，方便 Agent 读。

2.2 Grilling Session 需求追问#

Grilling Session 是一种结构化的澄清方法：Agent 扮演面试官，对 Client Brief 里的每个主张系统性追问，直到歧义消除，或者落到不可再拆的假设。做法源于传统需求工程里的利益相关者访谈（Stakeholder Interview），区别是追问者不会疲倦。

追问集中在五个方面：

追问不能无限继续，满足以下任一条就停：

1. 用户主动收口，比如“先按这个方向做”，接受剩余的不确定性
2. 问题已经落到原子决策，属于“先做再看”、无法在实施前决定的那一类
3. 对话接近 Smart Zone 上限，token 预算不够了

Grilling Session 把“需求分析师”这个角色自动化了。代码写出来之前，Agent 和人已经对“要构建什么”有了共享理解（Shared Understanding）。

2.3 Destination 与 Journey#

Destination 和 Journey 是 Grilling Session 之后的两个互补产出。Destination 描述项目做完、用户实际使用时的最终状态，用现在时书写，仿佛一切已经完成。Journey 记录从当前状态走到 Destination 过程中的关键决策、被否决的方案和放弃的理由，相当于一份考古日志。

flowchart TD
    GS[Grilling Session] -->|"产生了大量对话<br/>含决策推理、否决方案"| J[Journey<br/>过程文档]
    GS -->|"提炼出最终目标状态"| D[Destination<br/>目标状态文档]
    D -->|"Agent 作为<br/>唯一真相来源"| IMPL[实施阶段]
    J -->|"人类回顾时<br/>理解为什么这样设计"| RETRO[复盘/改进]

分开维护的理由是两个文档的受众和生命周期不同：

Destination 模板：

1
# Destination: [功能/系统名称]
2

3
## 用户视角
4
用户打开 [页面/应用]，可以：
5
- [功能清单 — 用现在时描述已完成的功能]
6

7
## 技术架构
8
- 前端使用 [框架]，路由结构如下：…
9
- 后端 API 端点列表：…
10
- 数据模型：[简要描述核心实体]
11

12
## 关键交互流
13
1. 用户点击 [按钮] → [发生什么]
14
2. 系统 [自动行为]
15

16
## 非功能特性
17
- 性能：[目标]
18
- 安全：[要求]

Journey 记录决策和被否决的选项：

1
# Journey: [功能/系统名称]
2

3
## 决策记录
4

5
### 决策 1: [主题]
6
- **时间**: 2026-06-02
7
- **选项**: A / B / C
8
- **选择**: B
9
- **理由**: [为什么选 B]
10
- **被否决的选项及原因**:
11
  - A: [看似好但…]
12
  - C: [未来可能考虑，但当前…]
13

14
## 开放问题
15
- [ ] [问题描述] — 待后续验证

这个模式纠正了“把所有东西堆在对话历史里”的做法：把隐性知识（对话历史）转成显性知识（持久文档），以此对抗 Dumb Zone 的侵蚀。

3.1 PRD 驱动开发#

PRD（产品需求文档，Product Requirements Document）原本是产品管理里的核心文档。在 AI 辅助开发里，它的定位变了：

标准结构如下：

1
# PRD: [功能名称]
2

3
## 1. 背景与目标
4
- 当前问题：[一句话描述]
5
- 目标：[解决什么]
6
- 用户价值：[量化收益]
7

8
## 2. 用户故事 (User Stories)
9
- 作为 [角色]，我想要 [动作]，以便 [价值]
10

11
## 3. 功能规格 (Functional Spec)
12
### 3.1 [功能点 A]
13
- 输入：[参数]
14
- 处理：[逻辑描述]
15
- 输出：[结果]
16
- 边界情况：[空值、极值、并发]
17

18
## 4. 非功能需求 (Non-Functional Requirements)
19
- 性能：页面加载 < 200ms (P95)
20
- 安全：用户数据加密存储
21
- 可访问性：WCAG 2.1 AA
22

23
## 5. 验收标准 (Acceptance Criteria)
24
- [ ] Given [前提], When [动作], Then [预期结果]
25

26
## 6. 范围外 (Out of Scope)
27
- 明确不做的功能，防止范围蔓延

从 Client Brief 到 PRD 的转化链：

flowchart LR
    CB[Client Brief<br/>What & Why] -->|"Grilling Session<br/>消除歧义"| DEST[Destination<br/>目标状态]
    DEST -->|"结构化展开"| PRD[PRD<br/>What & How]
    PRD -->|"切片拆分"| ISSUES[Kanban Issues<br/>细粒度任务]

PRD 的作用是让所有参与者（人和 Agent）在写代码之前，对“要构建什么”和“怎么验证”达成一致。

3.2 垂直切片与水平切片#

水平切片按技术架构层拆工作：先做完所有数据层，再做所有 API 层，最后做所有 UI 层。

垂直切片按用户可见的功能单元拆工作：每一片同时穿透数据库、业务逻辑、API 和前端，端到端可验证。

水平切片的形状：

flowchart TD
    A[全部数据库]
    B[全部 API]
    C[全部 UI]
    D[最终验证]

    A --> B --> C --> D

垂直切片的形状：

flowchart LR
    A1[切片 1<br/>DB→API→UI]
    A2[切片 2<br/>DB→API→UI]
    A3[切片 3<br/>DB→API→UI]
    A4[切片 4<br/>DB→API→UI]

    A1 --> V1[验证]
    A2 --> V2[验证]
    A3 --> V3[验证]
    A4 --> V4[验证]

两种切法的差异：

垂直切片的方法论来源是《程序员修炼之道》（The Pragmatic Programmer）里的曳光弹（Tracer Bullet）：

曳光弹不是纸上设计，不是原型。它是真实代码，穿越了系统的所有层级，证明这些层级可以连接在一起工作。

在 AI 辅助开发里，第一颗曳光弹的目标是用最薄的代码穿越所有技术层，证明架构可行，然后以此为骨架逐步加内容。

1
曳光弹示例（课程平台游戏化功能）:
2

3
切片 1 (曳光弹): "用户完成一节课 → 在仪表盘看到积分 +10"
4
  穿越: 数据库(新增积分字段) → 业务逻辑(积分计算) → API(积分查询/更新) → 前端(仪表盘显示)
5
  工作量: 约 2 到 4 小时
6
  验证: 整条路径可演示
7

8
切片 2: "积分累积到 100 → 解锁徽章"
9
切片 3: "仪表盘排行榜"

Agent 天然倾向按层批量处理（所有 DB schema → 所有 API → 所有 UI），因为这在单个对话里最省事。垂直切片正是纠正这个倾向的手段：每一刀都留下可演示的产出，问题尽早暴露，多个切片能并行推进。

3.3 切片粒度#

切片太大就会滑进 Dumb Zone，推理质量崩溃；切片太小，切片之间的连接成本和上下文切换开销又会超过收益。粒度取决于功能复杂度、token 预算和依赖耦合度三个因素。

按 token 预算算，一个切片的上下文消耗是：

$T_{\text{total}} = T_{\text{context}} + T_{\text{code}} + T_{\text{error\_recovery}}$

$T_{\text{context}}$ 是任务上下文（PRD 摘要、技术栈信息、代码约定），$T_{\text{code}}$ 是代码生成，$T_{\text{error\_recovery}}$ 是 Agent 犯错后纠正的额外开销。约束只有一条：

$T_{\text{total}} \leq 100\text{K tokens}$

对照经验值：

出现下面任何一条，说明切片过大：

1. Agent 实施到一半开始遗忘 PRD 里的验收标准
2. 代码风格在切片后半段漂移，变量命名和缩进习惯都变了
3. 修 bug 进入“修好 A 引入 B、修好 B 又引入 A”的循环
4. 切片做完之后，花了超过 3 轮 /clear 才把修正补完

宁可多切几刀薄的，也不要让一个厚片滑进 Dumb Zone。

3.4 Kanban 与 HITL/AFK 任务分类#

Kanban（看板）来自精益制造，在这里用来把垂直切片组织成可视化的工作单元：

其中最关键的分类依据是 HITL 和 AFK：

flowchart TD
    ISSUE[新 Issue] --> CLASSIFY{分类判断}
    CLASSIFY -->|"涉及不可逆决策<br/>或审美判断"| HITL[HITL<br/>需要人类介入]
    CLASSIFY -->|"纯功能实现<br/>技术验证"| AFK[AFK<br/>Agent 自主完成]
    HITL -->|"人类决策后"| AFK
    AFK -->|"完成后"| REVIEW{审查}
    REVIEW -->|"通过"| DONE[Done]
    REVIEW -->|"需要修改"| AFK

提升吞吐量的核心是让 AFK 切片尽可能多，三条规则：

1. 每个 AFK 切片都要有明确的验收标准，否则 Agent 不知道“做完”的定义
2. HITL 切片尽量排在工作流早期，架构决策前置可以省掉返工
3. AFK 切片可以放到夜间并行，用好 Agent 的非工作时间

1
工作流时间线:
2

3
09:00  人类完成所有 HITL 切片的决策工作
4
09:30  启动 AFK 切片 1 到 4 并行
5
12:00  AFK 切片全部完成
6
14:00  人类审查 AFK 产出
7
15:00  启动下一批 AFK 切片
8
次日:  夜间 AFK 批次的结果等待审查

这套分类把人的位置从“编码瓶颈”挪到了“决策瓶颈”，而决策恰好是人擅长、Agent 不擅长的部分。

4.1 Sub-Agent 任务委派#

Sub-Agent（子代理）把复杂任务交给独立的 Agent 实例执行。每个 Sub-Agent 拥有三样东西：

• 独立的上下文窗口，这是对抗 Dumb Zone 的主要手段
• 只给它需要的工具
• 明确的任务描述和验收标准

flowchart TD
    MAIN[主 Agent<br/>Orchestrator] -->|委派| SA1[Sub-Agent 1<br/>实施切片 1]
    MAIN -->|委派| SA2[Sub-Agent 2<br/>实施切片 2]
    MAIN -->|委派| SA3[Sub-Agent 3<br/>实施切片 3]
    SA1 -->|返回结果| MAIN
    SA2 -->|返回结果| MAIN
    SA3 -->|返回结果| MAIN
    MAIN -->|"整合 + 审查"| REVIEW[人工 Review]

按隔离程度分三档：

任务描述模板：

1
# Sub-Agent Task: [任务标识]
2

3
## 背景 (Context)
4
[从 PRD 摘录的相关章节]
5

6
## 任务描述 (Task)
7
实现 [具体功能描述]。
8

9
## 输入
10
- 相关文件：[路径列表]
11
- 依赖的 Issue：[#issue-number]
12

13
## 验收标准 (Acceptance Criteria)
14
- [ ] Given [前提], When [动作], Then [预期]
15
- [ ] 所有现有测试继续通过
16
- [ ] 新增测试覆盖核心路径
17

18
## 约束
19
- 遵循项目中已有的 [代码风格/模式]
20
- 不要修改 [受保护的文件/目录]
21
- 使用 [指定的库/版本]

委派的价值在于隔离上下文窗口，而不只是让更多 Agent 同时开工。

4.2 依赖图与 Phase 编排#

切片之间的前置关系可以用有向无环图（Directed Acyclic Graph, DAG）建模：

$G = (V, E)$

$V$ 是切片任务集合 $\{v_1, v_2, ..., v_n\}$，$E$ 是依赖边集合 $\{(v_i, v_j) \mid v_i \text{ 必须在 } v_j \text{ 之前完成}\}$。无环约束要求不存在路径 $v_i \rightarrow ... \rightarrow v_i$。

课程平台游戏化功能的依赖图：

flowchart TD
    V0["v₀: 数据模型<br/>(积分/徽章实体)"] --> V1["v₁: 积分计算服务"]
    V0 --> V2["v₂: 徽章服务"]
    V1 --> V3["v₃: 积分 API 端点"]
    V2 --> V4["v₄: 徽章 API 端点"]
    V3 --> V5["v₅: 仪表盘积分显示"]
    V4 --> V6["v₆: 仪表盘徽章墙"]
    V5 --> V7["v₇: E2E 测试"]
    V6 --> V7
    V1 --> V8["v₈: 排行榜服务"]
    V8 --> V9["v₉: 排行榜 API"]
    V9 --> V10["v₁₀: 排行榜页面"]
    V10 --> V7

把这批任务划成若干个 Phase，要求同一 Phase 内的任务互不依赖、可以并行，Phase 之间按依赖顺序推进：

1
COMPUTE_PHASES(tasks, dependencies)
2
 1  visited ← {}
3
 2  phases ← []
4
 3  while |visited| < |tasks|
5
 4      current_phase ← []
6
 5      for each task in tasks \ visited
7
 6          if all dependencies of task are in visited
8
 7              ADD(current_phase, task)
9
 8      if current_phase is empty
10
 9          ERROR "Circular dependency detected"
11
10      ADD(phases, current_phase)
12
11      visited ← visited ∪ current_phase
13
12  return phases

示例输出：

关键路径（Critical Path）是 DAG 中从起点到终点的最长路径，决定项目的最短完成时间：

$\text{Makespan} = \max_{\text{path } p} \sum_{v \in p} \text{duration}(v)$

在上面这张图里，$v_0 \rightarrow v_1 \rightarrow v_8 \rightarrow v_9 \rightarrow v_{10} \rightarrow v_7$ 是关键路径，它经过排行榜功能。优化这条路径能直接缩短总工期。

4.3 屏障式并行与流水线并行#

parallel() 是屏障式并行（Barrier Parallelism）：所有任务同时启动，等最后一个完成才进入下一阶段。

pipeline() 是流水线式处理（Pipeline Processing）：每个任务依次通过所有阶段，不同任务可以同时处在不同阶段，任务 A 在第三阶段时任务 B 可以在第二阶段。

1
parallel() — 屏障式:
2
Phase 1: [A1] [B1] [C1]  ← 三个任务并行
3
         ═══ 屏障 ═══     ← 等待最慢的完成
4
Phase 2: [A2] [B2] [C2]
5
         ═══ 屏障 ═══
6
Phase 3: [A3] [B3] [C3]
7
时间:    |████████████████████████|  (串行阶段累加)
8

9
pipeline() — 流水线式:
10
Phase 1: [A1] [B1] [C1]
11
Phase 2:     [A2] [B2] [C2]
12
Phase 3:         [A3] [B3] [C3]
13
时间:    |██████████████████|  (更短)

选择依据：

flowchart TD
    Q1{阶段 N 是否需要<br/>阶段 N-1 的全部结果？}
    Q1 -->|是| PAR[使用 parallel()<br/>屏障式并行]
    Q1 -->|否| Q2{各任务的耗时<br/>差异大吗？}
    Q2 -->|差异大| PIPE[使用 pipeline()<br/>避免快任务等待慢任务]
    Q2 -->|差异小| EITHER[两者均可<br/>差异可忽略]

放到 Agent 编排里看：

1
// pipeline() — 推荐的 AI 开发编排
2
pipeline(
3
  [slice1, slice2, slice3, slice4],                // 4 个垂直切片
4
  slice => agent("架构审查", {phase: "Review"}),    // 阶段 1: 架构审查
5
  review => agent("实现", {phase: "Implement"}),    // 阶段 2: 实现
6
  impl => agent("测试", {phase: "Test"})            // 阶段 3: 测试
7
)
8
// 切片 1 在测试时，切片 2 在实现中，切片 3 在审查中，没有空闲等待
9

10
// parallel() — 不需要屏障时会造成空转
11
parallel([...slices].map(s => () => agent("审查", s)))
12
//  ═══ 等待所有审查完成 ═══
13
parallel([...slices].map(s => () => agent("实现", s)))
14
//  ═══ 等待所有实现完成 ═══
15
// 快任务在每个阶段后都要空等慢任务

默认选 pipeline()，只有在确实需要跨任务汇总信息时才用 parallel() 的屏障。

4.4 TDD 测试驱动开发循环#

TDD（测试驱动开发，Test-Driven Development）由 Kent Beck 在 1990 年代从极限编程（Extreme Programming, XP）的实践中提炼而来。核心思想是：写任何产品代码之前，先写一个会失败的测试。

三条不可妥协的法则：

这三条法则造出一个极短的反馈循环，通常不到 30 秒，保证每一步都有可验证的进展。

stateDiagram-v2
    [*] --> Red: 写一个失败的测试
    Red --> Green: 写刚好让测试通过的最小代码
    Green --> Refactor: 消除重复，改善设计
    Refactor --> Red: 下一个测试
    Refactor --> [*]: 功能完成

以课程平台的“完成课程获得积分”为例，走一遍完整循环。

第一步，RED，写一个失败的测试：

1
import { describe, it, expect } from "vitest";
2
import { PointsService, PointsRepository } from "./points_service";
3

4
class InMemoryPointsRepo implements PointsRepository {
5
  private data: Map<string, number> = new Map();
6

7
  save(userId: string, points: number): void {
8
    this.data.set(userId, points);
9
  }
10

11
  get(userId: string): number {
12
    return this.data.get(userId) ?? 0;
13
  }
14
}
15

16
it("用户首次完成课程，应获得 10 积分", () => {
17
  const repo = new InMemoryPointsRepo();
18
  const service = new PointsService(repo);
19

20
  service.completeLesson({ userId: "alice", lessonId: "math-01" });
21

22
  expect(repo.get("alice")).toBe(10);
23
});

第二步，GREEN，写刚好让测试通过的最小代码：

1
export interface PointsRepository {
2
  save(userId: string, points: number): void;
3
  get(userId: string): number;
4
}
5

6
export class PointsService {
7
  constructor(private repo: PointsRepository) {}
8

9
  completeLesson(opts: { userId: string; lessonId: string }): void {
10
    this.repo.save(opts.userId, 10); // 最小实现：不做任何检查
11
  }
12
}

第三步，补一个幂等性测试，顺手重构实现：

1
// 同一用户-课程对不重复计分
2
it("重复完成同一课程仍为 10 分", () => {
3
  const repo = new InMemoryPointsRepo();
4
  const service = new PointsService(repo);
5

6
  service.completeLesson({ userId: "alice", lessonId: "math-01" });
7
  service.completeLesson({ userId: "alice", lessonId: "math-01" });
8

9
  expect(repo.get("alice")).toBe(10);
10
});
11

12
// 重构后的实现
13
export class PointsService {
14
  private completed: Set<string> = new Set();
15

16
  constructor(private repo: PointsRepository) {}
17

18
  completeLesson(opts: { userId: string; lessonId: string }): void {
19
    const key = `${opts.userId}::${opts.lessonId}`;
20
    if (this.completed.has(key)) {
21
      return; // 幂等：已完成的课程不重复加分
22
    }
23
    this.completed.add(key);
24
    const current = this.repo.get(opts.userId);
25
    this.repo.save(opts.userId, current + 10);
26
  }
27
}

测试策略按金字塔分布：

在 AI 辅助开发里，TDD 的作用从“测试代码”变成了“验证 Agent 理解了需求”。Agent 先写测试，人审查测试是否准确反映需求，这比审查实现代码高效得多。

flowchart TD
    PRD[PRD + 验收标准] --> AGENT1["Agent: 根据验收标准写测试<br/>(RED — 测试先于实现)"]
    AGENT1 --> HUMAN1{人类审查测试}
    HUMAN1 -->|"测试正确反映了需求"| AGENT2["Agent: 实现代码使测试通过<br/>(GREEN)"]
    HUMAN1 -->|"测试偏离需求"| AGENT1
    AGENT2 --> AGENT3["Agent: 重构优化<br/>(REFACTOR)"]
    AGENT3 --> HUMAN2{人类审查最终代码}
    HUMAN2 -->|通过| DONE[完成]
    HUMAN2 -->|需要修改| AGENT2

在 AI 辅助开发中，测试就是对 Agent 实现指令的精确定义。如果人写不出验收测试，说明需求还不够清晰，需要回到 Grilling Session。

Agent 生成代码的速度极快，只有测试这个客观验证器，才能让人在不必逐行审查的前提下信任 Agent 的产出。

4.5 Pair Programming 人-AI 结对#

结对编程（Pair Programming）是 XP 的核心实践之一，两个开发者共享一台计算机：驾驶员（Driver）操作键盘，关注当前这行代码怎么写；导航员（Navigator）关注全局，思考战略方向、潜在问题和改进机会。角色每 20 到 30 分钟轮换一次。

换成人和 AI 结对，角色分配变了：

flowchart LR
    subgraph 传统结对
        H1[Driver<br/>人类] --- H2[Navigator<br/>人类]
    end
    subgraph PairAI["人-AI 结对"]
        AI[Driver<br/>AI Agent<br/>写代码] --- H3[Navigator<br/>人类<br/>审方向、审美判断]
    end

人的职责（Navigator）有四条：

1. 定义“好的代码”长什么样。AI 没有审美观，靠示例和反馈来校准。
2. 守住架构边界，防止 AI 为了一时方便破坏模块边界。
3. 识别代码异味。AI 容易产出“功能正确但设计难看”的代码。
4. 做不可逆决策，比如架构、技术选型、数据库 Schema 设计。

AI 的职责（Driver）也有四条：

1. 执行重复性编码任务，比如 CRUD 和样板代码
2. 生成测试用例和边界条件组合
3. 快速探索多种实现方案，供人挑选
4. 编写文档和注释，并保持与实现同步

人机结对继承了 Driver-Navigator 的分工思路，同时把人从打字员的角色里挪出来，放到架构师和审美仲裁者的位置上。

5.1 深模块的定义#

深模块（Deep Modules）是 John Ousterhout 在 2018 年的《A Philosophy of Software Design》里提出的设计原则：

深模块提供大量功能、实现庞大而复杂，但只暴露极简的接口。复杂性被封装在内部，对外部不可见。

深模块和浅模块的差别可以画成一张表：

Ousterhout 给了一个用来思考的比例式，但它无法精确定量：

$\text{Depth}(M) \propto \frac{\text{FunctionalityProvided}(M)}{\text{InterfaceComplexity}(M)}$

分子是模块为用户解决的问题的数量，分母是使用它需要了解的概念、函数签名和配置选项的数量。

第一个案例是 Unix I/O 系统调用：

1
// 5 个系统调用，封住了整个文件系统栈的复杂性
2
int fd = open("/path/to/file", O_RDONLY);   // 打开：涉及路径解析、权限检查、inode 查找
3
ssize_t n = read(fd, buf, sizeof(buf));      // 读取：涉及页缓存、磁盘调度、预读
4
off_t pos = lseek(fd, 0, SEEK_END);          // 定位
5
ssize_t n = write(fd, buf, len);             // 写入：涉及延迟分配、日志、写回
6
close(fd);                                    // 关闭

这 5 个函数封住了虚拟文件系统、页缓存、Buffer Cache、磁盘调度器、文件系统格式（ext4/XFS/NTFS/ZFS）、权限模型（ACL/Capabilities）、RAID 等一层又一层的复杂性。

反过来的案例是 Java I/O：

1
// 读一个文件要理解并实例化多个类
2
FileInputStream fis = new FileInputStream("file.txt");
3
BufferedInputStream bis = new BufferedInputStream(fis);
4
DataInputStream dis = new DataInputStream(bis);
5
// 装饰器链强迫用户理解每一层的概念

过度拆分成无数小类，每一个小类都是浅模块，Ousterhout 把这种做法叫作 Classitis（类炎症）。

深模块的思路是把抽象边界设计好，让使用者用最小的认知成本换到最大的功能收益。

5.2 深模块与 Clean Code 的分工#

Ousterhout 的《A Philosophy of Software Design》和 Robert C. Martin 的《Clean Code》代表了软件设计的两条路线：

实际项目里这两条路线可以分工，各管一层：

深模块管的是模块之间的架构决策，比如耦合和抽象边界；Clean Code 管的是模块内部的代码质量。两者不冲突。

5.3 Skill 设计中的深模块#

一个 Agent Skill 本身就是模块：接收输入（用户指令），执行内部实现（Agent 推理加工具调用），返回输出。深模块的几条原则可以直接搬过来：

1
浅 Skill（反模式）:
2
/setup-test-file → 只做"创建一个测试文件"
3
/run-tests → 只做"运行测试"
4
/check-coverage → 只做"检查覆盖率"
5
→ 用户需要记住 3 个命令，还要理解它们的依赖关系
6

7
深 Skill（推荐）:
8
/tdd → 完整封装 TDD 循环：创建测试 → 运行 → 根据结果生成实现 → 再次运行 → 检查覆盖率
9
→ 用户只用一个命令，内部自动处理所有步骤

Matt Pocock 开源的 skills 仓库是这套原则的规模化应用，其中四点值得记：

1. 每个 Skill 是一个 / 命令，接口只有一个词，实现是一整套工程方法论
2. Skill 内部可以调用 Sub-Agent，相当于模块内的私有函数
3. Skill 之间通过文档通信，相当于模块间的 API 契约（PRD → Issues → TDD）
4. 用 pipeline() 组合多个 Skill，而不是把每个步骤都做成独立 Skill

对照检查一个 Skill 是否够深：

• 它封装了一整套工程方法论，不只是一个步骤
• 用户用一个 / 命令就能触发全套流程
• 内部处理掉所有边界条件和错误恢复
• 产出是有持久价值的文档或代码，不是一次性输出

反过来，下面三种情况说明这个 Skill 太浅：只是对现有 CLI 命令的薄封装，那是 alias 不是 Skill；做的事太少，用户还得记住另一个 Skill 才能完成工作流；实现泄露到了接口上，用户必须先了解内部工作方式才能用。

如果发现自己在为工作流里的每个原子步骤都建一个 Skill，那是在制造 Skillitis（技能炎症）。

6.1 四阶段工作流总览#

flowchart TD
    IDEA[想法 / 需求] --> P1

    subgraph P1["阶段 1: 对齐 (Align)"]
        CB[Client Brief] --> GRILL["/grill-me<br/>需求追问"]
        GRILL --> DJ[Destination & Journey<br/>文档化]
    end

    P1 --> P2

    subgraph P2["阶段 2: 规划 (Plan)"]
        PRD["/to-prd<br/>生成 PRD"] --> ISSUES["/to-issues<br/>垂直切片拆分"]
        ISSUES --> KAN[Kanban 看板<br/>HITL/AFK 分类]
    end

    P2 --> P3

    subgraph P3["阶段 3: 实施 (Implement)"]
        KAN --> DISPATCH{任务分发}
        DISPATCH -->|AFK 切片| SA1[Sub-Agent 1]
        DISPATCH -->|AFK 切片| SA2[Sub-Agent 2]
        DISPATCH -->|AFK 切片| SA3[Sub-Agent N]
        SA1 --> TDD1["/tdd 循环"]
        SA2 --> TDD2["/tdd 循环"]
        SA3 --> TDD3["/tdd 循环"]
    end

    P3 --> P4

    subgraph P4["阶段 4: 评审 (Review)"]
        QA[人工 QA / 验收] --> CR["AI Code Review<br/>新会话中审查"]
        CR --> DECISION{通过？}
        DECISION -->|是| DONE[完成]
        DECISION -->|否| FIX[修复] --> P3
    end

四个阶段的分工：

Matt Pocock 对整套流程的概括是一句话：

不是 Vibe Coding，是 Real Engineering。

6.2 案例背景#

需求是给一个在线课程平台加游戏化功能：用户完成课程后获得积分、徽章和排行榜。这是演讲中使用的实际案例。案例规模不大，但四个阶段都走到了，中间出现过一次 HITL 决策和一轮修复。

6.3 阶段 1：Client Brief 与 Grilling#

Client Brief 由需求方写成，只描述问题、目标用户和成功标准：

1
# Client Brief: 课程平台游戏化功能
2

3
## 背景
4
当前平台是纯内容消费型，用户看完课程就结束了。
5
缺乏激励机制导致完课率仅 32%。
6

7
## 目标用户
8
- 学习者：需要成就感和进度可视化
9
- 讲师：需要了解学生参与度
10

11
## 核心需求
12
1. 积分系统 — 完成课程获得积分 — P0
13
2. 徽章系统 — 达到里程碑解锁徽章 — P1
14
3. 排行榜 — 显示积分排名 — P2
15

16
## 成功标准
17
- [ ] 完课率从 32% 提升到 45% 以上（A/B test）
18
- [ ] 用户平均学习时长增加 20% 以上
19

20
## 范围外
21
- 不包含社交功能（评论、好友）
22
- 不包含实物奖励

Grilling Session 追出五个隐含假设：

1
Q: 用户重复完成同一课程可以重复得分吗？
2
A: 不可以。每个用户-课程对只计分一次。
3

4
Q: 如果用户在后台修改课程完成时间怎么办？（作弊）
5
A: 积分以首次完成时间为准。后端验证，不以客户端时间为准。
6

7
Q: 排行榜需要实时更新吗？
8
A: 不需要。5 分钟延迟可接受，用缓存。
9

10
Q: 如果两个用户积分相同怎么排名？
11
A: 谁先到达该积分谁排前面（时间戳 tiebreak）。
12

13
Q: 徽章的逻辑是什么？规则引擎还是硬编码？
14
A: MVP 阶段硬编码 3 个徽章规则。未来可能抽象为规则引擎，
15
   但现在不建过早的抽象。

6.4 阶段 2：PRD 与切片拆分#

PRD 把追问的结论固化成三个功能点：

1
# PRD: 课程平台游戏化功能 v1
2

3
## 功能 1: 积分系统 (P0)
4
- 完成课程 → +10 积分（幂等）
5
- 积分存储在 `user_points` 表
6
- API: `POST /api/points/award`, `GET /api/points/{userId}`
7

8
## 功能 2: 徽章系统 (P1)
9
- 3 种徽章规则：
10
  a. "初学者" — 累计 50 积分
11
  b. "学霸" — 累计 200 积分
12
  c. "完美主义者" — 连续 7 天完成课程
13
- 徽章在数据库中预定义，判定逻辑放在业务层
14

15
## 功能 3: 排行榜 (P2)
16
- 全局积分排行 TOP 100
17
- 缓存策略：Redis，5 分钟 TTL
18
- API: `GET /api/leaderboard?limit=100`

接着按依赖关系拆成 5 个 Phase：

1
切片拆分 (DAG 结构):
2

3
Phase 1: v₀ — 数据模型 (HITL: 需人工确认 Schema 设计)
4
Phase 2: v₁ — 积分计算服务 + API (AFK)
5
         v₂ — 积分仪表盘显示 (AFK)
6
Phase 3: v₃ — 徽章判定服务 + API (AFK)
7
         v₄ — 徽章展示组件 (AFK)
8
Phase 4: v₅ — 排行榜服务 + API (AFK)
9
         v₆ — 排行榜页面 (AFK)
10
Phase 5: v₇ — E2E 测试 (AFK)
11
         v₈ — 性能测试 (HITL: 需人工设定吞吐量目标)

6.5 阶段 3：切片 v₁ 的 TDD 实施#

切片 v₁ 的 RED 和 GREEN 两步与 4.4 的例子同构，区别是这里把 PRD 里的三条验收标准都写成了测试：

1
describe("PointsService", () => {
2
  it("用户完成未完成过的课程 → 收到 10 积分");
3
  it("同一用户-课程对不重复计分（幂等性）");
4
  it("不同课程积分累加");
5
});

实现与 4.4 的最终版本一致：用一个 awarded 集合做幂等守卫，键是 userId::lessonId，命中就返回，否则把当前积分加 10 写回仓库，另外暴露一个 getPoints() 供外部查询。

6.6 阶段 4：评审#

1
人工 QA:
2
  正常流程：完成课程 → 积分增加
3
  边界条件：重复完成 → 积分不变
4
  并发场景：同时完成两门课 → 积分正确累加
5
  UI 反馈：积分变化的动画时长需要调整（审美判断）
6

7
AI Code Review (新会话中):
8
  幂等性守卫到位
9
  建议：awarded 集合在服务重启后会丢失，需要持久化到数据库
10
  测试覆盖了 PRD 中的所有验收标准
11

12
修复 → 本轮完成

这套流程走完，有四件事值得记：

• HITL 只出现在 Schema 设计和性能目标两处，其余全部是 AFK
• Grilling 砍掉的是作弊和实时性这两个隐含假设
• AI Review 在新会话里跑，不受实现过程的上下文污染
• 评审发现的问题回到阶段 3，再走一轮