# Claude Code Agent 配置速查表

## 最小可用配置

```yaml
---
name: agent-name
description: What this agent does and when to use it
---

Your system prompt here...
```

## 推荐配置模板

```yaml
---
name: your-agent-name
description: Detailed description of agent's purpose and when Claude should invoke it. Include key responsibilities and use cases.
tools: Read, Write, Edit, Bash, TodoWrite, Glob, Grep, WebSearch, WebFetch
model: inherit
---

# Agent Title

Your detailed system prompt...
```

## 工具权限配置

### 选项1: 继承所有工具（最简单，无需用户审批）
```yaml
---
name: agent-name
description: Agent description
# 省略 tools 字段 = 继承所有工具
model: inherit
---
```

### 选项2: 限制工具访问（更安全）
```yaml
---
name: agent-name
description: Agent description
tools: Read, Write, Edit, TodoWrite  # 仅授权列出的工具
model: inherit
---
```

## 常用工具组合

| Agent 类型 | 推荐工具 |
|-----------|---------|
| **研究类** | `WebSearch, WebFetch, Read, Grep, Glob, TodoWrite` |
| **开发类** | `Read, Edit, Write, Bash, TodoWrite, Glob, Grep` |
| **规划类** | `Read, Write, Edit, TodoWrite` |
| **测试类** | `Read, Edit, Write, Bash, TodoWrite, Glob, Grep` |
| **设计类** | `Read, Write, Edit, TodoWrite` |

## 字段规则

| 字段 | 必需 | 格式 | 示例 |
|------|------|------|------|
| `name` | ✅ | 小写字母+连字符，1-64字符 | `researcher`, `backend-dev` |
| `description` | ✅ | 清晰描述，最大1024字符 | `Technical research specialist...` |
| `tools` | ❌ | 逗号分隔，区分大小写 | `Read, Write, Bash` |
| `model` | ❌ | `sonnet/opus/haiku/inherit` | `inherit` |

## 可用工具列表

### 文件操作
- `Read` - 读取文件
- `Write` - 创建/覆盖文件
- `Edit` - 编辑现有文件
- `Glob` - 文件模式匹配搜索
- `Grep` - 内容搜索

### 执行和任务
- `Bash` - 执行命令
- `TodoWrite` - 任务列表管理

### 网络访问
- `WebSearch` - 网络搜索
- `WebFetch` - 获取网页内容

### MCP 工具
- 省略 `tools` 字段时自动包含已连接的 MCP 工具

## 快速排错

### 错误: "Agent type 'xxx' not found"
✅ 检查清单：
- [ ] 文件在 `.claude/agents/` 目录
- [ ] 文件名以 `.md` 结尾
- [ ] 有完整的 YAML frontmatter（`---` 包围）
- [ ] `name` 字段存在且格式正确
- [ ] `description` 字段存在

### Agent 不被调用
✅ 解决方案：
- 改进 `description`，包含更多关键词
- 明确指定 agent：`请使用 researcher agent 查找文档`
- 检查 agent 是否有必需的工具权限

### YAML 解析错误
✅ 常见原因：
- 缺少结束的 `---`
- YAML 语法错误（缩进、引号）
- 文件编码问题（使用 UTF-8）

## 文件位置

- **项目级别**（推荐）: `.claude/agents/your-agent.md`
- **用户级别**: `~/.claude/agents/your-agent.md`

**优先级**: 项目级别 > 用户级别

## 验证配置

```bash
# 1. 检查文件是否存在
ls .claude/agents/

# 2. 在 Claude Code 中验证
/agents

# 3. 测试调用
请使用 [agent-name] agent 执行 [任务]
```

## 最佳实践

1. **名称**: 使用描述性的名称（`researcher` 而非 `agent1`）
2. **描述**: 包含职责、专长、使用场景
3. **工具**: 开始时限制工具，稳定后再放开
4. **提示**: 提供清晰的结构和示例
5. **测试**: 配置后立即测试验证

## 当前项目的 Agent

| Agent | 用途 | 主要工具 |
|-------|------|---------|
| `researcher` | 技术研究、文档查找 | WebSearch, WebFetch |
| `architect` | 架构设计、技术选型 | Read, Write, Edit |
| `backend` | 后端开发、API实现 | Read, Edit, Write, Bash |
| `frontend` | 前端开发、UI实现 | Read, Edit, Write, Bash |
| `product-manager` | 项目规划、需求管理 | Read, Write, Edit |
| `qa` | 测试设计、质量保证 | Read, Edit, Write, Bash |
| `ux-ui` | 界面设计、交互设计 | Read, Write, Edit |
| `ai` | AI功能、提示工程 | Read, Edit, Write, Bash |
| `progress-recorder` | 进度跟踪、记忆管理 | Read, Write, Edit |

---

**提示**: 查看完整文档请参考 `.claude/AGENT_CONFIGURATION_GUIDE.md`