关于 agent-patterns
面向 Claude Code 的技能，介绍 AI 辅助开发中的多 Agent 设计、委派与编排。内容涵盖协作模式、子 Agent 限制、配置方式和工具访问实践。
主要功能
- 01介绍八种编排模式
- 02说明子 Agent 配置
- 03记录工具访问实践
- 04比较子 Agent 与主对话任务
- 05列出委派常见问题
适用场景
- 01为并行开发选择协作模式
- 02配置项目级或用户级 Agent
- 03规划评审及多阶段工作流
安装
复制下面的命令，在终端中运行。
$
npx skills add https:/安装后在 Claude Code 中输入/agent-patterns确认已加载。
包含的文件
除 SKILL.md 外，安装时一起下载的参考资料和脚本。
references/agent-types.mddelegation-patterns.mdorchestration.mdsub-agent-configuration.mdtroubleshooting.md详细介绍
Agent 模式
Claude Code 和 AI 辅助开发中的多 Agent 设计、委派与编排。大规模软件开发默认使用可互换的 Agent；仅在同行评审或基于讨论的工作流中使用专用 Agent。
Claude Code 中的子 Agent 是专用 AI 助手，在隔离的上下文窗口中运行，具有自定义系统提示词、特定工具访问权限和独立权限。它们将探索、测试运行和冗长操作留在主线程之外，从而保留主对话上下文。
关键限制：子 Agent 无法再启动其他子 Agent。多步骤编排需要从主对话中串联子 Agent。
快速参考
| 模式 | 描述 | 适用场景 |
|---|---|---|
| 同质化群体 | 相同的 Agent 从共享看板中领取任务 | 大规模软件开发、弹性系统 |
| 顺序流水线 | 每个 Agent 都基于上一个 Agent 的输出进行构建 | 具有明确依赖关系的多步骤工作流 |
| 层级式 | 管理者拆解任务，工作者并行执行 | 包含独立子任务的复杂任务 |
| 同行协作 | Agent 反复迭代，直到达成共识 | 代码审查、对质量要求严格的输出 |
| 编排器委派 | 主对话依次调用子 Agent | 多阶段工作流、由专业人员并行处理的任务 |
| 两阶段审查 | 先检查规范合规性，再检查代码质量 | 高风险代码、复杂需求 |
| 先提问再委派 | Agent 在继续之前先提出澄清问题 | 模糊任务、返工成本高的工作 |
| 强制审查循环 | 修复与审查循环，达到最大迭代次数后升级处理 | 任何需要收敛的审查工作流 |
| 内置子 Agent | 模型 | 工具 | 用途 |
|---|---|---|---|
| Explore | Haiku | 只读 | 文件发现、代码搜索、代码库探索 |
| Plan | 继承 | 只读 | 规划模式下的代码库研究 |
| General-purpose | 继承 | 所有工具 | 复杂研究、多步骤操作 |
| Bash | 继承 | 终端 | 在独立上下文中运行终端命令 |
| Claude Code Guide | Haiku | 只读 | 解答有关 Claude Code 功能的问题 |
| 配置 | 值 |
|---|---|
| 自定义 Agent 位置 | .claude/agents/*.md（项目），~/.claude/agents/*.md（用户） |
| CLI Agent | --agents '{...}'（仅限当前会话，JSON 格式） |
| 插件 Agent | 插件的 agents/ 目录（优先级最低） |
| 必填字段 | name、description |
| 可选字段 | tools、disallowedTools、model、permissionMode、skills、hooks、color |
| 模型值 | sonnet、opus、haiku、inherit（默认值） |
| 权限模式 | default、acceptEdits、dontAsk、bypassPermissions、plan |
| 嵌套限制 | 子 Agent 不能再启动其他子 Agent（仅限一层） |
| 前台与后台 | 前台会阻塞主对话；后台会并发运行 |
| 批次大小 | 每个 Agent 处理 5-8 项（标准任务） |
| 并行 Agent | 同时运行 2-4 个 |
何时使用子 Agent，何时使用主对话
| 在以下情况下使用子 Agent | 在以下情况下使用主对话 |
|---|---|
| 任务会产生大量输出（测试套件、日志、API 响应） | 任务需要频繁来回沟通或迭代优化 |
| 需要强制执行特定的工具限制或权限 | 多个阶段共享大量上下文 |
| 工作独立完整，可以返回摘要 | 进行快速、针对性的更改 |
| 并行开展相互独立的研究 | 延迟很重要（子 Agent 会从头开始收集上下文） |
工具访问模式
| Agent 角色 | 推荐工具 | 原因 |
|---|---|---|
| 只读审查者 | Read, Grep, Glob | 无法修改代码；适合安全审计 |
| 文件创建者 | Read, Write, Edit, Glob, Grep | 不使用 Bash；避免因 heredoc 产生大量审批请求 |
| 脚本运行者 | Read, Write, Edit, Glob, Grep, Bash | 可全面访问构建/部署任务所需工具 |
| 研究 Agent | Read, Grep, Glob, WebFetch, WebSearch | 可访问外部数据以查找文档 |
子 Agent 默认继承所有工具（包括 MCP 工具）。使用 tools 作为允许列表，或使用 disallowedTools 作为拒绝列表来限制访问。后台子 Agent 无法使用 MCP 工具。
常见错误
| 错误 | 正确做法 |
|---|---|
| 期望子 Agent 创建嵌套子 Agent | 子 Agent 不能嵌套；应从主对话中依次调用子 Agent |
| 给只负责创建文件的 Agent 提供 Bash 工具 | 只使用 Write 和 Edit 工具；Bash 会因使用 heredoc 而导致大量审批请求 |
对敏感操作未设置 disallowedTools | 即使会继承工具，也要使用 disallowedTools 明确禁止危险工具 |
| 为小任务启动过多 Agent（5 个以上） | 从 2-3 个 Agent 开始；数量过多时，协调开销会超过收益 |
| 将关键指令放在 Agent 提示词的第 300 行之后 | 将关键规则放在 frontmatter 之后；模型会降低对靠后指令的优先级 |
| 使用专门的 Agent 进行大规模软件开发 | 使用可互换的 Agent 和共享任务看板；专门的 Agent 会造成单点故障 |
| 委派提示词中未包含“修复发现的问题” | 如果没有明确的行动指令，Agent 只会报告问题，不会进行更改 |
| 为内容生成任务将模型设为 Haiku | 默认使用 Sonnet；Haiku 仅用于执行脚本、快速查找或通过/失败检查 |
| 未为自定义 Agent 编写清晰的描述 | Claude 使用 description 字段决定何时自动委派；描述含糊会妨碍委派 |
| 在后台子 Agent 中使用 MCP 工具 | 后台子 Agent 无法使用 MCP 工具；应改为在前台运行 |
| 未向子 Agent 预加载技能 | 子 Agent 不会继承父级的技能；请在 skills 字段中明确列出 |
委派
- 设计 Agent 提示词前先探索代码库：Claude 会自动将文件发现和代码搜索任务委派给内置的 Explore 子 Agent（Haiku，只读）；支持快速、中等和非常全面三种模式
- 为复杂项目规划多 Agent 架构：使用计划模式；Claude 会先将研究工作委派给 Plan 子 Agent，然后再呈现计划
- 跨多个文件执行批量操作：在主对话中依次调用通用子 Agent，为它们提供相同的提示词和互不重叠的项目列表
- 隔离高输出量操作：将测试运行、日志处理或文档获取委派给子 Agent，避免主上下文中出现大量冗长输出
- 并行开展研究：同时启动多个子 Agent，分别进行独立调查；所有任务完成后，Claude 会综合各方发现
- 恢复中断的工作：让 Claude 继续之前的子 Agent；恢复后的 Agent 会保留完整的对话历史，包括工具调用和推理过程
对于项目级工作流排序、阶段门验证、目标分解和能力评分，请使用
orchestration技能。
参考资料
评论
支持 Markdown