Project Init
🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Yaojia Wang
549
.claude/AGENT_CONFIGURATION_GUIDE.md
Normal file
549
.claude/AGENT_CONFIGURATION_GUIDE.md
Normal file
@@ -0,0 +1,549 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user