Subagent

建议

配置 Subagent 时，建议先让 AI 帮你生成角色定义、工具权限和输出格式，再由你人工确认文件边界、权限范围和是否允许写入。

Subagent 是专门处理某一类子任务的独立代理。它通常有自己的上下文、角色提示、工具权限和模型配置，适合把复杂任务拆成多个相互独立的工作单元。

常见用途：

• 让一个代理只读代码并做调查
• 让一个代理专门审查 Git diff
• 让一个代理补测试或跑验证
• 让多个代理并行处理不同模块
• 把高噪声搜索、日志分析、文件扫描放到主会话之外

Subagent、Skill、MCP 的区别

类型	解决什么问题	典型内容
Subagent	谁来做某个子任务	角色、模型、工具权限、执行边界
Skill	怎么做某类任务	工作流、规范、脚本、模板、参考资料
MCP	能调用什么外部能力	数据库、浏览器、GitHub、文档服务、内部 API

简单说：Subagent 是“分工”，Skill 是“方法”，MCP 是“工具”。一个代码审查 Subagent 可以加载 review Skill，也可以只允许读取 Git diff 的 MCP 或命令。

配置位置

不同工具对 Subagent 的支持方式不同：

工具	用户级 Subagent	项目级 Subagent	说明
Claude Code	~/.claude/agents/	.claude/agents/	官方支持自定义 Subagent，推荐用 /agents 创建和管理
Codex	内置代理	AGENTS.md、Skill、Plan/Review 工作流	目前更适合通过任务提示、Skill 和项目说明控制分工
Cursor	Subagents	.cursor/agents/	自定义 Subagent 能力以当前 Cursor 版本为准

Claude Code 的 Subagent 是 Markdown 文件。常见目录结构：

.claude/
└── agents/
    └── code-reviewer.md

用户级目录：

~/.claude/agents/

项目级目录：

.claude/agents/

项目级 Subagent 适合提交到 Git 仓库，团队一起使用；用户级 Subagent 适合个人常用角色。

Claude Code 格式

Claude Code 中可以运行：

/agents

进入 Subagent 管理界面。也可以手动创建 Markdown 文件：

---
name: code-reviewer
description: Reviews code changes for correctness, security, regressions, and missing tests.
tools: Read, Glob, Grep, Bash
model: sonnet
---

You are a senior code reviewer.

Review the current changes. Focus on bugs, regressions, security issues, edge cases, and missing tests.
Do not modify files. Return findings first, ordered by severity.

常用 frontmatter：

• name：Subagent 名称，建议用小写和连字符
• description：什么时候应该使用它
• tools：允许使用的工具
• disallowedTools：禁止使用的工具
• model：使用 sonnet、opus、haiku 或 inherit
• permissionMode：权限模式
• mcpServers：只给该 Subagent 使用的 MCP
• skills：预加载到该 Subagent 的 Skill
• isolation：可设置为 worktree，让 Subagent 在独立 worktree 中运行

建议

先用 /agents 生成初稿，再手动调整 description、工具权限和系统提示。description 写得越清楚，自动委派越稳定。

推荐 Subagent

选择 Subagent 时，优先看三点：

1. 子任务是否独立
2. 是否能明确输入和输出
3. 是否需要限制工具或模型

code-reviewer

适合审查代码、PR 或当前 Git diff。

建议权限：

• 允许：Read、Glob、Grep、Bash
• 禁止：写文件、编辑文件、推送代码

示例提示：

使用 code-reviewer subagent 审查当前 Git diff，只列出问题，不要修改文件。

适合检查：

• 行为回归
• 安全风险
• 边界条件
• 测试缺口
• 文档遗漏

researcher

适合查代码结构、定位实现、梳理调用链。

建议权限：

• 只读文件和搜索工具
• 不允许编辑

示例提示：

使用 researcher subagent 查清楚登录状态是如何在前端和后端之间传递的，最后只返回文件路径和调用链摘要。

适合场景：

• 大仓库摸底
• 查找某个接口或状态来源
• 比较多个模块的实现差异
• 为 plan mode 提供上下文

test-runner

适合运行测试、定位失败原因、总结验证结果。

建议权限：

• 允许运行测试命令
• 不允许直接修代码，除非任务明确要求

示例提示：

使用 test-runner subagent 运行相关测试，定位失败原因，并说明需要修哪些文件。

适合场景：

• 并行跑测试
• 收集失败日志
• 判断失败是否和当前改动相关
• 给主会话返回最小修复建议

debugger

适合分析报错、日志、异常栈和复现步骤。

示例提示：

使用 debugger subagent 分析这段错误日志，给出根因、相关文件和最小修复方向。

适合场景：

• 构建失败
• 接口 500
• 页面白屏
• CI 失败
• 类型错误

frontend-qa

适合检查页面截图、布局、响应式和交互问题。

建议搭配：

• browser-use Skill
• Playwright MCP
• frontend-design Skill s 示例提示：

使用 frontend-qa subagent 检查桌面和移动端页面截图，重点看文字重叠、溢出、按钮状态和视觉一致性。

适合场景：

• 前端页面上线前检查
• 多视口布局验证
• 表单、弹窗、导航交互检查
• UI 还原验收

docs-writer

适合整理文档、迁移说明、FAQ 和变更记录。

示例提示：

使用 docs-writer subagent 把这次改动整理成用户可读的更新说明，语言简洁，不要写实现细节。

适合场景：

• 更新项目文档
• 生成 PR 描述
• 整理配置教程
• 把技术实现翻译成用户说明

使用建议

适合拆给 Subagent：

• 输入明确、输出明确
• 可以并行执行
• 不依赖主会话持续判断
• 不需要反复和用户确认
• 能用文件范围或任务范围隔离

注意

多个 Subagent 同时改同一批文件，最容易产生冲突。能只读就只读；需要写文件时，先划清文件边界。

编写建议

一个好的 Subagent 定义应该回答四件事：

它负责什么
什么时候调用它
它能用哪些工具
它最后返回什么

推荐结构：

---
name: test-runner
description: Runs focused tests and summarizes failures without editing files.
tools: Read, Glob, Grep, Bash
model: sonnet
---

Run only tests relevant to the current task.
Do not modify files.
Return:
1. Commands run
2. Pass/fail result
3. Failure summary
4. Likely related files
5. Suggested next action

常见原则：

• description 写触发条件，不要只写能力介绍
• 默认少给工具，特别是写文件、删除文件、推送代码
• 输出格式要固定，方便主会话接收
• 对审查、调查、测试类 Subagent，优先设为只读
• 对长期复用的项目角色，放到 .claude/agents/

资源网站

• Claude Code Subagents
• Claude Code Agent Teams
• Cursor Background Agents
• Cursor Subagents changelog
• OpenAI Codex

建议

Subagent 不一定越多越好。先从 code-reviewer、researcher、test-runner 三类开始，稳定后再扩展到更细的角色。