Claude Code Agent（智能体） 设计与开发指南

从“配一个自定义命令“到“设计一套多 Agent 体系“——读完本文，你应该能独立设计、实现并迭代 Cluade Code 中的自定义 Agent 和 Subagent。

Claude Code 的 Agent 体系虽然没有 oh-my-openagent 那样的三层编排架构，但它的 Subagent 系统加上 Hooks、MCP 和 Plugins，同样能实现灵活的多 Agent 协作。本文面向需要设计 Agent 的开发者——不只告诉你有什么配置项，还给出一套从入门到生产的完整方法。

快速上手：创建你的第一个自定义 Agent

在 Claude Code 中创建一个自定义 Agent 只需要两步：

第 1 步：创建 Subagent 文件

在项目 .claude/agents/ 目录下创建一个 Markdown 文件：

---
name: my-helper
description: 我的通用助手，处理常规开发任务
model: sonnet
effort: medium
maxTurns: 30
tools: Read Write Edit Bash Grep Glob
---

# System Prompt

你是一个通用的开发助手。请遵循以下原则：

1. 先理解问题再动手，必要时列出方案让用户选择
2. 修改前先读取相关文件，理解上下文
3. 所有输出用中文

第 2 步：在会话中调用

/fork my-helper "重构这个模块的 API 接口"

Claude Code 会创建一个后台子 Agent 独立执行，完成后将摘要返回主会话。

/fork 命令（v2.1.161+ 引入）生成一个隔离的子 Agent 会话，继承当前会话的上下文，在后台独立运行。你可以把一件事交给一个 Agent，它干完回来告诉你结果，你继续做自己的事。

快速动手：给你的 Subagent 配个 Skill（技能）

Agent + Skill 的组合是 Claude Code 最实用的模式。Skill 就是 SKILL.md 文件——一个包含完整指令集的文档。把 Skill 挂在 Agent 上，Agent 就获得了该领域的专业知识。

---
name: react-expert
description: React/Next.js 前端专家，专注于组件设计和性能优化
model: sonnet
skills:
  - react-performance
  - testing
tools: Read Write Edit Glob Bash
maxTurns: 25
color: blue
---

# System Prompt

你是 React 前端专家。

对应的 Skill 文件可以是：

---
name: react-performance
description: React 性能优化最佳实践
---

当你分析 React 组件性能时，遵循以下步骤：

1. **识别问题**：检查不必要的重渲染、大组件拆分、状态提升层次
2. **分析工具**：用 React DevTools Profiler 或浏览器 Performance 面板定位瓶颈
3. **优化手段**（按优先级）：
   - `React.memo` 包裹纯展示组件
   - `useMemo` / `useCallback` 缓存计算和回调
   - 状态下推，减少 Context 提供者范围
4. **验证**：优化前后对比渲染次数

然后用户在会话中执行：

/fork react-expert "检查 pages/dashboard 下的组件性能问题"

Subagent 会加载 react-performance Skill 的完整指令，以此为指导分析代码。

架构概览——Claude Code 的 Agent 体系

Claude Code 没有设计一个全局编排层（没有 Sisyphus 这样的主 Agent），它的 Agent 体系建立在四个核心概念上：

内置 Subagent 类型

自定义 Agent 的工作方式

主会话（编排器）
  │
  ├── /fork ──► 后台 Subagent（独立上下文窗口）
  │                     │
  │                完成后返回摘要
  │
  ├── /background ──► 转为后台 Agent（全功能）
  │
  └── Task 调用 ──► Subagent A
      Task 调用 ──► Subagent B

Agent 设计模式

掌握了“怎么配“之后，下一个问题是“怎么设计“。以下五种模式覆盖了 90% 的 Claude Code Agent 使用场景。

1. Simple Agent（单 Agent）

适用场景：一个 Agent 完成一件事。这是最常用的模式。

---
name: db-reviewer
description: 数据库 Schema 和查询审查专家
model: sonnet
effort: high
tools: Read Grep Glob
disallowedTools: Write Edit Bash
maxTurns: 15
color: purple
---

# System Prompt

你是一个数据库专家。审查以下方面：

1. Schema 设计是否符合第三范式
2. 索引策略是否合理（关注联合索引顺序）
3. SQL 查询是否存在 N+1 问题
4. 是否有潜在的死锁或锁竞争风险

特点：单一职责、只读权限、专注一件事。大多数自定义 Subagent 都是这种模式。

