前言

本文概括
继续复盘 Claude Code 在复杂研发任务中的使用经验。
本文重点整理 Worktree 并发隔离、验证机制、状态同步、失败案例、成本意识，以及人和 AI 的边界。
如果说上一篇解决的是“怎么让 AI 协作起来”，这一篇更关注“怎么避免协作越多越乱”。

Claude Code 使用经验目录
  1. Claude Code 使用经验（一）：从角色提示词到 SubAgent 协作 点击我查看
  2. Claude Code 使用经验（二）：验证闭环、状态同步与 Worktree 隔离 点击我查看(当前位置)

为什么协作之后还需要治理

上一篇讲到，固定角色提示词、SubAgent、规则文件和主子工作流分层，可以让 Claude Code 从“单点输出”变成“主从协作”。

但协作跑起来以后，新的问题也会出现。

比如：

  • 多个 SubAgent 同时改同一个工作区，文件互相影响
  • AI 输出了代码，却没有验证就说完成
  • 文档、代码、任务状态不一致，后续 Agent 读到旧信息
  • 主 Agent 汇总结果时，只看到产出，看不到风险

所以后半段经验的关键词不是“更快”，而是“可控”。

1
2
3
4
5
6
flowchart LR
    A["多 Agent 协作"] --> B["Worktree 隔离"]
    B --> C["独立验证"]
    C --> D["状态同步"]
    D --> E["统一审查与汇总"]
    E --> F["可靠交付"]

Worktree：让并发开发先隔离起来

当多个 SubAgent 可以同时执行任务后，最先暴露的不是能力问题，而是工作区污染问题。

如果多个任务都在同一个目录里改代码，就很容易出现：

  • 任务 A 的临时改动影响任务 B 的验证
  • 子 Agent 之间改到同一个文件，后写入的覆盖前面的
  • 某个实验性修改没有清理，导致后续判断失真
  • 最后很难定位问题到底来自哪一个任务

这时就需要用 git worktree 给不同任务准备独立工作空间。

一个简单的并发隔离示例

1
2
3
4
5
6
7
8
任务 A：用户资料页前端改造
- worktree-profile-ui

任务 B：资料保存接口调整
- worktree-profile-api

任务 C：测试和文档补充
- worktree-profile-check

对应的协作关系大概是：

1
2
3
4
5
6
7
8
9
10
flowchart TD
    A["主 Agent"] --> B["worktree-profile-ui\n前端任务"]
    A --> C["worktree-profile-api\n后端任务"]
    A --> D["worktree-profile-check\n验证/文档任务"]
    B --> E["独立验证"]
    C --> F["独立验证"]
    D --> G["独立检查"]
    E --> H["统一汇总与合并"]
    F --> H
    G --> H

Worktree 的意义不是让 AI “多开几个窗口”，而是让每个任务有自己的工程边界。

Worktree 解决的问题

它主要解决四类问题：

  • 文件隔离：不同任务不直接在同一工作区互相覆盖
  • 状态隔离：某个任务的临时状态不会污染其他任务
  • 验证隔离：每个任务可以在自己的环境里先判断是否通过
  • 回退隔离：某个方向失败时，更容易单独丢弃或重做

这一步很像真实团队里的分支开发。没有隔离时，并发越高，风险越大；有隔离后，并发才有可管理的基础。

Worktree 不是万能的

不过 Worktree 只解决“物理隔离”，不解决“认知同步”。

如果上游任务没有更新状态，下游 Agent 即使在独立 worktree 里，也可能基于错误前提继续开发。

所以 Worktree 后面必须跟着两个机制：验证机制和状态同步机制。

阶段结论：AI 并发开发的关键不只是并发，而是隔离。没有隔离，并发会把混乱放大。

验证机制：不要把产出误当成完成

AI 最容易制造的错觉，是“它已经输出了东西，所以任务完成了”。

但在研发任务里，输出代码、输出文档、输出测试建议，都只能算中间结果。

真正可交付，至少要满足：

1
产出存在 + 验证通过 + 状态回写

如果少了其中任何一项，都不应该轻易写成完成。

常见的完成错觉

我自己踩过的坑大概有三类：

  • 已输出代码，误以为功能完成
  • 已更新文档，误以为交付完成
  • 已列出测试建议，误以为已经验证

