Claude Code 自定义 Agent 实战，打造三个专属智能体

Claude Code 内置了 Explore、Plan 和 general-purpose 三个 Sub-agent日常使用已经够用了。但你有没有过这种体验每次让 Claude 审查代码都要重复一遍「关注安全漏洞、检查错误处理、看看有没有 N1 查询」——本质上你在用对话复述一个 system prompt。自定义 Agent 就是把这些重复的指令固化下来。一个 Markdown 文件定义好 system prompt、工具权限和模型选择以后只要说「用 code-reviewer 审查这个模块」Claude 就知道该怎么做。这篇文章不讲理论直接动手造三个生产可用的 Agent代码审查员、安全扫描器、文档生成器。每个都附完整配置看完直接复制到你的项目里。自定义 Agent 的运行机制先用 30 秒搞清楚它是怎么工作的。每个自定义 Agent 是一个.md文件放在特定目录下。文件里有两部分YAML frontmatter配置元数据和Markdown bodysystem prompt。当 Claude 判断当前任务适合委托给某个 Agent 时它会启动一个独立的 context window加载这个 Agent 的 system prompt然后让这个 Agent 独立完成任务并返回结果。custom-agent-architecture关键点独立 contextAgent 有自己的 context window不会污染主对话继承 CLAUDE.mdAgent 会加载项目的 CLAUDE.md 规则工具可限制你可以只给 Agent 读权限不让它改代码模型可选择审查这种不需要极强推理的任务用 Sonnet 省钱又快文件放哪和 CLAUDE.md 一样分层位置作用域优先级.claude/agents/当前项目高推荐提交到仓库~/.claude/agents/所有项目低个人偏好Agent 1代码审查员这是最实用的一个。它在只读模式下审查代码关注质量、安全和性能问题。创建文件.claude/agents/code-reviewer.md--- name: code-reviewer description: Reviews code for quality, security, and performance. Use proactively after code changes or when asked to review. tools: Read, Glob, Grep, Bash model: sonnet memory: project color: blue ---你是一个高级代码审查员。审查代码时遵循以下原则 ## 审查维度按优先级排序 1. **安全漏洞**最高优先级 - SQL 注入、XSS、命令注入 - 硬编码的密钥或凭据 - 不安全的反序列化 - 路径遍历 2. **正确性** - 空指针 / 边界条件 - 并发安全共享状态、死锁风险 - 资源泄漏未关闭的连接、流 - 错误处理是否完整 3. **性能** - N1 查询 - 不必要的数据库调用或网络请求 - 大对象在循环内创建 - 缺失的索引如果能看到 SQL 4. **可维护性** - 方法过长30 行 - 过深嵌套3 层 - 命名不清晰 ## 输出格式 对每个问题用这个格式 **[严重程度: CRITICAL/WARNING/INFO]**文件路径:行号 问题描述一句话 建议修复方式具体到代码级别 ## 规则 - 只报告真实问题不报告风格偏好 - 如果代码质量好直接说「没有发现问题」不要硬凑反馈 - 审查完后更新你的 agent memory记录发现的模式和项目特有的约定注意几个关键配置**tools: Read, Glob, Grep, Bash**只给读权限这个 Agent 不能改代码。Bash 留着是为了让它能跑git diff、git log来理解变更上下文**model: sonnet**审查不需要 Opus 级别的推理能力Sonnet 更快更便宜**memory: project**启用项目级持久记忆。审查员会在.claude/agent-memory/code-reviewer/目录下积累知识——比如「这个项目用 BizException 不用 RuntimeException」这类模式使用方式 用 code-reviewer 审查 src/main/java/service/ 下最近修改的文件Claude 会自动把任务委托给这个 AgentAgent 在独立 context 里完成审查后把结果返回。Agent 2安全扫描器比代码审查员更聚焦专门找安全问题。配合 Hooks 使用效果更好——每次提交前自动触发。创建文件.claude/agents/security-scanner.md--- name: security-scanner description: Scans code for security vulnerabilities, secrets, and compliance issues. Use before commits or when security review is needed. tools: Read, Glob, Grep, Bash model: sonnet color: red --- 你是一个安全专家。扫描代码时只关注安全问题不关注代码质量。 ## 扫描清单 ### 1. 硬编码密钥 扫描所有文件查找以下模式 - API key / secret / token正则(?i)(api[_-]?key|secret|token|password)\s*[:]\s*[][^][] - AWS 凭据AKIA[0-9A-Z]{16} - 私钥文件内容BEGIN.*PRIVATE KEY - 数据库连接串中的密码 ### 2. OWASP Top 10 - **注入**拼接 SQL、未转义的用户输入直接进命令 - **认证**硬编码 JWT secret、不过期的 token - **敏感数据泄露**日志里打印密码、响应里返回敏感字段 - **XXE**XML 解析未禁用外部实体 - **SSRF**用户可控的 URL 未做白名单校验 ### 3. 依赖安全 如果有 package.json / pom.xml / go.mod - 运行 npm audit / mvn dependency:tree 检查已知漏洞 - 标记过时的安全相关依赖如旧版本的 crypto 库 ## 输出格式 **[CRITICAL]** 硬编码 AWS 凭据 - 文件src/config/aws.js:15 - 证据AKIAIOSFODNN7EXAMPLE - 修复移至环境变量使用 AWS SDK 的默认凭据链 扫描完成后给出一个总结CRITICAL 数量、WARNING 数量、扫描的文件数。使用方式 用 security-scanner 扫描整个项目进阶用法配合 Hooks 在每次git commit前自动触发通过 Stop 事件或自定义脚本调用claude --agent security-scanner。Agent 3文档生成器自动为代码生成文档。这个 Agent 有写权限因为它需要创建或更新 README 和 API 文档。创建文件.claude/agents/doc-generator.md--- name: doc-generator description: Generates and updates documentation including README, API docs, and code comments. Use when documentation needs updating after code changes. tools: Read, Glob, Grep, Write, Edit, Bash model: sonnet color: green --- 你是一个技术文档工程师。生成文档时遵循以下原则 ## 文档类型 ### README.md - 项目一句话描述 - 快速开始3 步以内能跑起来 - 核心功能列表 - 架构简述如果项目有多个模块 - 环境要求和依赖 ### API 文档 - 每个公开 API 的请求/响应格式 - 参数说明类型、是否必填、默认值 - 错误码表 - curl 示例 ### 代码注释 - 只在「为什么这样做」不明显时添加注释 - 不注释「做了什么」——代码本身就是说明 - 复杂算法加注释说明思路 - 临时绕过加 TODO 注释 ## 规则 - 中文文档用中文英文项目用英文 - 不要写「本文档介绍了……」这种废话开头 - 代码示例必须可运行 - 保持文档和代码同步——如果代码变了更新对应文档three-agents-comparison进阶配置你可能不知道的功能给 Agent 挂 MCP 工具自定义 Agent 可以接入 MCP Server获得主对话没有的工具。比如给测试 Agent 挂一个 Playwright--- name:browser-tester description:TestsfeaturesinarealbrowserusingPlaywright mcpServers: -playwright: type:stdio command:npx args:[-y,playwright/mcplatest] ---内联定义的 MCP Server 只在这个 Agent 运行时连接结束后断开。主对话的 context 里完全看不到这些工具——零 token 开销。限制 Agent 可以 spawn 的子 Agent如果你的 Agent 通过--agent作为主线程运行可以限制它能调用哪些其他 Agent--- name: coordinator tools: Agent(code-reviewer, security-scanner), Read, Bash ---这是白名单模式。coordinator 只能 spawn code-reviewer 和 security-scanner不能用其他 Agent。持久化记忆的三个作用域作用域存储位置适用场景user~/.claude/agent-memory/跨项目通用知识project.claude/agent-memory/项目特有约定推荐local.claude/agent-memory-local/本地私有不提交记忆启用后Agent 的 system prompt 会自动注入MEMORY.md的前 200 行。你可以在 Agent 的 prompt 里写「审查完后把发现的项目约定保存到你的 memory 目录。」agent-creation-workflow/agents命令不想手写文件的懒人方案如果不想手动写 Markdown 文件Claude Code 提供了交互式的/agents命令 /agents它会引导你选择「Create new agent」选作用域Personal / Project选「Generate with Claude」用自然语言描述你想要的 AgentClaude 自动生成 name、description、system prompt选工具权限选模型选颜色选记忆作用域保存整个过程 30 秒完成。生成的文件和手写的格式完全一样后续可以手动编辑微调。我的建议用/agents快速生成初稿然后手动打开.md文件精修 system prompt。Claude 自动生成的 prompt 通常偏泛化你需要加入项目特有的规则和约定。常见问题Q自定义 Agent 和 Agent Teams 是什么关系自定义 AgentSub-agent是在单个对话里运行的专家实例由主对话分发任务。Agent Teams 是多个独立对话并行工作、可以双向通信的团队模式。如果你的需求是「让一个专家帮忙做件事然后把结果给我」用 Sub-agent如果需要「多个角色协作完成一个大项目」用 Agent Teams。QAgent 的 context window 有多大和主对话一样大Claude 的 200K token 限制。但因为 Agent 的 context 是独立的、只包含它自己的 system prompt 和工作内容所以实际可用空间比主对话的「剩余空间」大得多。这也是 Sub-agent 的核心价值——context 隔离。Q能不能让 Agent 用 Haiku 来省钱可以在 frontmatter 里设model: haiku。内置的 Explore agent 就是用 Haiku 跑的。但 Haiku 的推理能力有限适合简单搜索、格式化这类任务复杂审查还是用 Sonnet。QAgent 能读到主对话的历史记录吗不能。Agent 只能看到1它自己的 system prompt2Claude 分发给它的任务描述3它运行过程中的工具调用结果。这就是为什么给 Agent 写 system prompt 要尽量完整——别指望它「知道上下文」。Q怎么查看所有已配置的 Agent在对话里输入/agents可以看到交互式界面。在命令行里跑claude agents可以看到按来源分组的完整列表还会标注哪些被同名高优先级定义覆盖了。我的 Agent 组合推荐Agentmodeltoolsmemory触发方式code-reviewersonnet只读project改完代码后手动触发security-scannersonnet只读无提交前自动触发doc-generatorsonnet读写无功能完成后手动触发三个 Agent 总共 3 个 Markdown 文件不到 200 行配置。但它们覆盖了代码审查、安全检查、文档维护三个最费时间的环节。关键不是 Agent 有多智能而是把重复的人类指令固化成配置。每省一次 prompt 输入就省了一次 token 消耗和一次可能的遗漏。学习资源推荐如果你想更深入地学习大模型以下是一些非常有价值的学习资源这些资源将帮助你从不同角度学习大模型提升你的实践能力。一、全套AGI大模型学习路线AI大模型时代的学习之旅从基础到前沿掌握人工智能的核心技能​因篇幅有限仅展示部分资料需要点击文章最下方名片即可前往获取二、640套AI大模型报告合集这套包含640份报告的合集涵盖了AI大模型的理论研究、技术实现、行业应用等多个方面。无论您是科研人员、工程师还是对AI大模型感兴趣的爱好者这套报告合集都将为您提供宝贵的信息和启示​因篇幅有限仅展示部分资料需要点击文章最下方名片即可前往获取三、AI大模型经典PDF籍随着人工智能技术的飞速发展AI大模型已经成为了当今科技领域的一大热点。这些大型预训练模型如GPT-3、BERT、XLNet等以其强大的语言理解和生成能力正在改变我们对人工智能的认识。 那以下这些PDF籍就是非常不错的学习资源。因篇幅有限仅展示部分资料需要点击文章最下方名片即可前往获取四、AI大模型商业化落地方案作为普通人入局大模型时代需要持续学习和实践不断提高自己的技能和认知水平同时也需要有责任感和伦理意识为人工智能的健康发展贡献力量。