前言

本文概括
记录我使用 Claude Code 做研发提效时，如何从固定角色提示词演进到 SubAgent 主从协作。
重点整理固定角色提示词、SubAgent 协作、CLAUDE.md/AGENTS.md 约束、固定开发工作流、主子工作流分层。
这不是一篇工具白皮书，更像是一次被真实开发问题倒逼出来的个人复盘。

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

为什么要从提示词聊起

刚开始用 AI 编程工具时，我关注的其实很简单：它能不能帮我把代码写快一点。

但真正把 Claude Code 放进日常开发后，很快会发现一个更关键的问题：AI 不只是要会写代码，还要能在复杂任务里稳定协作。

一次性生成代码并不难，难的是：

  • 需求被拆开后，谁负责理解，谁负责实现，谁负责验证
  • 多个任务并行时，状态怎么同步
  • 对话变长以后，规则和历史决策怎么不丢
  • AI 说“完成了”以后，怎么判断它是真的完成

所以我的使用路径，大概经历了这样几个阶段：

1
2
3
4
5
6
flowchart LR
    A["固定角色提示词"] --> B["SubAgent 主从协作"]
    B --> C["CLAUDE.md / AGENTS.md 规则约束"]
    C --> D["固定开发工作流"]
    D --> E["主子工作流分层"]
    E --> F["验证、状态同步、Worktree 隔离"]

本文先讲前半段：从“用提示词模拟团队”，到“用 SubAgent 建立真正的协作链路”。

固定角色提示词：先把 AI 当成一个虚拟开发团队

最早的做法，是给 AI 固定几个角色，比如产品经理、前端工程师、后端工程师。

这套方式的核心不是让 AI “演得像”，而是让同一个需求能从不同视角被拆开。

产品角色提示词示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
你是一名产品经理，负责把用户需求转化为结构化研发输入。

你的职责：
1. 明确需求目标和业务背景
2. 拆分功能点和边界条件
3. 给出用户流程和异常场景
4. 输出研发可以直接消费的需求说明

输出要求：
- 功能目标
- 用户场景
- 关键流程
- 边界与异常
- 对前后端的具体要求
- 待确认问题

注意：
- 不直接写代码
- 不跳过边界条件
- 对不明确的信息要显式标注

前端角色提示词示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
你是一名前端工程师，基于产品需求输出前端实现方案。

你的职责：
1. 理解页面和交互需求
2. 拆分组件和状态管理
3. 识别接口依赖
4. 输出页面实现方案或代码草稿

输出要求：
- 页面结构拆分
- 组件划分
- 状态与交互说明
- 接口调用需求
- 异常态和空态处理
- 风险点

注意：
- 先分析，再编码
- 不假设后端接口一定完备
- 对不确定项要列出依赖

后端角色提示词示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
你是一名后端工程师，基于产品需求和前端依赖输出后端实现方案。

你的职责：
1. 设计接口和数据结构
2. 分析业务流程和校验逻辑
3. 识别异常场景和幂等问题
4. 输出实现方案或代码草稿

输出要求：
- 接口定义
- 请求与响应字段
- 核心业务逻辑
- 数据存储或模型建议
- 异常处理
- 测试建议

注意：
- 不忽略异常流程
- 不默认前端传参总是正确
- 对风险和依赖要显式说明

这套方式在早期很有用。它至少让我不再直接对 AI 说“帮我写个功能”，而是先让需求、页面、接口这些东西被拆开。

1
2
3
4
5
flowchart TD
    A["用户提出需求"] --> B["产品角色\n梳理目标、边界、异常"]
    B --> C["前端角色\n拆页面、状态、交互"]
    C --> D["后端角色\n补接口、字段、校验"]
    D --> E["汇总成研发方案"]

这个阶段解决了什么

固定角色提示词解决的是“AI 如何参与研发流程”的入门问题。

它的收益很直接：

  • 模糊需求更容易被拆成结构化内容
  • 产品、前端、后端不再混在一段回答里
  • 开发前会自然多一步分析
  • 对个人开发者来说，可以模拟一个小型研发团队

这个阶段的问题

但它的上限也很明显。

第一，角色之间没有真实协作。产品角色说完以后，前端角色并不会自动知道哪些结论已经落地，信息还是要靠人搬运。

第二，状态不可追踪。AI 输出了很多建议，但很难判断哪些已经实现、哪些只是方案、哪些还没验证。

第三，容易产生幻觉。尤其是文档没有更新时，后续角色可能会基于旧信息继续推进。

所以固定角色提示词适合入门，但不适合长期支撑复杂研发任务。

阶段结论：角色拆分可以让 AI 更像一个团队，但它还不是一个真正的协作系统。

