Claude Code 与 Cursor 的子代理对照：任务怎么分下去、上下文怎么隔开

2026-08-18

会想到 subagent，通常是被同一件事逼的：主对话里塞满了搜索结果、测试输出、日志，真正要决策的那几句被埋在中间。这一点两边文档口径一致——Claude Code 官方文档说，当一个附带任务会用你以后不会再引用的搜索结果、日志、文件内容淹没主对话时就该用它；Cursor 官方文档《Subagents》页也把 context isolation 列在第一位。

差异出现在下一层：**你能把这个 worker 定义到多细，以及分下去之后它的上下文和文件改动被隔到什么粒度。**这篇只对照两边文档都白纸黑字写了的部分，一方查不到的就直说不比。

一、定义文件放在哪，谁覆盖谁

两边都是「Markdown 文件 + YAML frontmatter，正文即系统提示词」这一套。查找位置和优先级不同。

Claude Code 官方文档《Create custom subagents》页给了一张作用域表，从高到低五档：managed settings（组织级）、--agents CLI 参数（仅当前会话）、.claude/agents/（当前项目）、~/.claude/agents/（你的所有项目）、plugin 的 agents/ 目录（最低）。同名时高优先级的那份生效。还有两件容易踩的：项目级 subagent 是从当前工作目录向上一路找到仓库根，每层的 .claude/agents/ 都会被扫；目录递归扫描，可以用 agents/review/ 这样的子文件夹归类，但身份只来自 frontmatter 的 name，子目录路径不参与识别，文件名也不必和 name 一致。

Cursor 官方文档《Subagents》页的位置表是这样的：

类型	位置	作用域
Project subagents	`.cursor/agents/`	当前项目
	`.claude/agents/`	当前项目（Claude 兼容）
	`.codex/agents/`	当前项目（Codex 兼容）
User subagents	`~/.cursor/agents/`	当前用户的所有项目
	`~/.claude/agents/`	当前用户的所有项目（Claude 兼容）
	`~/.codex/agents/`	当前用户的所有项目（Codex 兼容）

同名时项目级优先于用户级，.cursor/ 优先于 .claude/ 或 .codex/。

这张表值得停一下：Cursor 明说它会去读 .claude/agents/，同一批文件两边都可能加载到。但能加载 ≠ 字段都认，下面这节就是差异所在。

二、frontmatter：控制面的宽窄分界

Cursor 文档的配置字段表一共五个：name（可选，默认从文件名派生）、description（可选）、model（默认 inherit）、readonly（布尔，默认 false，为 true 时子代理以受限写权限运行，不做文件编辑、不跑会改变状态的 shell 命令）、is_background（布尔，默认 false，为 true 时后台运行、不阻塞父代理）。这些是文档写明的默认值，随版本可能变动。

Claude Code 的字段表长得多，只有 name 和 description 必填，与分任务直接相关的有 tools、disallowedTools、model、permissionMode、maxTurns、skills、mcpServers、hooks、memory、background、effort、isolation。

共有部分先对齐：name / description / model 两边都有，语义一致——description 决定父代理什么时候把活派给它，两边都建议在描述里写「use proactively」这类措辞；model: inherit 两边也都是默认。一处口径差异值得记一笔：name 在 Claude Code 文档里必填，在 Cursor 文档里可选、缺省从文件名派生。

真正的分界在权限粒度上。Cursor 给的是一个布尔开关 readonly，要么能写要么不能写；它的 FAQ 另写明子代理继承父代理的全部工具，包括已配置服务器的 MCP 工具（同一条 FAQ 写明云端子代理是例外，见第四节）。Claude Code 给的是按工具名的两个列表，tools 当白名单用：

---
name: safe-researcher
description: Research agent with restricted capabilities
tools: Read, Grep, Glob, Bash
---

disallowedTools 当黑名单用，继承整个工具池再挖掉几个：

---
name: no-writes
description: Inherits the available tools except file writes
disallowedTools: Write, Edit
---

两个都设时先应用 disallowedTools，再在剩下的池子里解析 tools，同时出现在两边的工具会被移除。两个字段还都接受 MCP 服务器级的模式：mcp__<server> 或 mcp__<server>__* 一次性授予或移除该服务器的全部工具，disallowedTools 里的 mcp__* 移除任何服务器的全部 MCP 工具：

