Claude Code 的工程化落地：Agent 篇做重度 Skill 或超长任务时，主 Agent 很容易出现“注意力

做重度 Skill 或超长任务时，主 Agent 很容易出现“注意力被上下文拖垮”的问题：信息越堆越多，判断开始飘，Token 花得飞快。我们团队第一次把大任务全塞给单 Agent 时，最明显的体感就是“它很努力，但越做越乱”。

这篇文章要解决的问题很直接：什么时候该用 SubAgents，什么时候该上自定义 Agent，什么时候才值得用 Agent Teams。你读完可以拿到一套可落地的选型方法，而不是一堆概念名词。

一、先抓住核心：上下文隔离

Claude Code 的多代理，不是把多个 Prompt 拼在一起，而是把任务拆到多个独立上下文里。子代理看不到主会话历史，也看不到其他子代理的中间推理结果。

这个设计像厨房分工：切菜、炒菜、摆盘各在自己工位干活，最后由主厨汇总出菜。好处是台面不会被“所有步骤同时展开”搞到一团糟。

你实际要记住两条：

主上下文更干净，核心任务不容易被搜索日志、临时推理淹没。
子代理 Prompt 必须自包含，不能默认它“知道前文发生了什么”。

二、第一层：CC 内置 SubAgents（够快、够轻）

内置子代理适合先把任务切薄，尤其是搜索、审查、方案梳理这类“信息多但可并行”的工作。

类型	模型	工具权限	典型场景
`Explore`	Haiku（快、成本低）	只读：`Read`、`Grep`、`Glob`	全仓搜索、文件定位、快速调研
`Plan`	继承主模型	只读	方案拆解、实现路径设计
`general-purpose`	继承主模型	全部工具	复杂多步任务执行
`claude-code-guide`	继承主模型	`Read`、`Bash`、`WebFetch`、`WebSearch`	Claude Code 使用问题排查

2.1 自动委派什么时候会触发

系统启动时将所有可用代理的 description（内置类型 + .claude/agents/ 自定义代理）注入 main Agent 的上下文。main Agent 根据当前任务意图匹配这些 description，命中后通过 Agent 工具 spawn 一个独立上下文的子代理执行。

2.2 前台与后台怎么选

默认是前台执行，主代理会等待结果。互不依赖的任务建议后台并行。

// 前台：结果回来后再继续
Agent({ description: "审查安全问题", prompt: "..." })

// 后台：并行执行，完成后通知
Agent({ description: "审查安全问题", prompt: "...", run_in_background: true })

我的经验是：只要下一个步骤必须吃到当前结果，就别并行；反过来，审查类任务天然适合并行。

2.3 改代码时优先开 worktree 隔离

当多个子代理都要改文件时，用 isolation: "worktree" 能显著降低冲突风险。

Agent({
  description: "重构认证模块",
  prompt: "...",
  isolation: "worktree"
})

这样每个子代理在独立 Git worktree 工作，互相不踩。改完有变更就保留分支，无变更会自动清理。

2.4 子代理 Prompt 的实用模板

子代理像新同事，任务描述越具体，返工越少。一个可复用的结构是：目标、已知信息、边界、输出格式。

审查 src/api/routes/ 下所有路由处理函数的错误处理。
重点关注：未捕获的异步异常、缺少输入校验的端点、SQL 注入风险。
已知 src/api/routes/health.ts 是健康检查，可跳过。
输出：按严重程度排序，每项包含文件路径、行号、问题描述、修复建议。
限制：200 字以内。

三、第二层：Custom Agents（把团队经验固化下来）

内置类型不够细时，就该上自定义 Agent。它的价值不只是“换个名字”，而是把你团队常识写进配置里，让 Agent 越跑越像你们自己人。

3.1 放在哪里

.claude/agents/：项目级，适合团队共享。
~/.claude/agents/：个人级，跨项目复用。

3.2 常用字段怎么配