2. Fork 模式（后台并行）

适用场景：多个独立任务可以同时进行。

# 用户在主会话中
/fork code-reviewer "审查 src/auth/ 下的变更"
/fork db-reviewer "审查 migrations/ 下的新迁移文件"  
/fork security-scanner "检查依赖是否有已知漏洞"

# 三个 Subagent 各自独立运行，完成后汇总结果

Fork 模式的关键优势是不阻塞主会话。你可以在等待子 Agent 结果的同时继续在主会话中工作。

3. Pipeline（流水线模式）

适用场景：A 的输出是 B 的输入。适合分阶段处理。

第一阶段：Code Reviewer → 输出问题列表
第二阶段：Fixer → 根据问题列表逐个修复
第三阶段：Tester → 验证修复是否引入新问题

Claude Code 不提供内置的 Pipeline 编排器——你需要通过 Hooks 或手动调度来实现：

---
name: pipeline-runner
description: 多阶段流水线协调者
model: sonnet
maxTurns: 50
tools: Read Write Edit Grep Glob Bash
---

# System Prompt

你是一个流水线协调者。你需要按顺序执行以下阶段：

1. **规划阶段**：分析需求，生成实现计划
2. **实现阶段**：按计划逐步实现
3. **自检阶段**：检查实现是否满足需求
4. **修正阶段**：对发现的问题进行修复

每个阶段完成后，输出阶段小结，再进入下一步。

用单个 Agent 做 Chain 模式时，关键是把步骤写入 prompt 让 Agent 自己编排。

4. Hook 触发的自动化 Agent

适用场景：在特定事件（如写入文件、执行命令）后自动触发 Subagent。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "agent",
            "agent": "code-reviewer",
            "prompt": "审查刚刚修改的文件：{{output}}"
          }
        ]
      }
    ]
  }
}

这样每次文件修改后，会自动触发 code-reviewer Subagent 审查变更。审查结果（而非被阻断）会出现在输出中。

Hook 类型的 agent 使用 Subagent（最多 50 轮）执行任务，适合需要代码库状态验证的场景。

5. Batch 分解模式

适用场景：一个大型变更需要分解为多个独立单元并行处理。

/batch

Claude Code 会将你的需求分解为多个独立子任务，每个子任务交给一个 Subagent 并行执行。所有 Subagent 完成后汇总合并。

/batch 是 Claude Code 对“大规模并行变更“的内置解决方案。它会自动分析变更范围、分解为无冲突的子任务、并行执行并合并结果。

自定义 Subagent 配置参考

Frontmatter 完整字段

关键字段详解

model 选择策略

tools 权限设计

---
name: readonly-expert
description: 只读分析专家，不修改任何文件
tools: Read Grep Glob WebFetch
disallowedTools: Write Edit Bash
---

权限设计原则：最小权限。只给 Agent 完成工作所必需的工具。只读 Agent 永远不应该有 Write/Edit 权限。

isolation 工作区隔离

---
name: experimental-coder
description: 实验性代码修改，不污染主工作区
model: sonnet
isolation: worktree
tools: Read Write Edit Bash Grep Glob
---

isolation: worktree 会在独立的 Git worktree 中执行，修改不会影响主分支。适合风险较高的变更。

运行 Agent

在交互会话中

通过 CLI 启动

# 指定 Agent 启动
claude --agent react-expert "实现这个组件"

# 直接后台运行
claude --bg "分析测试失败原因并给出修复建议"

# 非交互模式 + 指定 Agent
claude -p "审查 src/auth/" --agent security-reviewer

管理后台任务

# 查看所有后台 Agent
claude agents

# 连接到后台会话
claude attach <id>

# 停止后台会话
claude stop <id>

# 查看后台会话日志
claude logs <id>

Agent 设计工具箱——Subagent 之外的能力

除了 Subagent，Claude Code 还有几个与 Agent 密切相关的能力，组合使用效果更佳。

Background Agent

/background 将当前会话转为后台运行。与 /fork 的区别：

/batch——并行任务分解

/batch 是 Claude Code 对大范围变更的“分解-并行-合并“方案。适用场景：

• 同时重构多个独立模块
• 为多个功能编写测试
• 批量更新代码风格

Claude Code 自动分析变更范围，拆分为无冲突的子任务，分配给多个 Subagent 并行执行。

Task 工具

在 Claude Code 的 Hooks 和 Plugins 中可以通过 Task 工具调用 Subagent：