尤其是第三类最容易忽略。AI 说“建议运行 npm test”，和它真的运行并确认结果，是两件完全不同的事。

验证可以分成四层

1
2
3
4
5
6
flowchart LR
    A["代码产出"] --> B["代码级验证"]
    B --> C["运行级验证"]
    C --> D["任务级验证"]
    D --> E["交付级验证"]
    E --> F["标记完成"]

四层含义如下：

  • 代码级验证：代码是否符合目标，是否有明显逻辑问题
  • 运行级验证：项目能否构建、测试能否通过、页面是否可打开
  • 任务级验证：需求目标是否真的被满足
  • 交付级验证：文档、状态、风险说明是否同步补齐

一个可复用的验证记录模板

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
# 任务验证记录

## 改动内容
- ...

## 验证方式
- 单元测试 / 构建检查 / 页面检查 / 接口验证 / 人工核对

## 验证结果
- 通过 / 未通过 / 部分通过

## 未覆盖风险
- ...

## 当前结论
- 已完成
- 待进一步验证
- 存在阻塞

这个模板不复杂，但能强迫 AI 把“做了什么”和“怎么证明它可用”分开说。

阶段结论：在 AI 协作里，只有产出、验证、状态回写同时成立，才更接近真正完成。

状态同步：明确什么才是单一事实来源

多 Agent 协作最容易失控的地方，不是代码写错，而是状态不同步。

比如：

  • 代码已经改完，但任务文档还写着进行中
  • 文档已经更新，但实际代码没有落地
  • SubAgent 说完成了，但主 Agent 没有汇总回写
  • 后续 Agent 继续读取旧文档，做出错误判断

这些问题单看都不大，但在多 Agent 场景里会被快速放大。

单一事实来源怎么定

我比较推荐先把几类状态的准绳说清楚：

  • 代码真实状态，以代码仓库为准
  • 任务进度状态，以任务面板或状态文档为准
  • 协作规则，以 CLAUDE.md 或 AGENTS.md 为准
  • 最终汇报，必须引用最新代码、文档和验证记录

可以用一张图理解：

1
2
3
4
5
6
flowchart TD
    A["协作规则\nCLAUDE.md / AGENTS.md"] --> D["主 Agent 汇总判断"]
    B["代码仓库\n真实实现状态"] --> D
    C["任务状态文档\n进度与阻塞"] --> D
    E["验证记录\n测试与风险"] --> D
    D --> F["最终汇报"]

状态记录模板

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
# 任务状态面板

## 任务名称
- 用户资料编辑页改造

## 当前状态
- 进行中 / 已实现待验证 / 阻塞 / 已完成

## 负责人
- SubAgent A

## 依赖项
- 后端接口返回字段调整

## 最近更新时间
- 2026-07-03

## 备注
- 前端页面已实现，等待接口联调验证

这里有个细节很重要：状态不要只写“完成”或“未完成”，中间态要说清楚。

比如：

  • 已实现待验证
  • 已验证待合并
  • 已识别问题待修复
  • 阻塞，等待人工决策

这些状态比一句“差不多好了”更适合给后续 Agent 消费。

阶段结论：状态同步的关键不是多写文档，而是明确谁是准绳，以及每次变更后谁负责回写。

三个失败案例

这套方法不是一开始就设计好的，很多规则都是被问题逼出来的。

下面这几个案例，对我影响比较大。

案例一：任务完成了，但文档没更新

在早期固定角色提示词阶段，某个接口方案已经调整过，但共享文档没有同步更新。

后续角色继续读取旧字段定义，然后基于旧文档推进页面方案，最后前后端理解不一致。

这个案例说明：

  • 文档不会自动变成最新
  • 后续 Agent 很容易相信旧信息
  • 没有统一状态源时，每个角色都可能“自以为正确”

后来我开始要求每次任务完成后必须回写状态，就是被这个问题推动的。

案例二：主 Agent 上下文过长，压缩后丢失规则

在 SubAgent 早期使用中，主 Agent 承担了太多职责：拆任务、写代码、读文档、做汇总、追进度。

对话越来越长后触发上下文压缩，一些原本强调过的规则被弱化，后续又退回到“大而全单 Agent”模式。

这个案例说明：

  • 关键规则不能只放在聊天记录中
  • 主 Agent 不应该长期沉入代码细节
  • 规则文件和主子工作流分层是必要的