---
name: local-only
description: Inherits every tool except those from the github MCP server
disallowedTools: mcp__github
---

以上片段均原样取自 Claude Code 官方文档，未经实测，以官方文档与 --help 的实际输出为准。

这个差异什么时候会咬到你：如果你要的只是「这个 reviewer 不许改文件」，两边都做得到——Cursor 写 readonly: true，Claude Code 写 disallowedTools: Write, Edit。但如果要的是「可以跑 Bash，但不许碰某一台 MCP 服务器」这种斜着切的边界，我们在 Cursor 的文档里没有找到按工具名或按 MCP 服务器切分子代理工具集的字段，这一维度不比。

反过来，Cursor 在模型这一侧有 Claude Code 文档里没有的写法：模型 ID 后接方括号写 id=value 选项，多个用逗号分隔，文档给的例子是 claude-opus-5[effort=high]（示例值，平台上有哪些模型随时在变，别当清单用）。Claude Code 侧的对应是独立的 effort 字段，可用档位取决于模型。

三、子代理启动时，手里到底有什么

这是「上下文隔离粒度」真正的落点，也是两边文档详略差最大的一处。Cursor 的说法很短：子代理以干净上下文启动，没有此前对话历史的访问权，所以父代理需要在 prompt 里带上必要信息。

Claude Code 文档《What loads at startup》一节把非 fork 子代理的初始上下文逐项列了出来：它自己的系统提示词加环境细节（不是完整的 Claude Code 系统提示词）、父代理写的委派任务消息、CLAUDE.md 层级里主对话会加载的每一级（含项目规则、CLAUDE.local.md 与受管策略文件）、父会话启动时拍下的 git status 快照、skills 字段点名预载的技能全文，以及一份兄弟代理名册。同一节还列了不会过去的：父对话历史与工具结果、父代理的系统提示词、output style、主对话的 auto memory；上下文窗口按子代理自己的模型算，不按父代理。

内置子代理还有个例外：Claude Code 的 Explore 与 Plan 会跳过 CLAUDE.md 和 git status，文档写明没有任何 frontmatter 字段或按代理的设置能改这一点，某条规则确实必须进去时（文档举的例子是「忽略 vendor/ 目录」）就在委派 prompt 里重述一遍。

实际影响：把团队规范写在项目级规则文件里指望子代理照着做时，Claude Code 文档明确告诉了你哪些代理会加载、哪些不会；Cursor 的文档里我们没有找到项目规则是否随子代理一起加载的说明，这一点不比——它给出的可靠做法只有一条：父代理把必要信息放进 prompt。

还有一个排查时容易绕晕人的机制：Claude Code 文档写明后台运行的子代理会被再过滤一层、收窄内置工具集（MCP 工具保留），同一份定义在前台和后台可能解析出不同的工具集，且这种移除本身不报错，除非把 tools 过滤到一个都不剩。Cursor 也区分 Foreground / Background，但我们没有在它的文档里找到「后台运行会改变可用工具集」的说明，不比。

四、文件改动隔到哪一层

两边都有「让子代理在别的地方改文件」的形态，但落点不同。

Claude Code 是 isolation: worktree：子代理跑在临时 git worktree 里拿到仓库的隔离副本，文档写明默认从你的默认分支切出而不是父会话的 HEAD，子代理没有产生改动时该 worktree 自动清理。围绕它有一组检查：命令在 worktree 内执行，工作目录解析到主 checkout 的会失败；对 Bash 命令还额外检查命令本身，挡掉把 git 重定向进主 checkout 的命令，也拒绝它无法确认「留在 worktree 内」的命令形状——即使命令里根本没有 git。

Windows 侧要单独记一句：文档写明 PowerShell 命令只做工作目录检查，不做上面那两项命令内容检查——同一份定义在 Windows 上走 PowerShell 与在 Linux/macOS 上走 Bash，被拦住的命令范围不一样。frontmatter 里挂 hook 也是分开的：文档给的校验脚本示例是 Bash，并注明 macOS 与 Linux 上要 chmod +x，否则 hook 不是「挡住」而是直接失败；Windows 上要把脚本写成 PowerShell 并在该 hook 条目里加 shell: powershell。

