子代理：分工执行专项任务

子代理（subagent）是 Claude Code 在独立上下文窗口中运行、且可限定工具集的专项执行角色。主会话把适合隔离的任务委托给子代理，既能避免大量检索内容把主对话上下文撑满，也能形成"作者写、专家审"的分工结构。本节说明位置、格式、内置子代理与设计原则。

一、为什么需要子代理

• 上下文隔离：探索、搜索等任务读取的大量文件留在子代理自己的窗口，只把结论返回主会话，主会话更清爽、不易衰减。
• 职责与工具受限：审查类角色可配置为只读，从机制上避免误改文件。
• 角色化复用：把"安全审查""代码探索""测试编写"沉淀为可反复调用的固定角色。

你可以在提示中显式要求，例如"用子代理对本次改动做一次安全审查"；主代理也会在合适时机自动委托给内置子代理。

二、存放位置与优先级

位置	作用域	说明
托管策略（managed settings）	组织级，最高优先	由团队/运维统一下发
--agents 启动参数 / JSON 文件	当前会话	启动时以 JSON 定义临时子代理
.claude/agents/	当前项目	建议提交版本控制，团队共享；从工作目录向仓库根逐层扫描
~/.claude/agents/	个人全部项目	跨项目复用的个人角色
插件 agents/ 目录	插件启用范围，最低优先	随插件分发

目录支持递归子文件夹组织；子代理身份只由 frontmatter 的 name 决定，与文件名不必一致；同名定义以离工作目录更近者优先。会话中可用 /agents 查看与管理已配置的子代理。

三、文件格式与 frontmatter

文件以 --- YAML 开头，其后 Markdown 为该代理的系统提示。name 与 description 为必填：前者是唯一标识，后者说明何时委托。常用可选字段：

字段	作用
tools	允许使用的工具列表；省略则继承子代理可用全集，列出后只保留所选项
disallowedTools	在继承/指定集合中再剔除的工具（如禁用写操作）
model	指定模型或 inherit 跟随主会话
permissionMode	该代理的权限模式，如只读类可收紧为不执行写操作
maxTurns	子代理最大执行轮次，达到后返回部分结果并可续接
skills / mcpServers	预置 Skill 与限定可用的 MCP 服务器

---
name: read-only-reviewer
description: 只读审查代码改动，指出缺陷、边界条件与风格问题，不修改文件
tools: Read, Grep, Glob, WebFetch
---
你是一名严格的只读代码审查员。只阅读与检索，不写入文件、不执行修改命令。
输出：按"问题位置—风险说明—建议改法"列出发现，区分阻断级与建议级。

四、内置子代理

内置角色	工具特征	典型用途
Explore	只读，不具备写入能力	代码库搜索、定位与探索；可按 quick / medium / very thorough 调整彻底度
Plan	只读，服务于计划模式调研	动手前收集背景、形成方案，过程留在独立窗口
general-purpose	具备完整子代理工具集	需要探索与改动结合的复杂多步任务

另有少量面向辅助功能的内置代理自动服务于特定场景；不需要时可在权限规则中以 Agent(代理名) 形式禁用指定代理。

五、设计原则与常见加载失败原因

• 单一职责：一个代理做好一类任务，写清输入、动作边界与交付格式。
• 最小授权：只读角色不给 Edit/Write；能不执行命令就不收 Bash。
• 作者—审查分离：让审查子代理在新鲜上下文复核 diff，避免"自己审自己"的盲点。

子代理文件被跳过的常见原因：缺少 name；--- 不在文件首行；有 name 却缺 description；YAML 无法解析；name 以 - 开头、含冒号或过长。可用 /doctor 检查配置，或对代理目录做校验工具排查命名与解析问题。