// Pseudocode——Hook 中的 Subagent 调用
{
  "type": "agent",
  "agent": "security-reviewer",
  "prompt": "审查最近修改的敏感文件"
}

Task 工具是 Claude Code 中 Agent 间通信的基础——主 Agent 通过它委派工作给子 Agent，子 Agent 完成后返回结构化摘要。

案例：构建一个代码审查流水线

我们从头构建一个可投入生产的代码审查 Subagent，并在迭代中完善它。

V1：基础版本

---
name: code-reviewer
description: 代码审查专家，检查实现变更的质量
model: sonnet
effort: high
tools: Read Grep Glob Bash
disallowedTools: Write Edit
maxTurns: 20
color: yellow
---

# System Prompt

你是严格的代码审查者。审查以下维度：

## 检查清单

1. **逻辑正确性**：条件判断是否完整？边界情况是否处理？
2. **安全风险**：是否存在注入、越权、敏感信息泄露？
3. **性能隐患**：是否存在不必要的循环、内存泄漏？
4. **代码质量**：命名是否清晰？函数是否过长？错误处理是否得当？

## 输出格式

对每个问题输出：
- `[CRITICAL]` — 必须修复的问题
- `[WARNING]` — 建议修复的问题
- `[INFO]` — 观察和建议

使用方式：

/fork code-reviewer "审查最近的 Git 变更"

V2：增加格式化和上下文

---
name: code-reviewer
description: 代码审查专家，检查实现变更的质量
model: sonnet
effort: high
tools: Read Grep Glob Bash
disallowedTools: Write Edit
maxTurns: 20
memory: project
color: yellow
---

# System Prompt

你是严格的代码审查者。审查以下维度：
...

memory: project 让 Subagent 可以访问项目的持久记忆——包括历史审查记录和项目约定。

V3：接入 Hook 实现自动审查

将 Subagent 与 Hook 绑定，每次代码变更后自动触发审查：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "agent",
            "agent": "code-reviewer",
            "prompt": "审查刚刚修改的文件，重点关注安全和正确性问题"
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "echo \"$CLAUDE_TOOL_INPUT\" | grep -qE 'rm -rf /|DROP DATABASE' && exit 2 || exit 0"
          }
        ]
      }
    ]
  }
}

这个配置实现了：

• 写/改文件后 → 自动触发 code-reviewer 审查
• 执行危险命令前 → 自动拦截

测试与迭代

Agent 开发不是一次性工作——你需要一个反馈循环来持续改进。

测试清单

测试你的 Subagent 时，确认以下问题：

版本管理

Subagent 是代码，应该版本控制：

# 推荐目录结构
.claude/
  agents/
    code-reviewer-v1.md
    code-reviewer-v2.md
  skills/
    react-performance.md

版本演进记录建议：

V1：基础审查功能，输出问题列表
V2：增加 memory:project 记忆历史审查结果
V3：接入 Hook，自动触发后审查

常见问题排查

最佳实践

1. 命名清晰、职责单一

每个 Subagent 只做一件事。好的命名标准：看到名字就知道它干什么。

✅ security-scanner：安全扫描
✅ db-migration-reviewer：数据库迁移审查
✅ api-doc-generator：API 文档生成

❌ helper：太模糊
❌ super-agent：职责不清晰

2. Prompt（提示词） 要具体、可操作

不写笼统的指令，写 Agent 能逐条执行的具体规则。

❌ "审查代码质量"
✅ "检查：是否存在 SQL 注入风险？错误处理是否覆盖了网络超时？日志是否包含敏感信息？"

3. 最小权限原则

只给 Agent 完成工作所必需的工具。审查类 Agent 不要给 Write/Edit/Bash 权限，以防意外修改。

4. 用 Skill 做知识库，用 Agent 做执行器

Skill 是可复用的知识包，Agent 是执行者。一个 Skill 可以被多个 Agent 共享。

5. 把常用命令存为 Subagent

不要每次都手写长 prompt。常见的任务——代码审查、安全扫描、数据库迁移检查——都应该做成 Subagent 文件，一个 /fork 搞定。

6. 生产级 Agent 的配置要完整

---
name: production-ready
description: 生产级 Agent 配置模板
model: sonnet
effort: high
maxTurns: 30
tools: Read Write Edit Bash Grep Glob
disallowedTools: rm rf
permissionMode: acceptEdits
memory: project
isolation: worktree
skills:
  - team-conventions
  - security-checklist
