014d62bcc2
🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
550 lines
12 KiB
Markdown
550 lines
12 KiB
Markdown
# 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
|