前两篇我们学会了用 SDK 调用 Agent、给 Agent 加自定义工具。但不管哪种方式都是在代码里配置——每次跑 Agent 都要在脚本里写一段提示词传一堆参数改起来麻烦也不方便复用。现实工作里大家会希望有更多「随手可用」的专属 Agent一个专门做代码审查的、一个专门写测试的、一个专门生成文档的……配置好了放在那里需要的时候一行命令就能召唤出来和同事共享换个电脑也能用。Claude Code 提供了一套标准的 Agent 角色定义机制——把 Agent 的身份、职责、工具权限、模型选择都写成一个 markdown 文件放在.claude/agents/目录下就能让整个团队复用。这套机制背后就是我们在第六篇源码里读到的loadAgentsDir.ts今天把它彻底用起来。一、Agent 定义文件的结构一个 Agent 定义文件是一个普通的.md文件结构分两部分YAML 前置信息Frontmatter和文件正文System Prompt。--- description: 专职代码审查员针对 Pull Request 提供详细的代码质量反馈 tools: Read, Bash, Grep model: claude-sonnet-4-6 permissionMode: default maxTurns: 30 --- 你是一位经验丰富的代码审查员专注于代码质量、安全性和可维护性。 你的工作流程 1. 先理解代码的上下文读入口文件、README、相关配置 2. 分析具体改动逐文件审查 3. 按优先级给出建议Critical → Major → Minor [系统提示词继续...]Frontmatter 字段一览字段类型含义description必填字符串Agent 的一句话描述也是 Claude 决定何时使用这个 Agent 的依据tools字符串数组或逗号分隔允许使用的工具列表*表示全部disallowedTools字符串数组明确禁用的工具优先级高于toolsmodel字符串使用的模型inherit表示继承父 Agent 的模型permissionMode枚举default/bypassPermissions/acceptEditsmaxTurns整数最大执行轮次超出后停止effort枚举推理强度low/medium/highmcpServers数组这个 Agent 专用的 MCP Serverbackground布尔是否作为后台任务运行memory枚举持久化记忆范围user/project/local文件正文前置信息之后的所有内容就是这个 Agent 的系统提示词System Prompt。在loadAgentsDir.ts里前置信息解析之后正文直接作为systemPrompt注入进子代理的queryLoop。二、放置位置的优先级Agent 定义文件可以放在三个地方优先级从高到低~/.claude/agents/— 用户级别只有自己能用项目目录/.claude/agents/— 项目级别团队共享建议提交到版本控制Claude Code 内置 Agent—Explore、Plan、general-purpose等不可覆盖同名 Agent项目级别会覆盖用户级别用户级别会覆盖内置但内置的agentType命名方式与自定义不同基本不会冲突。三、实践一专职代码审查 Agent创建文件.claude/agents/code-reviewer.md--- description: 专职代码审查员。对一个或多个文件进行代码审查从可维护性、安全性、性能三个维度给出反馈。 tools: Read, Grep, Bash model: claude-sonnet-4-6 permissionMode: default maxTurns: 20 --- 你是一位资深软件工程师专注于代码审查工作。你的目标是帮助团队提升代码质量而不是为了批评而批评。 ## 审查维度 每次审查从以下三个维度出发按重要性排序 **1. 安全性Critical** - SQL 注入、XSS、命令注入等 OWASP Top 10 问题 - 敏感信息泄露密钥、密码硬编码 - 权限控制缺失 **2. 可维护性Major** - 函数/类职责是否单一 - 是否有明显的代码重复 - 命名是否表达意图 - 异常处理是否完整 **3. 性能Minor** - 明显的 O(n²) 复杂度 - 不必要的同步阻塞 - 重复的计算/查询 ## 输出格式 ## 代码审查报告 ### 文件文件路径 **[Critical] 问题标题** 位置第 X-Y 行 问题具体描述 建议修复方案 [其他问题...] ### 总体评价 2-3 句综合评价 ### 改进优先级 1. 必须修复... 2. 建议修复... 3. 可以考虑... ## 工作原则 - 只指出真实存在的问题不泛泛批评「写得不好」 - 给出具体可行的改进建议而不是「这应该更好」 - 如果代码逻辑不清楚先通过 Read 和 Grep 理解上下文再做判断 - 中文输出然后从命令行使用这个 Agent# 让代码审查员审查特定文件claude--agentcode-reviewer审查 src/auth/middleware.ts重点关注安全性# 也可以在 Claude Code 交互模式里召唤它# 在对话框里输入code-reviewer 帮我审查这次 PR 里的改动也可以通过 SDK 使用import{query}fromanthropic-ai/claude-codeconstresponsequery({prompt:审查 src/auth/middleware.ts重点关注安全性,options:{cwd:process.cwd(),// 指定使用 code-reviewer AgentagentType:code-reviewer,},})forawait(constmessageofresponse){if(message.typeassistant){constblocksmessage.message?.content??[]for(constblockofblocks){if(block.typetext)process.stdout.write(block.text)}}if(message.typeresult)break}四、实践二测试工程师 Agent创建文件.claude/agents/test-engineer.md--- description: 测试工程师 Agent。为指定的函数或模块编写完整的单元测试覆盖正常路径、边界情况和错误情况。 tools: Read, Grep, Bash, Write, Edit model: claude-sonnet-4-6 permissionMode: acceptEdits maxTurns: 40 --- 你是一位专注于测试驱动开发的工程师。你的职责是为代码编写高质量的测试确保测试真正能捕获潜在的 Bug。 ## 工作流程 **第一步理解被测代码** 1. 读取目标文件理解函数签名、功能、依赖 2. 查看现有测试如有避免重复 3. 查看相关类型定义 **第二步设计测试用例** 对每个函数至少覆盖 - 正常输入 期望输出Happy Path - 边界值空字符串、0、null、空数组 - 异常情况应该抛出错误的场景 - 若有异步操作测试 Promise 的 resolve 和 reject **第三步编写测试** - 遵循项目已有的测试框架先用 Bash 检测用的是 Jest/Vitest/其他 - 每个测试用例描述要清晰一看就知道在测什么 - 不 Mock 不必要的东西——Mock 越少测试越可靠 ## 输出规范 - 测试文件放在与被测文件同目录命名为 filename.test.ts - 每个 describe 块对应一个函数 - 每个 it 的描述格式应该 期望行为 当 条件 - 写完后运行测试确认全部通过 ## 禁止事项 - 不编写「看起来像测试但实际不测任何东西」的占位测试 - 不为了提高覆盖率而写无意义的测试 - 不修改被测代码来迁就测试使用方式# 为指定文件写测试claude--agenttest-engineer为 src/utils/parser.ts 里的所有导出函数编写单元测试# 结合 CI 自动触发在 git commit hook 里# 检测到新增文件但没有对应测试时自动召唤测试工程师五、用多个 Agent 组成流水线有了多个专职 Agent更有意思的玩法是让它们串联工作——第一个 Agent 完成一项工作结果传给下一个 Agent 继续处理。下面是一个完整的代码改进流水线先让「测试工程师」写测试再让「代码审查员」审查原始代码最后汇总报告// pipeline.tsimport{query}fromanthropic-ai/claude-codeasyncfunctionrunAgentAndCollect(options:{prompt:stringagentType:stringcwd:string}):Promisestring{constresponsequery({prompt:options.prompt,options:{cwd:options.cwd,agentType:options.agentType,permissionMode:acceptEdits,},})letoutputforawait(constmessageofresponse){if(message.typeassistant){constblocksmessage.message?.content??[]for(constblockofblocks){if(block.typetext)outputblock.text}}if(message.typeresult)break}returnoutput}asyncfunctioncodeImprovementPipeline(targetFile:string){constcwdprocess.cwd()console.log( 步骤 1/2代码审查...\n)constreviewReportawaitrunAgentAndCollect({prompt:审查${targetFile}按照 Critical/Major/Minor 三级输出问题列表,agentType:code-reviewer,cwd,})console.log(reviewReport)console.log(\n 步骤 2/2补充测试...\n)consttestReportawaitrunAgentAndCollect({prompt:为${targetFile}编写单元测试重点覆盖以下已知问题点\n${reviewReport},agentType:test-engineer,cwd,})console.log(testReport)// 汇总报告constsummaryawaitrunAgentAndCollect({prompt:基于以下代码审查和测试报告生成一份 PR 描述 ## 代码审查结果${reviewReport}## 测试补充情况${testReport}PR 描述要包含本次改进的核心目标、解决的主要问题、测试覆盖情况。300 字以内。,agentType:general-purpose,cwd,})console.log(\n PR 描述草稿\n)console.log(summary)}awaitcodeImprovementPipeline(process.argv[2]??src/index.ts)运行之后三个步骤顺序执行每一步的输出作为下一步的输入最终输出一份完整的改进报告和 PR 描述草稿。这就是——一个人提交代码三个「专家」背后帮大家自动过一遍。六、Agent 配置进阶Memory 和 MCPFrontmatter 里还有两个字段值得单独拿出来讲memory字段——让 Agent 有「记忆」---description:技术文档写作助手记住项目的写作风格规范memory:project---配置了memory: project之后这个 Agent 每次被召唤会自动加载CLAUDE.md里和项目记忆相关的部分。它会「记住」上次告诉它的写作风格、特殊约定不需要每次都重新解释。memory有三个选项user用户级别的持久记忆跨项目project项目级别只在当前仓库有效local本地临时记忆不提交到版本控制mcpServers字段——给 Agent 装备专属 MCP 工具---description:数据分析助手能查询生产数据库和内部知识库mcpServers:-readonly-postgres# 引用已配置的 MCP Server 名字-knowledge-base# 另一个---这样「数据分析 Agent」启动时就会自动挂载readonly-postgres和knowledge-base两个 MCP Server而其他 Agent 不会有这两个工具——权限和能力精确地绑定在对应的角色上。七、Agent 定义的设计哲学回头看src/tools/AgentTool/built-in/exploreAgent.ts里的 Explore Agent大家会发现 Anthropic 内部在设计 Agent 时遵循几个原则值得借鉴单一职责Explore Agent 只做搜索Plan Agent 只做规划绝不越界。每个 Agent 的description第一句话就是它的核心职责边界。最小权限disallowedTools明确列出了不该有的工具。Explore Agent 的disallowedTools里有Edit、Write——它是只读探索的永远不应该改文件这个约束写在定义里不依赖 Claude 自觉遵守。说清楚何时不用它whenToUse字段不只是说「什么时候用我」也要暗示「什么情况下换别人」。这帮助 Claude 在多 Agent 可用时做出合理选择。提示词写给执行者而不是读者Agent 的系统提示词是给另一个 Claude 看的不是给人看的。要直接、具体、可操作避免模糊表述。「先读取文件再理解上下文再给出建议」比「理解代码后提供帮助」好得多。学到这里大家已经掌握了完整的自制 Agent 工具箱调用方式第七篇claude -p命令行调用、SDKquery()流式调用自定义工具第八篇tool()createSdkMcpServer()扩展 Agent 能力专属角色本篇.claude/agents/配置文件定义可复用 Agent把这三篇连起来从「会调用 Claude」到「能配出一套专业 AI 工作流」中间并没有太大的门槛——只是需要花时间把工具和提示词打磨好。工具设计得好提示词写得清楚Agent 的表现就会远超通用模式。很多人用 Claude Code 只是把它当「聊天助手」用了一半的力气。用好自定义工具和专属 Agent才算真的把这套架构的潜力释放出来。