Claude Code 自定义代理创作

—＃＃ 介绍In Claude Code Subagent Patterns we covered five workflows for spending your context window wisely — and the fifth, pipeline orchestration with custom agents, is the one teams ask about most. “将您的审核清单编码为子代理"听起来很棒，直到您打开一个空的”.claude/agents/migration-reviewer.md"和一个闪烁的光标。本指南是缺失的手册。 We’ll walk through the anatomy of a custom agent definition, what each frontmatter field actually controls, how to write a system prompt that produces a structured report instead of a chatty ramble, why tool allowlists matter more than they look, and two complete, production-ready examples you can copy today. 然后是错误——因为这里的故障模式很微妙，当代理第一次错过一些明显的东西时，它们就会让你失去对代理的信任。If you’ve never delegated to a subagent before, read the patterns piece first. 如果您有，并且您准备好发布自己的产品，那么这就是剧本。## 自定义代理剖析自定义代理是带有 YAML frontmatter 的单个 Markdown 文件。 它位于两个地方之一：- .claude/agents/<name>.md — 项目范围、版本控制、与整个团队共享

• ~/.claude/agents/<name>.md — 用户范围，可在计算机上的每个项目中使用结构非常简单：``降价

姓名： 迁移审核员 description: 检查数据库迁移的安全性。 当 PR 涉及 db/migrate/、架构文件或任何 SQL DDL 时使用。 工具：Read、Grep、Glob 型号: 十四行诗 #

您是数据库迁移审核者。 你的工作就是发现不安全的地方 在达到生产之前进行迁移… ````结尾"—“上方的所有内容都是配置。 它下面的所有内容都是系统提示符 - 子代理运行时的角色和指令集。 这就是整个合同。 没有构建步骤，没有注册，没有插件清单。 将文件放入，运行”/agents"以确认 Claude Code 已拾取该文件，并且它是可调用的。## Frontmatter 领域四个字段完成所有工作。 其中三个是可选的，但对于一个严肃的代理来说，默认值很少是您想要的。### 名称（必填）代理的身份 - 这是父级作为"subagent_type"传递的字符串。 保持短横线大小写和描述性：“security-auditor”，而不是"agent2"。 文件名是装饰性的； name 字段是规范的。### 描述（必填——以及体重不足的人）这是路由信号。 当父代理决定是否委托时，它会读取描述，而不是系统提示。 因此，描述必须编码何时才能到达该代理，并具有具体的触发器：> ❌ description: 代码审查者。

✅description: 检查代码更改的正确性和安全性。 在编写重要的差异之后、提交之前主动使用，特别是对于身份验证、支付或并发敏感代码。"主动"这个词是有负担的——它会促使父母在没有明确询问的情况下调用。 如果你的经纪人似乎从来没有被解雇过，那么描述几乎总是原因。### tools（可选 - 但无论如何都要声明它）以逗号分隔的允许列表。 省略它，代理将继承父级拥有的所有工具。 我们将用整整一节的时间来解释为什么这通常是错误的。###模型`（可选）固定一个层级：“俳句"用于廉价的机械通行证，“十四行诗"用于平衡的审查工作，“作品"用于深度推理。 “haiku” 上的大容量 linter 式代理可保持成本合理； 安全审计员如果失误代价高昂，就会获得"opus”。## 编写系统提示符身体是大多数特工获胜或失败的地方。 三个规则可以产生可靠的员工：1. 在第一句话中说明角色和边界。“您是迁移审核者。您不编写代码或应用修复 - 您报告发现。” 告诉代理"不"做什么与工作本身一样重要。**2. 指定输出契约。 ** 含糊的提示产生散文； 你想要结构。 把它拼出来：``降价 以列表形式报告您的发现。 对于每个问题：

• 严重性：阻止者 | 警告| 尼特
• 位置：文件：行
• 问题：一句话
• 修复：具体更改 以一行结论结束：可以安全合并或需要更改。 ````3. 给它一个清单，而不是一种氛围。“安全审查"是一个愿望。 恩```降价 以列表形式报告您的发现。 对于每个问题：
• 严重性：阻止者 | 警告| 尼特
• 位置：文件：行
• 问题：一句话
• 修复：具体更改 以一行结论结束：可以安全合并或需要更改。 “呃"继承了"Write”、“Edit"和"Bash”。第一次发现问题时，它可能会"帮助"修复它——改变你的工作树、运行命令，并破坏使审查值得请求的独立性。修复方法是最小权限。 将工具与工作相匹配：| Agent kind | Tools | | — | — | | Reviewer / auditor | Read, Grep, Glob | | Researcher / explorer | Read, Grep, Glob, WebSearch, WebFetch | | Test runner | Read, Grep, Glob, Bash | | Fixer (rare, deliberate) | Read, Edit, Bash |从字面上看，只读审阅者"不能"变得流氓。 这种可预测性使您可以信任其报告，而无需重新检查其涉及的所有内容。 （如果您稍后通过 MCP 服务器 连接外部系统，则适用相同的规则 — 仅授予代理true正需要的 MCP 工具。）## 工作示例：迁移审核员``降价

姓名： 迁移审核员 description: 审核数据库迁移以确保生产安全。 当更改涉及 db/migrate/、schema.rb 或任何 SQL DDL 文件时主动使用。 工具：Read、Grep、Glob 型号: 十四行诗 —您是数据库迁移审核者。 您不编辑文件或运行 迁移——您阅读建议的迁移并报告风险。根据此列表检查每个迁移：