mcpServers:
  - sentry
color: green
---

# System Prompt
...

7. 做好隔离

变更类任务（重构、迁移）一定要用 isolation: worktree。只读任务（审查、分析）不需要隔离。

常见反模式

设计 Claude Code Agent 时，以下反模式会限制 Agent 系统的可维护性和扩展性：

CLAUDE.md 膨胀：把所有规则、约束、备忘都塞进一个 CLAUDE.md 文件，导致文件超过 500 行。Agent 需要在每一次工具调用前扫描整个文件，token 消耗和决策延迟线性增长。正确的做法是利用 Claude Code 的多层 CLAUDE.md 体系（项目级、目录级、文件级），按作用域分层放置规则：全局规则放根目录，模块规则放对应子目录。

过度依赖 Hook：用 Shell Hook 处理应该在 Agent 内部完成的事情。Hook 是外部事件触发器，它的调用开销（进程启动、上下文切换）远高于 Agent 内部逻辑。例如在 PostToolUse Hook 中运行一个完整的 TypeScript 编译检查，不如让 Agent 在代码修改后自行执行编译验证。

Subagent 通信链过长：设计 A→B→C→D 的链式 Subagent 调用，中间任何一个 Agent 的输出偏差都会被下游放大。Claude Code 缺乏 OMO 那样的主 Agent 汇聚机制，链式调用的结果一致性难以保证。应优先选择星型或扇出（fan-out）模式，主 Agent 直接分发独立任务给多个 Subagent 并单独收集结果。

适用场景与限制

适用场景：Claude Code 最适合个人开发者和小团队的日常编码。简洁的内置能力让“打开即用“成为可能；CLAUDE.md 的分层配置对单体应用和中小型项目匹配度极高；六层扩展体系（CLAUDE.md → Skills → MCP → Subagent → Hook → Plugin）让渐进式深入成为可能——项目从简单开始，随需求增长逐步叠加扩展层。

不适用场景：当团队需要跨项目、跨团队的标准化 Agent 配置时，Claude Code 的文件级 CLAUDE.md 缺乏集中管理机制。每个开发者本地维护自己的 AGENTS.md，配置漂移不可避免。此时 OpenCode + OMO 的集中配置和 Skill 分发体系更适合团队标准化。

限制说明：Claude Code 仅支持 Anthropic Claude 系列模型，无法利用 GPT-4o、Gemini 或本地模型的能力差异。这意味着对于某些任务（如结构化输出或数学推理），无法切换到可能更合适的模型。六层扩展体系虽然灵活，但各层之间的交互优先级和冲突解决规则需要人工排查，缺乏统一的调试工具。

常见错误与陷阱

MCP 服务器选择错误：为内置工具已经能胜任的任务引入 MCP 服务器。例如使用 MCP 文件系统服务器来做文件的增删改查，而 Claude Code 的 File Tools（Read/Write/Edit）已经优化了文件操作并内置了差异分析和冲突检测。MCP 应留给外部 API 调用和数据库访问。

Skill 命名冲突：安装多个社区 Skill 时忽略命名空间，导致两个 Skill 定义了相同名称的命令或规则。Claude Code 的 Skill 加载顺序决定了冲突胜出方，但结果往往不是预期的。应检查 Skill 的 name 字段，在安装时通过别名机制避免冲突。

忽略 CLAUDE.md 的目录层级：将所有配置写在一个 CLAUDE.md 中，不知道 Claude Code 支持目录级 CLAUDE.md。实际上，src/api/CLAUDE.md 中的规则只对 src/api/ 下的文件生效，这比在根 CLAUDE.md 中写条件规则更精确、更高效。

Agent 记忆失效：依赖 Agent 的长期记忆功能时没有检查记忆存储的状态。Claude Code 的记忆基于向量检索，如果知识库内容发生变化未及时重建索引，Agent 会检索到过期或冲突的信息。

关联章节

• ← Claude Code 扩展机制 — Subagent、Hooks、Plugins 完整参考
• ← Claude Code 命令参考 — /fork、/background、/agents 命令详解
• ← Claude Code 生态参考 — 社区 Subagent、Skills 推荐
• → oh-my-openagent Agent（智能体） 设计与开发指南 — OMO 三层编排体系对比参考
• → 自定义工作流 — Team Mode 多 Agent 协作
• → Agent 派生模式 — Agent 动态生成模式