一份配置生成三种编程助手子代理
文章比较 Claude Code、Cursor 与 Codex 的子代理配置位置、文件格式和字段差异,并提供从单一来源生成三套配置的脚本。还讨论技能与子代理的区别、只读限制及配置未加载的排查点。
AI 深度解读
同一个代码审查助手,放进 Claude Code、Cursor 和 Codex,配置格式、权限边界和触发方式都可能变。作者给出的办法是:只维护一份职责说明,再用脚本生成三套原生配置。
这套方案值得参考的地方,是把「哪些内容可以共用」和「哪些能力必须分别处理」分清了。不过,作者验证的是生成脚本与文件格式,没有在三个产品里实际运行代理。配置能解析,离代理按预期工作还有一步。
为什么值得单独建一个子代理
技能(skill)和子代理(subagent)解决的是两类问题。技能把指令补进当前对话;子代理启动一个拥有独立上下文的工作线程,完成任务后返回摘要。
如果一次排查要读大量文件、搜索结果和日志,子代理可以把这些中间材料留在自己的上下文里,主线程只接收结论。适合独立出去的,通常是反复出现、边界明确的工作,例如只报告失败的测试运行、文档研究,以及禁止修改文件的代码审查。
三个工具已经有内置助手:Claude Code 有 Explore 和 Plan,Cursor 有 explore 和 browser,Codex 有 default、worker 和 explorer。只有需要不同指令或限制时,才值得增加自定义配置。
作者建议先建两三个。每个子代理都要单独调用模型和工具,会增加 token 消耗。Cursor 文档把 50+ 个职责含糊的子代理列为反模式;Claude Code 则会在自定义代理描述合计超过 15,000 tokens 时发出启动警告。这些是文档提示,不是作者测得的最佳数量。
一份源文件能统一什么,不能统一什么
三个工具共同拥有的内容很少:name、description,以及提示词正文。
Claude Code 在项目的 .claude/agents/ 和个人的 ~/.claude/agents/ 读取带 YAML frontmatter 的 Markdown,也扫描子目录,以及工作目录向上直到仓库根目录沿途的 .claude/agents/。Cursor 读取 .cursor/agents/,兼容 .claude/agents/、.codex/agents/ 及用户主目录中的对应目录。Codex 使用 .codex/agents/ 和 ~/.codex/agents/ 下的 TOML。
Claude Code 和 Codex 以 name 字段识别代理;Cursor 缺少它时会回退到文件名。模型配置也不能直接照搬:sonnet 是 Claude Code 的别名,Cursor 接受 inherit 或模型 ID。两者共同有文档支持的值是 model: inherit。
因此,作者把源文件限制为 name、description、可选的 readonly 和正文。例如,这份 agents-src/code-reviewer.md 把审查范围与返回格式固定下来:
---
name: code-reviewer
description: Reviews changed code for bugs, security problems and missing tests, without editing anything. Use proactively after code changes, or when the user asks for a review of the current diff.
readonly: true
---
You are a senior code reviewer. You review; you never fix.
1. Read every file the parent agent names, and the code each change calls into.
2. Look for bugs, unhandled errors, security problems (secrets, injection, missing auth checks) and changed behavior without a test.
3. Skip style comments unless they hide a real bug.
Reply with findings grouped as Critical, Warning and Suggestion. Give file:line for each one and say how to fix it. If you find nothing, say so in one line.
要看的是 description:它同时交代了职责和使用时机。正文要求主代理指定文件,审查者因此不必依赖 git diff,也就可以不授予 Bash。
作者的 scripts/sync_agents.py 使用 Python 3,无需额外包,分别生成:
.claude/agents/code-reviewer.md,设置model: inherit,只读时加入tools: Read, Grep, Glob。.cursor/agents/code-reviewer.md,设置model: inherit和readonly: true。.codex/agents/code-reviewer.toml,把正文写入developer_instructions,只读时在前面补充禁止修改的指令。
修改源文件后运行 python3 scripts/sync_agents.py,把源文件和生成结果一起提交。CI 或 pre-commit hook 执行 python3 scripts/sync_agents.py --check,发现文件缺失或内容过期就退出,状态码为 1。
脚本拒绝未知字段、重复名称和非法名称,名称限定为小写字母、数字及单个连字符,正则是 ^[a-z0-9]+(-[a-z0-9]+)*$。但它不会删除多余文件,只会列出并保留。因此,删除源文件后,旧配置仍需人工处理。
真正容易出错的是权限、覆盖和加载
共用 readonly: true,不代表三个工具提供了相同的只读保证。
Claude Code 执行工具白名单,tools: Read, Grep, Glob 不提供写入能力。但加上 Bash 后,代理又能通过 shell 修改文件,需要用 permissions.deny 或 PreToolUse hook 约束。disallowedTools: Bash(git push *) 还有一个容易误读的行为:它会移除整个 Bash 工具,而非只禁这一条命令。主会话处于 bypassPermissions、acceptEdits 或 auto 时,子代理的 permissionMode 也会被忽略,沿用主会话模式。
Cursor 使用 readonly: true 限制文件编辑和改变状态的 shell 命令。但它虽然兼容 Claude 目录,文档只列出了 name、description、model、readonly、is_background,没有承诺支持 Claude 的 tools。所以脚本专门生成 Cursor 副本:同名时,.cursor/agents/ 中的配置优先。至于 Cursor 是否读取 Codex 的 TOML,作者没有确认。
Codex 的边界在父会话。子代理继承父回合的沙箱和审批设置,自定义文件里的 sandbox_mode、approval_policy、mcp_servers 不能覆盖它们。提示词可以要求不修改,但需要硬性只读时,必须先把委派所在会话设为只读沙箱。
触发方式同样不同。Claude Code 和 Cursor 会根据描述自行委派,use proactively 可以鼓励这种行为。按原文核对的文档,Codex 当前本地版本需要用户直接要求,或者由 AGENTS.md、技能指令明确要求。作者建议在 AGENTS.md 写入这样的触发规则:
After changing code, spawn the code-reviewer agent on the changed files and fix its Critical findings before you finish.
这里关键的是 spawn the code-reviewer agent:它把「什么时候创建哪个代理」写成了明确动作。
最后还有静默加载失败。Claude Code 会忽略不认识的字段,disallowed-tools、maxturns 这种拼错的字段不会报错。缺少 name 或 description、开头 --- 不在第一行、YAML 无法解析,以及名称以 - 开头、包含 : 或超过 256 字符,都可能导致文件被跳过。
排查可用 claude --debug 查看日志;Claude Code v2.1.233 起可运行 claude plugin validate .claude/agents,但它不会标记缺失 name。新建代理目录后还应重启会话,因为运行中的会话只监听启动时已经存在的目录。
我的判断
我认可「公共职责只写一次,平台差异交给生成器」这个方向。相比复制三份后分别维护,它更容易发现提示词漂移,也能把字段拼写错误提前变成明确失败。
但这份源格式只是小型约定,解析器按行拆字段,并不是完整的 YAML 解析器。它也没有承载各平台的全部能力;一旦需要平台专属模型、工具或权限策略,就要扩展生成规则,不能继续假设所有字段含义一致。
作者验证了配置生成,没有验证三个产品中的实际执行。
他们在临时 Git 仓库里,用审查者和测试运行者两个代理测试了写入、--check、子目录调用、手改生成文件、额外文件、错误字段、非法名称、缺失 frontmatter,以及包含 ''' 的提示词。输出用 PyYAML 或 Python 的 tomllib 解析,并检查必需字段与提示词一致性。
这些检查支持脚本的可靠性,但不能证明自动委派、权限执行和任务质量。原文也没有效率、成本或审查效果的对照数据,相关收益仍是工程经验判断。其文档核对日期是 2026-11-03,具体行为应以实际使用版本为准。
能拿来做什么
- 如果团队同时使用多个 AI 编程工具,可以先统一一个代码审查代理,在描述中明确职责、触发时机和输出格式,再逐步增加其他角色。
- 把生成文件纳入版本控制,并将
python3 scripts/sync_agents.py --check接入 CI;删除代理时,同时检查三个目标目录是否残留旧文件。 - 需要禁止审查者修改代码时,分别检查 Claude Code 的工具列表、Cursor 的
readonly和 Codex 父会话沙箱,不能只检查公共源文件。 - 首次配置后,在 Claude Code 的
@候选、Cursor 的/入口确认代理,再实际调用一次;Codex 则明确要求创建代理,并检查是否出现代理线程。