字段	作用	示例
`tools`	工具白名单	`Read, Grep, Glob`
`disallowedTools`	工具黑名单	`Bash, Write`
`model`	指定模型	`haiku` / `sonnet` / `opus`
`maxTurns`	最大推理轮数	`10`
`permissionMode`	权限模式	`plan` / `acceptEdits`
`skills`	预加载 Skill	`- security-checklist`
`memory`	持久化记忆作用域	`project`
`background`	是否默认后台运行	`true`

3.3 一个安全审查 Agent 示例

下面这个配置是“只读审查型”，适合合并前把高风险问题先筛出来。

---
name: security-reviewer
description: 审查 OWASP Top 10、硬编码凭据、注入风险；适用于敏感模块改动。
tools: Read, Grep, Glob
model: opus
skills:
  - api-conventions
  - security-checklist
memory: project
---

你是安全审查专家。请按 Critical / High / Medium / Low 分组输出问题。
每项包含：位置、问题描述、修复建议。

几个关键点：

tools 限制是硬约束，比在 Prompt 里写“不要改代码”可靠得多。
skills 能把团队规范提前喂进去，减少“看起来对、其实不符合你项目”的误报。
memory: project 会沉淀审查经验，长期看准确率会明显提升。

3.4 调用路径

常见有 3 种：自动委派、命令行直启、Skill 中指定。

claude --agent security-reviewer

Skill 中指定通常写成 context: fork + agent。两者并不冲突，反而很适合组合：Skill 定义流程，自定义 Agent 提供领域能力。

四、第三层：Agent Teams（协作型重任务）

SubAgents 更像“主代理派单，子代理回报”。Agent Teams 往前再走一步：代理之间可以直接通信，不必每次都通过主代理中转。

Agent Teams 架构图

4.1 团队里有哪些角色

角色	职责
`Team Lead`	建队、分派任务、汇总结果
`Teammate`	独立执行子任务
`Task List`	共享任务与依赖关系
`Mailbox`	代理间消息通道

4.2 常见工具

Teammate      -> spawnTeam / cleanup
SendMessage   -> message / broadcast / shutdown
TaskCreate    -> 创建共享任务
TaskUpdate    -> 更新任务状态
TaskList      -> 查看任务列表
TaskGet       -> 查看任务详情

4.3 和 SubAgents 的差异

对比项	SubAgents	Agent Teams
通信方式	通过主代理中转	代理间直接通信
生命周期	任务结束即销毁	团队持续存在直到解散
适用场景	独立、可拆分子任务	多角色协作的复杂项目
Token 开销	较低	更高（官方文档示例约为 7 倍，视模式而定）
成熟度	生产可用	仍在实验阶段

4.4 已知限制

不支持会话恢复，/resume 和 /rewind 对 Teammate 无效。
一个 session 同时只能管理一个团队。
不支持嵌套团队，Teammate 不能继续创建自己的 Team。

五、落地选型：别一上来就“重武器”

很多人第一次接触多代理，会直接冲向 Agent Teams。说实话，我也这么干过，结果像拿吊车搬快递，能搬，但成本真不低。

更稳妥的路径是先从轻到重：

场景	推荐方案
单次搜索、定位文件	内置 `Explore`
只读分析、代码审查	自定义 Agent + `tools: Read, Grep, Glob`
多个可并行改动	`SubAgent` + `worktree` 隔离
强依赖协作型任务	`Agent Teams`
CI/CD 自动化编排	`Claude Agent SDK`

如果你要在流水线里跑自动化，Agent SDK 可以直接代码调用。

import { query } from '@anthropic-ai/claude-agent-sdk';

const result = query({
  prompt: '审查 src/api/ 下所有路由的错误处理'
});

for await (const message of result) {
  console.log(message);
}

from claude_agent_sdk import query

result = query(prompt='审查 src/api/ 下所有路由的错误处理')

for message in result:
    print(message)

我现在的习惯是：80% 场景用 SubAgents，15% 用自定义 Agent 强化领域能力，最后那 5% 真正跨角色协作的复杂任务，才上 Agent Teams。

Claude Code 的工程化落地：Agent 篇