1. 在大表上添加具有 NOT NULL 约束且无默认值的列（锁）。
2. 在没有 CONCURRENTLY 的情况下添加索引 (bl``` markdow n

姓名： 迁移审核员 description: 审核数据库迁移以确保生产安全。 当更改涉及 db/migrate/、schema.rb 或任何 SQL DDL 文件时主动使用。 工具：Read、Grep、Glob 型号: 十四行诗 #

您是数据库迁移审核者。 您不编辑文件或运行 迁移——您阅读建议的迁移并报告风险。

根据此列表检查每个迁移：

1. 在大表上添加具有 NOT NULL 约束且无默认值的列（锁）。
2. 在没有 CONCURRENTLY 的情况下添加索引（阻止写入）。
3. 重命名或删除仍由应用程序代码引用的列。
4. 数据回填在架构更改时在同一事务内运行。
5. 缺少相应的回滚/下行路径。

将调查结果报告为：

• 严重性：阻止者 | 警告| 尼特
• 位置：文件：行
• 问题/修复 以结论结束：可以安全合并或需要更改。 ``瓦片。 您只报告——您从不修改代码。对于差异，请检查：
• Authn/authz：是否可以在没有预期检查的情况下到达此路径？
• 注入：用户输入是否连接到 SQL、shell 或 HTML 中？
• 秘密：添加到代码或日志中的任何密钥、令牌或密码？
• IDOR：对象引用的范围是否仅限于经过身份验证的用户？对于每个发现，给出一个漏洞利用草图（攻击者如何触发它）， 然后修复。 不确定时默认标记 - 误报 便宜，错过认证漏洞则不然。

``降价
 ---
 名称：安全门
description: 涉及身份验证、授权、秘密或用户输入的威胁模型差异。 在合并任何身份验证或付款更改之前主动使用。 
工具：Read、Grep、Glob
 型号: 作品
 ---

 您是一名具有威胁建模思维的安全审查员。 false设
 输入是敌对的。 您只报告——您从不修改代码。 

对于差异，请检查：
 - Authn/authz：是否可以在没有预期检查的情况下到达此路径？ 
- 注入：用户输入是否连接到 SQL、shell 或 HTML 中？ 
- 秘密：添加到代码或日志中的任何密钥、令牌或密码？ 
- IDOR：对象引用的范围是否仅限于经过身份验证的用户？ 

对于每个发现，给出一个漏洞利用草图（攻击者如何触发它），
 然后修复。 不确定时默认标记 - 误报
 便宜，错过认证漏洞则不然。 
```i
s
t
委托模式](/resources/llm-frameworks/claude-code-subagent-patterns-multi-agent-workflows-2026/) 为您工作。 
- **一劳永逸。** 代理就是代码。 当你的堆栈发生变化时，未维护的清单就会腐烂。 每季度审查一次。## 原理定制代理是**可执行的机构知识**。 审查标准过去存在于没有人打开的 wiki 页面中，或者存在于总是发现错误的一位高级工程师的头脑中——你编码一次，对其进行版本控制，每个团队成员以及每次 CI 运行都会得到相同的、不知疲倦的审查者。 代理不会在截止日期前匆忙而跳过第 3、5 和 7 步。这种一致性，而不是原始情报，才是胜利。## 设置生产就绪的 Claude 代码要大规模运行自定义代理管道，您需要稳定的基础设施：1. **长期运行和 CI 会话的可靠主机。** 自定义代理在 CI 中大放异彩，他们控制每个 PR。 您需要一个不会丢失工作的盒子。 **HTStack
** — 香港 VPS，从中国大陆访问低延迟且 BGP 路由稳定。 它与托管 dibi8.com 的 IDC 相同，因此我们在其上运行我们自己的代理管道。 超值套餐每月 5-12 美元。2. **并行门的云空间。** 当编排器同时扇出到迁移审核器 + 安全门 + 性能检查器时，您需要备用 CPU。 **DigitalOcean
** — 跨越 14 个以上区域的 60 天 200 美元免费赠金，非常适合在您的应用旁边托管 CI 运行器。3. **技能包。** 曲线最陡的部分是编写不会失败的代理定义。 我们在 Gumroad 上将五种经过实战考验的技能打包为 19 美元的捆绑包（请参阅角落里浮动的 CTA），其中包括协调器提示和另外三个准备发布的代理定义。## 相关阅读- [Claude Code Subagent 模式](/resources/llm-frameworks/claude-code-subagent-patterns-multi-agent-workflows-2026/) — 五个工作流程； 本指南深入探讨了模式 5。 
- [Superpowers 框架](/resources/llm-frameworks/superpowers/) — 一个可供学习的精选技能/代理库。 
- [MCP 服务器 2026 排名](/resources/llm-frameworks/mcp-servers-2026-rankings-selection-guide/) — 将代理功能扩展到捆绑工具之外。 
- [AI 编码代理景观](/resources/llm-frameworks/ai-coding-agent-landscape-2026-skills-mcp-opensource/) — 自定义代理位于更广泛的生态系统中。## 判决自定义代理将团队的最佳实践从无人阅读的文档转变为针对每次更改运行的检查。 秘诀是：一个尖锐的**描述**，以便它触发，一个**最低权限工具白名单**，以便它保持在其车道上，以及一个**带有明确清单和输出合同的系统提示**，以便它生成一份您可以采取行动的报告。从一个开始 - 上面的迁移审核员是大多数团队中影响力最高的第一代理。 植入一个错误，确认它捕获它，然后提交文件。 从那一刻起，每个队友都有了一个永不疲倦、永不跳过的审稿人。<!--自动引用-->
 ## 参考文献和来源- [克劳德代码](https://github.com/anthropics/claude-code)
 - [Claude Agent SDK](https://docs.anthropic.com/en/api/agent-sdk/overview)