# Claude Code 自定义 Agent 配置完整指南

本文档提供了在 Claude Code 中配置和使用自定义 sub agent 的完整说明。

## 目录

1. [基础知识](#基础知识)
2. [YAML Frontmatter 格式](#yaml-frontmatter-格式)
3. [工具权限配置](#工具权限配置)
4. [Agent 识别和加载](#agent-识别和加载)
5. [常见问题排查](#常见问题排查)
6. [最佳实践](#最佳实践)

---

## 基础知识

### 什么是 Claude Code Sub Agent？

Sub agent 是专门化的 AI 助手，用于处理特定类型的任务。每个 sub agent：
- 拥有独立的上下文窗口
- 可配置特定的工具访问权限
- 使用自定义的系统提示（system prompt）

### Agent 文件位置

Sub agent 配置文件可以存放在两个位置：

1. **项目级别**（优先）：`.claude/agents/`
   - 仅对当前项目有效
   - 项目成员共享

2. **用户级别**：`~/.claude/agents/`
   - 对所有项目有效
   - 用户私有配置

**重要**：同名 agent 时，项目级别优先于用户级别。

---

## YAML Frontmatter 格式

### 完整格式

每个 agent 文件必须以 YAML frontmatter 开头：

```yaml
---
name: agent-name
description: When this agent should be invoked
tools: Tool1, Tool2, Tool3
model: inherit
---

# Agent Title

Your agent's system prompt goes here...
```

### 字段说明

| 字段 | 必需 | 说明 | 示例 |
|------|------|------|------|
| `name` | ✅ 是 | Agent 唯一标识符，小写字母+连字符，最大64字符 | `researcher`, `backend-dev` |
| `description` | ✅ 是 | 描述 agent 用途和调用时机，最大1024字符 | `Technical research specialist for finding docs` |
| `tools` | ❌ 否 | 逗号分隔的工具列表，省略则继承所有工具 | `Read, Write, Bash` |
| `model` | ❌ 否 | 使用的模型：`sonnet`, `opus`, `haiku`, `inherit` | `inherit` |

### 字段详解

#### `name` 字段
- **格式要求**：小写字母、数字、连字符（-）
- **长度限制**：1-64 字符
- **示例**：
  - ✅ 正确：`researcher`, `backend-dev`, `ux-ui`
  - ❌ 错误：`Researcher`（大写）, `backend_dev`（下划线）, `backend dev`（空格）

#### `description` 字段
- **作用**：Claude 根据此字段决定何时调用该 agent
- **最佳实践**：
  - 描述 agent 的职责和专长
  - 说明何时应该使用该 agent
  - 包含关键词便于 Claude 识别
- **示例**：
  ```yaml
  description: Technical research specialist for finding documentation, best practices, and up-to-date technical knowledge. Use for technology research, API documentation lookup, and technical problem investigation.
  ```

#### `tools` 字段
- **省略时**：agent 继承主线程的所有工具，包括 MCP 工具
- **指定时**：agent 仅能使用列出的工具
- **可用工具**：
  - 文件操作：`Read`, `Write`, `Edit`, `Glob`, `Grep`
  - 执行：`Bash`
  - 任务：`TodoWrite`
  - 网络：`WebSearch`, `WebFetch`
  - MCP 工具（如已连接）

**重要**：工具名称区分大小写，必须精确匹配。

#### `model` 字段
- **`inherit`**（推荐）：继承主线程的模型配置
- **`sonnet`**：Claude 3.5 Sonnet（平衡性能和成本）
- **`opus`**：Claude 3 Opus（最强性能）
- **`haiku`**：Claude 3.5 Haiku（快速且经济）

---

## 工具权限配置

### 自动继承权限（推荐）

**省略 `tools` 字段时，agent 自动继承所有工具权限，无需用户审批。**

```yaml
---
name: researcher
description: Research specialist
# 省略 tools 字段 = 继承所有工具
model: inherit
---
```

**优点**：
- ✅ 无需用户审批，agent 可直接使用所有工具
- ✅ 自动获取新增的 MCP 工具
- ✅ 配置简单

**缺点**：
- ⚠️ 安全性较低（所有工具都可用）

### 限制工具访问（推荐用于敏感操作）

```yaml
---
name: backend
description: Backend development specialist
tools: Read, Edit, Write, Bash, TodoWrite, Glob, Grep
model: inherit
---
```

**优点**：
- ✅ 更安全（仅授权必要工具）
- ✅ 防止意外操作

**缺点**：
- ⚠️ 需要明确列出所有需要的工具
- ⚠️ MCP 工具需单独配置

### 工具使用策略

#### 研究类 Agent
```yaml
tools: WebSearch, WebFetch, Read, Grep, Glob, TodoWrite
```

#### 开发类 Agent
```yaml
tools: Read, Edit, Write, Bash, TodoWrite, Glob, Grep
```

#### 规划类 Agent
```yaml
tools: Read, Write, Edit, TodoWrite
```

---

## Agent 识别和加载

### 如何验证 Agent 是否被识别

1. **检查 agent 文件格式**
   ```bash
   # 确保文件以 .md 结尾
   ls .claude/agents/
   ```

2. **验证 YAML frontmatter**
   - 确保有正确的 `---` 分隔符
   - 检查 `name` 和 `description` 字段是否存在
   - 验证 YAML 语法（使用在线 YAML 验证器）

3. **使用 `/agents` 命令**（Claude Code 内）
   ```
   /agents
   ```
   这会列出所有已识别的 agent。

### Claude Code 如何选择 Agent

Claude 基于以下因素决定调用哪个 agent：

1. **任务描述**：你提出的请求内容
2. **Agent 的 `description`**：与任务的匹配度
3. **当前上下文**：项目状态、已有信息
4. **可用工具**：agent 是否有完成任务所需的工具

**示例**：

```
用户请求："研究 NestJS 最佳实践"
Claude 分析：
  - 关键词：研究、NestJS、最佳实践
  - 匹配 agent: researcher
  - 原因：description 包含 "research", "best practices"
```

---

## 常见问题排查

### 问题 1: "Agent type 'xxx' not found"

**原因**：
- Agent 文件缺少 YAML frontmatter
- `name` 字段缺失或格式错误
- 文件不在正确的目录

**解决方案**：
1. 确认文件在 `.claude/agents/` 目录
2. 检查 YAML frontmatter 格式：
   ```yaml
   ---
   name: your-agent-name
   description: Your description
   ---
   ```
3. 确保 `name` 使用小写字母和连字符
4. 重启 Claude Code

### 问题 2: Agent 被识别但不被调用

**原因**：
- `description` 与任务不匹配
- Claude 选择了其他更合适的 agent
- Agent 缺少必需的工具

**解决方案**：
1. 改进 `description`，包含更多关键词
2. 明确告诉 Claude 使用特定 agent：
   ```
   请使用 researcher agent 查找 NestJS 文档
   ```
3. 检查 `tools` 字段是否包含必需工具

### 问题 3: YAML 解析错误

**常见错误**：
```yaml
# ❌ 错误：缺少结束的 ---
---
name: researcher
description: Research specialist

# ✅ 正确：有完整的分隔符
---
name: researcher
description: Research specialist
---
```

**解决方案**：
- 使用在线 YAML 验证器检查语法
- 确保没有隐藏字符（BOM、特殊空格）
- 使用 UTF-8 编码保存文件

### 问题 4: 工具权限不足

**表现**：Agent 运行时提示缺少工具权限

**解决方案**：
1. **方案A**：省略 `tools` 字段（继承所有工具）
   ```yaml
   ---
   name: researcher
   description: Research specialist
   # 省略 tools
   ---
   ```

2. **方案B**：明确添加所需工具
   ```yaml
   ---
   name: researcher
   description: Research specialist
   tools: WebSearch, WebFetch, Read, TodoWrite
   ---
   ```

---

## 最佳实践

### 1. Agent 设计原则

#### 单一职责
每个 agent 专注一个领域：
- ✅ 好：`researcher`（技术研究）
- ❌ 坏：`general-helper`（什么都做）

#### 清晰的边界
```yaml
# ✅ 好：职责明确
name: backend
description: Backend development for APIs, databases, and business logic

# ❌ 坏：职责模糊
name: developer
description: Writes code
```

### 2. Description 最佳实践

```yaml
# ✅ 优秀的 description
description: Technical research specialist for finding documentation, best practices, and up-to-date technical knowledge. Use for technology research, API documentation lookup, and technical problem investigation.

# 要素：
# - 角色定义：Technical research specialist
# - 核心能力：finding documentation, best practices
# - 使用场景：technology research, API documentation lookup
```

### 3. 工具配置策略

#### 渐进式工具授权
```yaml
# 阶段1：最小权限（测试阶段）
tools: Read, TodoWrite

# 阶段2：增加必要工具（稳定后）
tools: Read, Write, Edit, TodoWrite

# 阶段3：完全权限（信任后）
# 省略 tools 字段
```

### 4. 系统提示（System Prompt）设计

```markdown
---
name: researcher
description: Research specialist
tools: WebSearch, WebFetch, Read, TodoWrite
---

# Researcher Agent

You are a technical research specialist.

## Your Role
[明确定义角色]

## Core Responsibilities
1. Technical documentation research
2. Best practices discovery
3. Technology evaluation

## Tool Usage Priority
1. **WebSearch** - Primary tool for research
2. **WebFetch** - For specific URLs
3. **Read** - For local context

## Output Format
[定义输出格式]

## Best Practices
[列出最佳实践]
```

### 5. 版本控制

```bash
# 将 agent 配置纳入版本控制
git add .claude/agents/
git commit -m "Add custom sub agents configuration"

# 在 .gitignore 中排除敏感配置
# .gitignore
.claude/settings.local.json
```

### 6. 团队协作

**项目 README 中说明**：
```markdown
## Claude Code Sub Agents

本项目配置了以下 sub agents：

- `researcher` - 技术研究
- `architect` - 架构设计
- `backend` - 后端开发
- `frontend` - 前端开发
- `qa` - 质量保证

使用方式：
bash
# 直接向 Claude 提出请求，它会自动选择合适的 agent
"请研究 NestJS 最佳实践"  # → researcher
"实现用户登录API"        # → backend
```

---

## 完整配置示例

### 示例1: 技术研究 Agent

```yaml
---
name: researcher
description: Technical research specialist for finding documentation, best practices, and up-to-date technical knowledge. Use for technology research, API documentation lookup, and technical problem investigation.
tools: WebSearch, WebFetch, Read, Grep, Glob, TodoWrite
model: inherit
---

# Researcher Agent

You are the Research Specialist for the project.

## Core Responsibilities
1. Find official documentation
2. Research best practices
3. Compare technologies
4. Investigate technical problems

## Tool Usage
- **WebSearch**: Primary research tool
- **WebFetch**: Deep-dive specific URLs
- **Read**: Local project context

## Output Format
Always provide:
- Source URLs
- Version information
- Code examples
- Recommendations
```

### 示例2: 后端开发 Agent

```yaml
---
name: backend
description: Backend engineer for server-side development, API design, database implementation, and business logic. Use for backend code implementation, API development, and database work.
tools: Read, Edit, Write, Bash, TodoWrite, Glob, Grep
model: inherit
---

# Backend Agent

You are the Backend Engineer.

## Core Responsibilities
1. API development
2. Database design
3. Business logic implementation
4. Testing

## Code Standards
- TypeScript + NestJS
- 80%+ test coverage
- Proper error handling
- Clear documentation
```

---

## 权限管理高级配置

### settings.local.json 配置

在 `.claude/settings.local.json` 中可以预先授权常用操作：

```json
{
  "permissions": {
    "allow": [
      "Bash(npm test:*)",
      "Bash(npm run build:*)",
      "Bash(git status:*)",
      "Read(*)",
      "TodoWrite(*)"
    ],
    "deny": [
      "Bash(rm -rf:*)",
      "Bash(sudo:*)"
    ],
    "ask": [
      "Write(*)",
      "Edit(*)"
    ]
  }
}
```

**说明**：
- `allow`: 自动批准的操作（无需用户确认）
- `deny`: 拒绝的操作
- `ask`: 需要用户确认的操作

---

## 总结

### 快速检查清单

配置新的 agent 时，确保：

- [ ] 文件在 `.claude/agents/` 目录
- [ ] 文件名以 `.md` 结尾
- [ ] 有完整的 YAML frontmatter（`---` 包围）
- [ ] `name` 字段：小写字母+连字符
- [ ] `description` 字段：清晰描述用途
- [ ] `tools` 字段：省略（继承所有）或明确列出
- [ ] `model` 字段：推荐使用 `inherit`
- [ ] 系统提示清晰明确

### 推荐的 Agent 权限配置

```yaml
# 研究类（需要网络访问）
tools: WebSearch, WebFetch, Read, Grep, Glob, TodoWrite

# 开发类（需要文件操作和执行）
tools: Read, Edit, Write, Bash, TodoWrite, Glob, Grep

# 规划类（仅需文档操作）
tools: Read, Write, Edit, TodoWrite

# 完全信任（继承所有工具）
# 省略 tools 字段
```

---

## 参考资源

- [Claude Code 官方文档](https://docs.claude.com/en/docs/claude-code/sub-agents)
- [ClaudeLog - Custom Agents](https://claudelog.com/mechanics/custom-agents/)
- [YAML 语法验证器](https://www.yamllint.com/)

---

**最后更新**: 2025-11-02
**Claude Code 版本**: 2.0.31