你已经知道 Claude Code 内置了三种子代理Explore、Plan、General-purpose分别覆盖搜索、分析、执行三个环节。用了一段时间后你会发现这三种通用型选手处理大部分任务没问题但一旦遇到具体的、带领域知识的场景它们就显得不够用了。 比如代码审查时你希望 Claude 自动关注 SQL 注入、N1 查询、命名规范这些团队约定的检查点而不是每次手动交代一遍。写测试时你希望它知道项目用的是 pytest 而不是 unittest文件要放在__tests__/目录下。生成 API 文档时你希望它遵循团队的 OpenAPI 模板格式。这些带领域知识的子代理Claude Code 不会替你内置但它给了你自己造的能力。一、自定义子代理是什么自定义子代理就是一个 Markdown 文件。例如我们在这里自定义了一个code-reviewer Agent。--- name: code-reviewer description: 专注代码质量审查的子代理检查安全漏洞、性能问题和代码规范 model: sonnet tools: - Read - Glob - Grep - Bash --- 你是一个严格的代码审查员。审查代码时重点关注 1. **安全漏洞**SQL 注入、XSS、命令注入、硬编码密钥 2. **性能问题**N1 查询、不必要的循环、内存泄漏风险 3. **代码规范**命名一致性、错误处理完整性、资源释放 4. **可维护性**函数长度、圈复杂度、重复代码 输出格式按严重程度分三级 - **严重**必须修复有安全风险或会导致线上故障 - **警告**建议修复影响性能或可维护性 - **建议**可以改进属于最佳实践 每个问题附上文件路径、行号和修复建议。 审查结束后给出整体评分1-10和一句话总结。 没有复杂的 SDK没有要编译的插件就是一个.md文件放在约定的目录下Claude Code 启动时自动识别。文件内容分两部分顶部的 YAML frontmatter 定义元信息名字、模型、工具、权限正文就是系统提示词你希望这个子代理怎么干活的指令。 上图展示了一个自定义子代理文件的完整结构。上半部分是 YAML frontmatter用三个横线---包裹定义了子代理的身份证叫什么名字、用什么模型、能用哪些工具。下半部分是系统提示词就是你平时在对话里反复跟 Claude 说的那些话现在固化成文件一劳永逸。二、放在哪里2.1 常见放置位置 自定义子代理文件有两个放置位置对应两种作用范围项目级.claude/agents/只在当前项目生效。最大的好处是可以提交到 Git团队成员 clone 下来就能用不需要额外配置。全局级~/.claude/agents/所有项目都能用。适合放你个人的通用工具比如一个万能的 code-reviewer 或 doc-writer。优先级上项目级覆盖全局级如果两个目录下有同名文件项目级的生效。2.2 临时加载 除了这两个固定目录还有两种临时加载的方式。通过CLI falg 临时加载指定目录下的子代理claude--agents/path/to/my-agents/通过插件分发插件的agents/目录会被自动扫描适合团队统一分发标准化的子代理集合。三、Frontmatter 字段详解 Frontmatter 是子代理的配置中心每个字段控制一个维度我们逐个看。3.1 name 和 description身份与触发条件name:code-reviewerdescription:专注代码质量审查检查安全漏洞、性能问题和代码规范name是调用时的标识符你在对话里code-reviewer就靠这个名字匹配。description更关键Claude 会读这段描述来决定是否自动调用这个子代理。比如你说帮我检查一下这段代码的质量Claude 看到 description 里有代码质量审查就可能自动选中它。所以 description 写得越精确自动匹配越靠谱。3.2 model选哪个大脑model:sonnet# 快且便宜适合审查、搜索类任务model:opus# 最强推理适合复杂分析、架构设计model:haiku# 最快最便宜适合简单的格式化、分类任务model:inherit# 继承主对话的模型默认行为 不是每个子代理都需要最强模型。代码审查用 sonnet 就够了跑得快还省钱。只有需要深度推理的场景比如设计复杂的重构方案才需要 opus。3.3 tools工具白名单tools:-Read-Glob-Grep-Bash 这是一个allowlist只有列出的工具才能被子代理使用。这个字段非常重要它是你控制子代理能力边界的手段。一个 code-reviewer 不需要Edit权限它只审查不改代码一个 test-writer 则需要Edit来写测试文件。最小权限原则在这里同样适用。3.4 permission权限模式permission:default# 默认该问用户就问permission:acceptEdits# 自动接受文件编辑其他操作仍需确认permission:dontAsk# 不问用户直接执行所有操作permission:bypassPermissions# 绕过所有权限检查慎用permission:plan# 只做规划不执行任何操作 这五档权限从严格到宽松排列。对于审查类子代理default就行对于需要大批量自动写测试的场景acceptEdits能免去你反复点确认的麻烦。bypassPermissions只建议在完全可控的 CI 环境中使用。3.5 isolation 和 background高级选项isolation:worktree# 在独立的 Git worktree 中工作background:true# 默认以后台任务方式运行isolation: worktree让子代理在一个独立的 Git 工作区中操作不会影响你当前的代码。适合让它去独立尝试一个方案不满意就扔掉的场景。background: true让子代理默认在后台运行不阻塞你的主对话。你可以继续跟主 Claude 聊其他事情后台任务完成后会通知你结果。四、实战示例一code-reviewer 来看一个完整的代码审查子代理。创建文件.claude/agents/code-reviewer.md---name:code-reviewerdescription:专注代码质量审查的子代理检查安全漏洞、性能问题和代码规范model:sonnettools:-Read-Glob-Grep-Bash---你是一个严格的代码审查员。审查代码时重点关注 1.**安全漏洞**SQL注入、XSS、命令注入、硬编码密钥 2.**性能问题**N1查询、不必要的循环、内存泄漏风险 3.**代码规范**命名一致性、错误处理完整性、注释质量4.**可维护性**函数长度、圈复杂度、重复代码输出格式按严重程度分三级-**严重**必须修复有安全风险或会导致线上故障-**警告**建议修复影响性能或可维护性-**建议**可以改进属于最佳实践每个问题附上文件路径、行号和修复建议。 审查结束后给出整体评分1-10和一句话总结。model 选 sonnet代码审查不需要最强推理能力sonnet 足够且速度更快。审查一个模块可能就 30 秒搞定用 opus 反而浪费。tools 没给 Edit审查员只看不改这是刻意的限制。如果你想让它审查完自动修复那就加上 Edit但这是另一个子代理的职责了。输出格式写在提示词里三级分类不是装饰是让输出结构化、可扫描。团队成员看到红色就知道必须处理蓝色可以以后再说。4.1 Step 1准备一个练习项目# 创建项目并初始化 gitmkdir-pplayground/srccdplaygroundgitinit4.2 Step 2写一段有问题的代码作为审查目标 创建src/user_service.py故意埋几个典型问题importsqlite3importos DB_PASSWORDadmin123# 硬编码密码defget_user(user_id):connsqlite3.connect(users.db)querySELECT * FROM users WHERE id user_id# SQL 注入resultconn.execute(query).fetchone()returnresultdefget_all_users():connsqlite3.connect(users.db)users[]foruserinconn.execute(SELECT * FROM users).fetchall():# N1 查询循环内执行 SQLforroleinconn.execute(SELECT * FROM roles WHERE user_id str(user[0])).fetchall():users.append({user:user,role:role})returnusersdefdelete_user(user_id):connsqlite3.connect(users.db)conn.execute(DELETE FROM users WHERE id user_id)os.system(echo User user_id deleted)# 命令注入 这段代码包含SQL 注入、命令注入、硬编码密码、N1 查询、连接未关闭。正好覆盖 code-reviewer 提示词里的各个检查项。4.3 Step 3创建子代理文件mkdir-p.claude/agents 将上面的code-reviewer.md内容保存到.claude/agents/code-reviewer.md。4.4 Step 4启动并调用(1) 全局模式 整个会话都是reviewer身份claude--agentcode-reviewer 之后进入直接说检查src/user_service.py。(2) 正常启动后提及预期结果你应该会看到结构化的审查报告包含 三级问题列表每个问题带文件路径和行号。五、实战示例二test-writer 写测试的子代理和审查的关键区别在于需要写文件的权限---name:test-writerdescription:根据源码自动生成单元测试覆盖正常路径和边界条件model:sonnettools:-Read-Glob-Grep-Edit-Bashpermission:acceptEdits---你是一个测试工程师。给定源码文件按以下步骤工作 1. 先检查项目的测试框架看 package.json 或 pyproject.toml 2. 分析目标函数的输入输出类型和边界条件 3. 生成单元测试覆盖正常路径、边界值、异常输入、空值处理 4. 测试文件放在与源文件同级的 __tests__ 目录下 5. 写完后自动运行测试确保全部通过 如果测试失败分析原因并修复最多重试 3 次。注意两个不同tools 多了 Edit因为它需要创建和修改测试文件。permission 设为 acceptEdits自动接受文件编辑操作省去你每次点确认。写测试是相对安全的操作它不会改你的源码所以放宽权限是合理的。4.1Step 1创建 test-writer 子代理 将上面的 test-writer 内容保存到.claude/agents/test-writer.md。现在你的 agents 目录下有两个子代理了.claude/agents/ ├── code-reviewer.md ← 只读审查 └── test-writer.md ← 可写自动补测试4.2 Step 2让 test-writer 给代码补测试 观察它的行为它会先读源码分析函数签名然后创建测试文件并运行。因为permission: acceptEdits它创建文件时不会逐个问你确认。4.3Step 3串联两个子代理 这是自定义子代理最有意思的用法让不同角色协作。首先让reviewer进行审查根据审查报告手动修复代码修复完后让test-writer补测试 先审查、再修复、再补测试。两个子代理各司其职一个只读一个可写权限边界清晰。六、三种调用方式 子代理定义好了怎么用三种方式各有适用场景6.1 自然语言最直觉 用 code-reviewer 检查 auth 模块 你正常说话Claude 根据语意和子代理的 description 匹配。大多数时候能正确触发但偶尔 Claude 会把它当成普通问题来回答而不是调用子代理。6.2 提及保证触发 code-reviewer 检查最近的 PR 改动前缀是硬触发Claude 一定会调用对应的子代理不存在理解偏差的问题。当你需要确定性时用这种方式。6.3 全局模式整个会话都是这个代理claude--agentcode-reviewer 启动时指定--agent整个会话都以 code-reviewer 的身份运行。适合你就想开一个专门的审查会话从头到尾检查多个文件不需要反复 。 三种方式的选择逻辑很简单日常随手用就自然语言需要确定性就 提及专项工作就全局模式。七、总结 自定义子代理的核心思路就一句话把你反复对 Claude 说的话固化成一个可复用的 Markdown 文件。 就像你不会每次 code review 都重新写一份 checklist而是把 checklist 贴在团队 wiki 上一样自定义子代理做的是同样的事情只不过读 checklist 的不是人是 AI。
【Agents】Claude Code 自定义子代理：内置的不够用，就自己造
你已经知道 Claude Code 内置了三种子代理Explore、Plan、General-purpose分别覆盖搜索、分析、执行三个环节。用了一段时间后你会发现这三种通用型选手处理大部分任务没问题但一旦遇到具体的、带领域知识的场景它们就显得不够用了。 比如代码审查时你希望 Claude 自动关注 SQL 注入、N1 查询、命名规范这些团队约定的检查点而不是每次手动交代一遍。写测试时你希望它知道项目用的是 pytest 而不是 unittest文件要放在__tests__/目录下。生成 API 文档时你希望它遵循团队的 OpenAPI 模板格式。这些带领域知识的子代理Claude Code 不会替你内置但它给了你自己造的能力。一、自定义子代理是什么自定义子代理就是一个 Markdown 文件。例如我们在这里自定义了一个code-reviewer Agent。--- name: code-reviewer description: 专注代码质量审查的子代理检查安全漏洞、性能问题和代码规范 model: sonnet tools: - Read - Glob - Grep - Bash --- 你是一个严格的代码审查员。审查代码时重点关注 1. **安全漏洞**SQL 注入、XSS、命令注入、硬编码密钥 2. **性能问题**N1 查询、不必要的循环、内存泄漏风险 3. **代码规范**命名一致性、错误处理完整性、资源释放 4. **可维护性**函数长度、圈复杂度、重复代码 输出格式按严重程度分三级 - **严重**必须修复有安全风险或会导致线上故障 - **警告**建议修复影响性能或可维护性 - **建议**可以改进属于最佳实践 每个问题附上文件路径、行号和修复建议。 审查结束后给出整体评分1-10和一句话总结。 没有复杂的 SDK没有要编译的插件就是一个.md文件放在约定的目录下Claude Code 启动时自动识别。文件内容分两部分顶部的 YAML frontmatter 定义元信息名字、模型、工具、权限正文就是系统提示词你希望这个子代理怎么干活的指令。 上图展示了一个自定义子代理文件的完整结构。上半部分是 YAML frontmatter用三个横线---包裹定义了子代理的身份证叫什么名字、用什么模型、能用哪些工具。下半部分是系统提示词就是你平时在对话里反复跟 Claude 说的那些话现在固化成文件一劳永逸。二、放在哪里2.1 常见放置位置 自定义子代理文件有两个放置位置对应两种作用范围项目级.claude/agents/只在当前项目生效。最大的好处是可以提交到 Git团队成员 clone 下来就能用不需要额外配置。全局级~/.claude/agents/所有项目都能用。适合放你个人的通用工具比如一个万能的 code-reviewer 或 doc-writer。优先级上项目级覆盖全局级如果两个目录下有同名文件项目级的生效。2.2 临时加载 除了这两个固定目录还有两种临时加载的方式。通过CLI falg 临时加载指定目录下的子代理claude--agents/path/to/my-agents/通过插件分发插件的agents/目录会被自动扫描适合团队统一分发标准化的子代理集合。三、Frontmatter 字段详解 Frontmatter 是子代理的配置中心每个字段控制一个维度我们逐个看。3.1 name 和 description身份与触发条件name:code-reviewerdescription:专注代码质量审查检查安全漏洞、性能问题和代码规范name是调用时的标识符你在对话里code-reviewer就靠这个名字匹配。description更关键Claude 会读这段描述来决定是否自动调用这个子代理。比如你说帮我检查一下这段代码的质量Claude 看到 description 里有代码质量审查就可能自动选中它。所以 description 写得越精确自动匹配越靠谱。3.2 model选哪个大脑model:sonnet# 快且便宜适合审查、搜索类任务model:opus# 最强推理适合复杂分析、架构设计model:haiku# 最快最便宜适合简单的格式化、分类任务model:inherit# 继承主对话的模型默认行为 不是每个子代理都需要最强模型。代码审查用 sonnet 就够了跑得快还省钱。只有需要深度推理的场景比如设计复杂的重构方案才需要 opus。3.3 tools工具白名单tools:-Read-Glob-Grep-Bash 这是一个allowlist只有列出的工具才能被子代理使用。这个字段非常重要它是你控制子代理能力边界的手段。一个 code-reviewer 不需要Edit权限它只审查不改代码一个 test-writer 则需要Edit来写测试文件。最小权限原则在这里同样适用。3.4 permission权限模式permission:default# 默认该问用户就问permission:acceptEdits# 自动接受文件编辑其他操作仍需确认permission:dontAsk# 不问用户直接执行所有操作permission:bypassPermissions# 绕过所有权限检查慎用permission:plan# 只做规划不执行任何操作 这五档权限从严格到宽松排列。对于审查类子代理default就行对于需要大批量自动写测试的场景acceptEdits能免去你反复点确认的麻烦。bypassPermissions只建议在完全可控的 CI 环境中使用。3.5 isolation 和 background高级选项isolation:worktree# 在独立的 Git worktree 中工作background:true# 默认以后台任务方式运行isolation: worktree让子代理在一个独立的 Git 工作区中操作不会影响你当前的代码。适合让它去独立尝试一个方案不满意就扔掉的场景。background: true让子代理默认在后台运行不阻塞你的主对话。你可以继续跟主 Claude 聊其他事情后台任务完成后会通知你结果。四、实战示例一code-reviewer 来看一个完整的代码审查子代理。创建文件.claude/agents/code-reviewer.md---name:code-reviewerdescription:专注代码质量审查的子代理检查安全漏洞、性能问题和代码规范model:sonnettools:-Read-Glob-Grep-Bash---你是一个严格的代码审查员。审查代码时重点关注 1.**安全漏洞**SQL注入、XSS、命令注入、硬编码密钥 2.**性能问题**N1查询、不必要的循环、内存泄漏风险 3.**代码规范**命名一致性、错误处理完整性、注释质量4.**可维护性**函数长度、圈复杂度、重复代码输出格式按严重程度分三级-**严重**必须修复有安全风险或会导致线上故障-**警告**建议修复影响性能或可维护性-**建议**可以改进属于最佳实践每个问题附上文件路径、行号和修复建议。 审查结束后给出整体评分1-10和一句话总结。model 选 sonnet代码审查不需要最强推理能力sonnet 足够且速度更快。审查一个模块可能就 30 秒搞定用 opus 反而浪费。tools 没给 Edit审查员只看不改这是刻意的限制。如果你想让它审查完自动修复那就加上 Edit但这是另一个子代理的职责了。输出格式写在提示词里三级分类不是装饰是让输出结构化、可扫描。团队成员看到红色就知道必须处理蓝色可以以后再说。4.1 Step 1准备一个练习项目# 创建项目并初始化 gitmkdir-pplayground/srccdplaygroundgitinit4.2 Step 2写一段有问题的代码作为审查目标 创建src/user_service.py故意埋几个典型问题importsqlite3importos DB_PASSWORDadmin123# 硬编码密码defget_user(user_id):connsqlite3.connect(users.db)querySELECT * FROM users WHERE id user_id# SQL 注入resultconn.execute(query).fetchone()returnresultdefget_all_users():connsqlite3.connect(users.db)users[]foruserinconn.execute(SELECT * FROM users).fetchall():# N1 查询循环内执行 SQLforroleinconn.execute(SELECT * FROM roles WHERE user_id str(user[0])).fetchall():users.append({user:user,role:role})returnusersdefdelete_user(user_id):connsqlite3.connect(users.db)conn.execute(DELETE FROM users WHERE id user_id)os.system(echo User user_id deleted)# 命令注入 这段代码包含SQL 注入、命令注入、硬编码密码、N1 查询、连接未关闭。正好覆盖 code-reviewer 提示词里的各个检查项。4.3 Step 3创建子代理文件mkdir-p.claude/agents 将上面的code-reviewer.md内容保存到.claude/agents/code-reviewer.md。4.4 Step 4启动并调用(1) 全局模式 整个会话都是reviewer身份claude--agentcode-reviewer 之后进入直接说检查src/user_service.py。(2) 正常启动后提及预期结果你应该会看到结构化的审查报告包含 三级问题列表每个问题带文件路径和行号。五、实战示例二test-writer 写测试的子代理和审查的关键区别在于需要写文件的权限---name:test-writerdescription:根据源码自动生成单元测试覆盖正常路径和边界条件model:sonnettools:-Read-Glob-Grep-Edit-Bashpermission:acceptEdits---你是一个测试工程师。给定源码文件按以下步骤工作 1. 先检查项目的测试框架看 package.json 或 pyproject.toml 2. 分析目标函数的输入输出类型和边界条件 3. 生成单元测试覆盖正常路径、边界值、异常输入、空值处理 4. 测试文件放在与源文件同级的 __tests__ 目录下 5. 写完后自动运行测试确保全部通过 如果测试失败分析原因并修复最多重试 3 次。注意两个不同tools 多了 Edit因为它需要创建和修改测试文件。permission 设为 acceptEdits自动接受文件编辑操作省去你每次点确认。写测试是相对安全的操作它不会改你的源码所以放宽权限是合理的。4.1Step 1创建 test-writer 子代理 将上面的 test-writer 内容保存到.claude/agents/test-writer.md。现在你的 agents 目录下有两个子代理了.claude/agents/ ├── code-reviewer.md ← 只读审查 └── test-writer.md ← 可写自动补测试4.2 Step 2让 test-writer 给代码补测试 观察它的行为它会先读源码分析函数签名然后创建测试文件并运行。因为permission: acceptEdits它创建文件时不会逐个问你确认。4.3Step 3串联两个子代理 这是自定义子代理最有意思的用法让不同角色协作。首先让reviewer进行审查根据审查报告手动修复代码修复完后让test-writer补测试 先审查、再修复、再补测试。两个子代理各司其职一个只读一个可写权限边界清晰。六、三种调用方式 子代理定义好了怎么用三种方式各有适用场景6.1 自然语言最直觉 用 code-reviewer 检查 auth 模块 你正常说话Claude 根据语意和子代理的 description 匹配。大多数时候能正确触发但偶尔 Claude 会把它当成普通问题来回答而不是调用子代理。6.2 提及保证触发 code-reviewer 检查最近的 PR 改动前缀是硬触发Claude 一定会调用对应的子代理不存在理解偏差的问题。当你需要确定性时用这种方式。6.3 全局模式整个会话都是这个代理claude--agentcode-reviewer 启动时指定--agent整个会话都以 code-reviewer 的身份运行。适合你就想开一个专门的审查会话从头到尾检查多个文件不需要反复 。 三种方式的选择逻辑很简单日常随手用就自然语言需要确定性就 提及专项工作就全局模式。七、总结 自定义子代理的核心思路就一句话把你反复对 Claude 说的话固化成一个可复用的 Markdown 文件。 就像你不会每次 code review 都重新写一份 checklist而是把 checklist 贴在团队 wiki 上一样自定义子代理做的是同样的事情只不过读 checklist 的不是人是 AI。