SubAgent：从静态角色变成主从协作

后来我开始使用 SubAgent 模式。这个阶段最大的变化是：不再让多个角色各说各话，而是由主 Agent 统一接收目标、拆任务、分发、回收结果。

它更像一个“负责人 + 执行者”的结构。

1
2
3
4
5
6
7
8
flowchart TD
    A["主 Agent\n理解目标 / 拆分任务 / 汇总结果"] --> B["SubAgent A\n局部分析"]
    A --> C["SubAgent B\n代码实现"]
    A --> D["SubAgent C\n验证或文档"]
    B --> E["结构化回传"]
    C --> E
    D --> E
    E --> A

一个常见分工可以这样写：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
主 Agent：
- 读取需求
- 判断任务依赖
- 拆分子任务
- 分发给不同 SubAgent
- 汇总结果和风险

SubAgent A：
- 负责接口分析和后端实现

SubAgent B：
- 负责前端组件改造和交互补齐

SubAgent C：
- 负责验证点梳理和文档收尾

这一步比固定角色提示词更实用，因为任务开始有了“调度者”。

SubAgent 解决的问题

SubAgent 模式主要解决了三件事：

  • 不同任务可以围绕同一个目标推进
  • 主 Agent 可以统一管理进度和依赖
  • 子任务可以交给更聚焦的执行者处理

对复杂任务来说，这比让一个 AI 从头做到尾稳定很多。

尤其是跨前端、后端、测试、文档的任务，如果全部放在一个对话里，很容易上下文膨胀。拆给 SubAgent 后，局部任务的上下文会小很多，执行也更专注。

SubAgent 暴露的新问题

不过 SubAgent 并不会自动带来秩序。

我遇到过几个典型问题：

  • 主 Agent 一边调度一边写代码，最后又变回“大而全单 Agent”
  • SubAgent 接到任务后顺手扩张范围，改了不该改的文件
  • 任务完成后没有标准化回传，主 Agent 不知道风险在哪里
  • 长对话触发压缩后，前面约定的规则被弱化

这时问题的本质已经不是“有没有协作”，而是“协作有没有治理”。

阶段结论：SubAgent 解决了协作链路问题，但没有自动解决职责边界和规则稳定问题。

用 CLAUDE.md / AGENTS.md 固化协作规则

在 SubAgent 使用一段时间后，我开始把关键规则写进 CLAUDE.md 或 AGENTS.md。

原因很简单：不要把长期规则只放在聊天记录里。

聊天记录会变长，会压缩，会被遗忘；但项目规范文件可以被反复读取，也更适合作为团队共识。

主 Agent 规范示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
# 主 Agent 规范

## 角色定位
你是任务总控，不是主编码者。

## 核心职责
1. 理解需求目标
2. 拆分任务并分发给 SubAgent
3. 跟踪任务进度和依赖关系
4. 汇总结果并形成最终输出

## 禁止事项
1. 不长时间沉入局部代码实现
2. 不替代 SubAgent 完成完整编码任务
3. 不在未确认状态的情况下宣布任务完成

## 输出要求
1. 所有任务拆解必须显式列出
2. 所有阶段结论必须可追踪
3. 汇报时必须区分“已完成”“待验证”“待确认”

SubAgent 规范示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
# SubAgent 规范

## 角色定位
你是具体任务执行者，不负责全局调度。

## 核心职责
1. 接收明确子任务
2. 完成分析、实现或局部验证
3. 只处理任务边界内的文件
4. 将结果结构化回传主 Agent

## 禁止事项
1. 不自行扩张任务边界
2. 不替代主 Agent 调整全局计划
3. 不在缺少依据时假设其他任务已完成

## 回传要求
1. 修改了哪些文件
2. 执行了哪些验证
3. 发现了哪些风险
4. 哪些问题未完成或仍有阻塞

这些规范看起来有点啰嗦，但实际价值很高。

它们不是为了限制 AI，而是为了防止 AI 在长任务里“漂移”。

规则文件解决的问题

把规则文件化以后，变化很明显：

  • 主 Agent 更不容易沉入局部实现
  • SubAgent 更清楚自己不能乱扩范围
  • 每次任务开始前都有统一约束
  • 长对话压缩后，也能通过文件重新找回规则

但规则文件只能解决“谁该做什么”，还不能解决“应该按什么顺序做”。

这就需要固定开发工作流。

阶段结论：AI 协作不能只靠临时提示词，关键规则必须文件化，才能从个人习惯变成可复用资产。

固定开发工作流：让任务少漏步骤

在角色边界稳定后，我开始给 Claude Code 任务固定一套开发工作流。

一个通用版本如下：