Cursor 的对应形态是 cloud subagent：文档写明输入 /in-cloud，接下来提交的任务就作为云端子代理运行，起自己的 VM 和分支；另有 /babysit 让它去盯一个 PR。一条硬边界值得抄下来：云端子代理用的是团队在 cursor.com/agents 上配置的 MCP 服务器，不是你本地会话里的那些，并使用为你的仓库配置的 environment。

两边都能把改动隔开，但隔离介质不同：一边是本机临时 worktree，一边是云端 VM 加分支。咬到你的时候通常是这样——云端那条路要先有为仓库配置好的 environment，文档写明云端子代理用的就是它；worktree 虽在本机，但文档写明默认从默认分支切出而不是父会话的 HEAD。两边都不等价于「你当前那份工作区」。

五、嵌套与恢复

嵌套深度：Claude Code 文档写明默认允许在主对话之下嵌套三层，用环境变量 CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH 调整，设 1 即关闭嵌套；这是文档写明的默认值，随版本可能变动（文档记载 v2.1.219 才把默认提到三层，更早的版本行为不同）。它可以写进 settings.json：

{
  "env": {
    "CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH": "2"
  }
}

Cursor 文档 FAQ 给的是固定规则而非可配项：自 Cursor 2.5 起主代理和它的直接子代理可以启动子代理，但由另一个子代理启动的子代理不能再启动；嵌套还需要当前模式有 Task tool 访问权，hooks 或工具策略可以阻止 spawn。

并发上限只写机制：Claude Code 文档写明存在一个并发上限，达到后再 spawn 会返回 Concurrent subagent limit reached，可用 CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS 调整；Cursor 文档里我们没有找到并发上限的说明，不比。

恢复：两边都是「拿 agent ID 续上」。Claude Code 用 SendMessage，以 agent 的 ID 或名字作 to，并写明内置 Explore 与 Plan 是一次性的、不返回 agent ID，要续跑就用 general-purpose 或自定义子代理。Cursor 每次执行返回一个 agent ID，在 prompt 里写 Resume agent abc123 ... 续上，后台子代理的输出写在 ~/.cursor/subagents/。

六、从你的处境倒推

把上面几节压成一条决策路径：

只想让主对话别被日志刷爆——两边都够用，不必挑，文档给的建议也一致。
要按工具粒度卡边界（能跑命令但不许碰某台 MCP 服务器）——看 Claude Code 的 tools / disallowedTools；Cursor 文档里只有 readonly 这个布尔开关，更细的粒度我们没有依据。
依赖项目级规则文件约束子代理——Claude Code 明写了哪些代理加载 CLAUDE.md、哪些跳过；Cursor 侧没有对应说明，按它自己的建议把规则放进委派 prompt。
要把文件改动隔到别处——本机隔离看 isolation: worktree（默认基分支不是父会话 HEAD，Windows 上 PowerShell 的检查项少于 Bash）；云端隔离看 /in-cloud（MCP 来自团队配置而非本地会话）。
跨工具共用一批定义文件——把 name / description / model 当公共部分，permissionMode、skills、hooks、isolation 这些在 Cursor 的字段表里找不到对应项，其余按各自文档补。

两个产品迭代都很频繁，本文提到的字段、默认值与版本号随版本变动，请以各自官方文档最新内容为准。

本文依据 Claude Code 官方文档（code.claude.com/docs）于 2026-08-17 的公开内容整理。该产品闭源，本文只复述官方文档写明的机制，不推断其内部实现； 我们没有对文中涉及的功能做过实测，因此不涉及界面外观、操作手感与运行速度的任何描述。该产品迭代频繁，文中涉及的命令、配置项与默认值随版本变动，请以官方文档最新内容为准。本文不涉及价格、额度与限流的具体数值，相关信息请以官方定价与用量说明页为准。

本文涉及的另一方内容依据其官方文档整理（Cursor：cursor.com/docs）。双方均为闭源商业产品，本文只对照各方公开写明的机制，不推断实现，也不对产品做优劣排名。

安全与合规相关做法请结合自身环境评估，本文不构成安全方案建议。