案例三：多个任务共用一个工作区，验证结果被污染

有一次多个子任务在同一个目录里交错推进。某个任务为了验证方便临时改了配置，结果影响到另一个任务的测试结论。

最后排查时，很难判断问题来自：

  • 功能代码本身
  • 临时配置
  • 另一个任务的未完成改动
  • 验证环境不一致

这个案例直接推动我引入 Worktree 隔离。

阶段结论：失败案例的价值不在于复盘谁做错了，而是把容易重复发生的问题沉淀成规则和流程。

成本意识：不是所有任务都值得上完整机制

多 Agent、Worktree、验证记录、状态同步都很有用，但不是所有任务都值得这样做。

如果一个任务只是改一行文案，却开多个 SubAgent、建多个 worktree、写一堆状态文档，那就本末倒置了。

适合轻量模式的场景

  • 单文件小改动
  • 一次性脚本
  • 纯说明性问答
  • 不需要并发推进的简单任务
  • 失败成本很低、很容易人工检查的任务

这类任务更适合单 Agent 快速完成，再做必要检查。

适合完整协作机制的场景

  • 中等复杂度以上的研发任务
  • 涉及需求、代码、测试、文档同步推进
  • 多个子任务可以并行，但存在冲突风险
  • 对可追踪性、稳定性要求比较高
  • 后续还会有人接着维护或复盘

一个简单判断标准

可以问自己三个问题：

  1. 这个任务是否跨多个阶段，而不是单点输出？
  2. 是否需要多角色或多任务协同？
  3. 是否存在并发冲突或状态误判风险？

如果大多数答案是“是”，就值得启用更完整的协作机制。否则，轻量处理通常更划算。

阶段结论：AI 协作不是越重越好，而是越匹配越好。成熟的提效方式，应该知道什么时候该简化。

人和 AI 的边界

即使 Claude Code 已经能完成大量分析、实现和验证工作，也不代表所有判断都应该交给 AI。

我现在会把边界分得更清楚：AI 适合做高频、结构化、可验证的工作；人必须保留取舍权、裁决权和兜底责任。

需求取舍必须由人决定

哪些需求先做，哪些不做，哪些延后，本质上是业务优先级判断。

AI 可以帮忙分析影响范围和实现成本，但不能替代人做最终取舍。

架构权衡必须由人把关

AI 可以提出方案，但架构决策往往涉及长期维护成本、团队经验、历史包袱和系统风险。

这些信息很多时候不在代码里，也不在当前对话里，必须由人来拍板。

上线风险必须由人兜底

AI 可以跑测试、整理验证结果、提示风险，但最终能不能上线，风险是否可接受，仍然要由人负责。

尤其是生产环境、权限、数据、安全相关改动，不能让 AI 自己做最终结论。

合规和安全边界不能让渡

涉及敏感数据、权限策略、审计要求、外部合规时，AI 只能作为辅助工具。

它可以帮助检查遗漏、整理清单、生成说明，但责任主体必须是人。

阶段结论：AI 越强，人越要清楚自己负责什么。边界清楚，提效才不会变成责任失控。

本篇小结

回看后半段实践，我觉得 Claude Code 提效真正进入复杂任务阶段后，关键不再是“让 AI 多做一点”，而是“让 AI 做得可控一点”。

可以把整套方法概括成下面这条路径：

1
2
3
4
5
6
7
flowchart LR
    A["主从协作"] --> B["Worktree 隔离"]
    B --> C["验证机制"]
    C --> D["状态同步"]
    D --> E["失败复盘"]
    E --> F["成本判断"]
    F --> G["人负责最终边界"]

我的最终经验是：

  1. 并发之前先隔离，否则多 Agent 会放大混乱
  2. 输出之后必须验证，否则产出不等于完成
  3. 状态必须有单一事实来源，否则后续 Agent 会基于旧信息行动
  4. 失败案例要沉淀成流程，而不是只当成一次事故
  5. 完整机制有成本，小任务不要硬套重流程
  6. AI 可以执行和辅助判断，但最终取舍、上线和兜底必须由人负责

Claude Code 带来的价值，不只是“让一个人写代码更快”。更长期的价值，是让我们开始思考：怎样把 AI 纳入一个可管理、可验证、可复盘的研发协作体系里。