1
2
3
4
5
6
7
8
1. 需求理解
2. 任务拆解
3. 方案确认
4. 代码实现
5. 局部验证
6. 文档更新
7. 状态回写
8. 结果汇报

对应到执行过程，可以画成这样：

1
2
3
4
5
6
7
8
flowchart LR
    A["需求理解"] --> B["任务拆解"]
    B --> C["方案确认"]
    C --> D["代码实现"]
    D --> E["局部验证"]
    E --> F["文档更新"]
    F --> G["状态回写"]
    G --> H["结果汇报"]

工作流模板示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
# 开发工作流

## 阶段 1：需求理解
- 明确目标、范围、输入输出
- 标注不确定项

## 阶段 2：任务拆解
- 拆成可独立执行的子任务
- 标注任务依赖和前置条件

## 阶段 3：方案确认
- 形成实现思路
- 明确风险点和验证方式

## 阶段 4：代码实现
- 按既定边界改动
- 不随意扩展需求

## 阶段 5：局部验证
- 至少进行与改动对应的验证
- 记录验证结果

## 阶段 6：文档更新
- 更新需求、说明、任务状态

## 阶段 7：状态回写
- 标记完成情况
- 区分完成、待验证、阻塞

## 阶段 8：结果汇报
- 汇总改动
- 明确风险、待办和下一步建议

固定流程带来的收益

固定工作流最大的意义，是减少“看起来做了很多，但其实漏了关键步骤”的情况。

比如以前很容易出现：

  • 代码写了，但没有跑验证
  • 文档改了，但任务状态没更新
  • SubAgent 说完成了，但没有说明风险
  • 主 Agent 汇总时，只看到了产出，没有看到验证结果

工作流固定后，这些问题更容易暴露出来。

阶段结论：AI 提效不只靠模型能力，也靠稳定流程。流程越清楚，返工越少。

主子工作流分层：不要让所有 Agent 做同一套事

固定工作流跑久了以后，又会遇到一个新问题：如果主 Agent 和 SubAgent 都走同一套流程，反而会变重。

主 Agent 应该做管理，SubAgent 应该做执行。两者需要不同粒度的工作流。

主 Agent 工作流

1
2
3
4
5
6
7
8
9
1. 接收任务目标
2. 明确范围与优先级
3. 判断任务依赖
4. 拆分子任务
5. 分发给 SubAgent
6. 跟踪进度与风险
7. 回收结果
8. 汇总验证情况
9. 输出最终汇报

SubAgent 工作流

1
2
3
4
5
6
1. 接收明确子任务
2. 阅读相关规范和上下文
3. 确认文件边界和目标边界
4. 完成局部实现或验证
5. 执行与任务匹配的检查
6. 回传文件、验证、风险、阻塞

两者的关系可以理解为：

1
2
3
4
5
6
7
8
flowchart TD
    A["主 Agent\n目标管理 / 任务拆分 / 进度跟踪 / 结果汇总"] --> B["SubAgent 1\n局部分析与实现"]
    A --> C["SubAgent 2\n局部分析与实现"]
    A --> D["SubAgent 3\n验证与审查"]
    B --> E["标准化回传"]
    C --> E
    D --> E
    E --> A

分层之后的变化

主子工作流分层后，协作会更接近真实研发团队：

  • 主 Agent 不再长期陷入局部代码细节
  • SubAgent 不需要背全部全局上下文
  • 每个子任务的输入、输出、验证边界更清楚
  • 主 Agent 汇总时更容易判断当前状态

这一步非常关键。因为很多 AI 协作失败，不是因为 AI 不会写代码，而是因为所有角色都在做所有事。

阶段结论：主 Agent 和 SubAgent 不只是职责不同，工作流也应该不同。只有分层，协作才不会重新退化成单 Agent 模式。

本篇小结

从固定角色提示词到 SubAgent 协作，我最大的感受是：AI 提效不是简单地“写一个更好的 prompt”。

更稳定的路径应该是：

  1. 用固定角色提示词解决入门阶段的视角拆分问题
  2. 用 SubAgent 建立真实的主从协作链路
  3. 用 CLAUDE.md / AGENTS.md 固化规则，减少长对话漂移
  4. 用固定开发工作流降低漏步骤和返工概率
  5. 用主子工作流分层控制上下文压力和职责边界

如果只停留在提示词层面，AI 很容易变成一个“很会输出内容的助手”。但当角色、规则和流程都逐步稳定后，它才更像一个可以参与研发协作的工程伙伴。

下一篇会继续整理后半段：当 SubAgent 可以并行执行后，为什么还需要 Worktree 隔离、验证闭环、状态同步，以及为什么人仍然必须保留最终判断权。