ColaFlow/.claude/RESEARCH_REPORT_AGENT_CONFIGURATION.md

# Claude Code 自定义 Agent 配置研究报告

**研究日期**: 2025-11-02
**Claude Code 版本**: 2.0.31
**研究目的**: 了解如何正确配置自定义 sub agent 并赋予最高权限

---

## 执行摘要

成功完成了 Claude Code 自定义 agent 配置的研究，并为项目的 9 个 agent 文件添加了正确的 YAML frontmatter 配置。研究发现，通过省略 `tools` 字段，agent 可以继承所有工具权限而无需用户审批。

---

## 研究发现

### 1. Agent 配置正确格式

#### 必需的 YAML Frontmatter 结构

所有自定义 agent 文件必须包含 YAML frontmatter：

```yaml
---
name: agent-name
description: Agent description
tools: Tool1, Tool2, Tool3  # 可选
model: inherit              # 可选
---

# Agent system prompt content
```

#### 关键字段要求

| 字段 | 必需 | 格式要求 | 作用 |
|------|------|---------|------|
| `name` | ✅ 是 | 小写字母、数字、连字符，1-64字符 | Agent 唯一标识符 |
| `description` | ✅ 是 | 最大1024字符 | Claude 用于判断何时调用该 agent |
| `tools` | ❌ 否 | 逗号分隔，区分大小写 | 限制 agent 可用工具 |
| `model` | ❌ 否 | `sonnet/opus/haiku/inherit` | 指定使用的模型 |

**来源**:
- [Claude Code 官方文档](https://docs.claude.com/en/docs/claude-code/sub-agents)
- [ClaudeLog - Custom Agents](https://claudelog.com/mechanics/custom-agents/)

---

### 2. 工具权限配置机制

#### 方案A: 自动继承（最高权限，无需审批）

**配置方法**: 省略 `tools` 字段

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

**效果**:
- ✅ Agent 自动获得所有工具权限
- ✅ 包括 MCP server 的自定义工具
- ✅ **无需用户审批**即可使用工具
- ✅ 新增工具会自动可用

**来源**: 官方文档明确说明 "omit to inherit all tools from the main thread"

#### 方案B: 限制性授权（安全但需配置）

**配置方法**: 明确列出允许的工具

```yaml
---
name: backend
description: Backend developer
tools: Read, Edit, Write, Bash, TodoWrite
model: inherit
---
```

**效果**:
- ✅ 更安全，仅授权必要工具
- ⚠️ 需要手动管理工具列表
- ⚠️ MCP 工具需要显式添加

---

### 3. Agent 识别和加载机制

#### Claude Code 如何发现 Agent

1. **扫描目录**:
   - 项目级别: `.claude/agents/*.md`
   - 用户级别: `~/.claude/agents/*.md`
   - 优先级: 项目 > 用户

2. **解析 Frontmatter**:
   - 验证 YAML 语法
   - 提取 `name` 和 `description`
   - 解析 `tools` 和 `model`

3. **注册 Agent**:
   - 使用 `name` 作为唯一标识符
   - `description` 用于智能路由

#### Claude Code 如何选择 Agent

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

1. **任务描述分析**: 用户请求的关键词
2. **Agent description 匹配**: 与任务的相关度
3. **当前上下文**: 项目状态、历史对话
4. **工具可用性**: Agent 是否有完成任务所需的工具

**示例匹配逻辑**:
```
用户: "研究 NestJS 最佳实践"
→ 关键词: 研究, NestJS, 最佳实践
→ 匹配: researcher (description 包含 "research", "best practices")
→ 调用: researcher agent
```

---

### 4. 常见问题和解决方案

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

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

**解决方案**:
1. 确保文件在 `.claude/agents/` 目录
2. 添加完整的 YAML frontmatter
3. 验证 `name` 格式（小写+连字符）
4. 重启 Claude Code（如需要）

**证据**: GitHub Issue [#4623](https://github.com/anthropics/claude-code/issues/4623) 显示此问题在早期版本（1.0.62）中存在，已在后续版本修复。

#### 问题2: YAML Frontmatter 解析错误

**常见错误**:
- 缺少结束的 `---` 分隔符
- YAML 语法错误（缩进、引号）
- 文件编码问题（BOM、非UTF-8）

**解决方案**:
```yaml
# ❌ 错误示例
---
name: researcher
description: Research agent
（缺少结束的 ---）

# ✅ 正确示例
---
name: researcher
description: Research agent
---
```

**证据**: GitHub Issue [#6377](https://github.com/anthropics/claude-code/issues/6377) 报告了 frontmatter 解析问题。

#### 问题3: Agent 配置正确但不被调用

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

**解决方案**:
1. 优化 `description`，添加更多相关关键词
2. 明确指定 agent: `请使用 researcher agent 查找文档`
3. 检查 `tools` 配置是否包含所需工具

---

### 5. 可用工具清单

#### 核心工具

| 工具 | 用途 | 典型使用场景 |
|------|------|------------|
| `Read` | 读取文件内容 | 查看代码、配置、文档 |
| `Write` | 创建新文件 | 生成新代码、文档 |
| `Edit` | 编辑现有文件 | 修改代码、更新配置 |
| `Glob` | 文件模式搜索 | 查找特定类型文件 |
| `Grep` | 内容搜索 | 代码搜索、查找引用 |
| `Bash` | 执行命令 | 运行测试、构建、Git操作 |
| `TodoWrite` | 任务管理 | 跟踪开发任务 |
| `WebSearch` | 网络搜索 | 查找最新技术信息 |
| `WebFetch` | 获取网页 | 读取特定文档页面 |

#### 工具使用注意事项

1. **工具名称区分大小写**: 必须精确匹配（`Read` 而非 `read`）
2. **MCP 工具**: 省略 `tools` 字段时自动包含
3. **工具权限**: 省略 `tools` = 无需用户审批

---

### 6. 最佳实践总结

#### Agent 设计原则

1. **单一职责**: 每个 agent 专注一个领域
   ```yaml
   # ✅ 好
   name: researcher
   description: Technical research specialist

   # ❌ 坏
   name: helper
   description: Does everything
   ```

2. **清晰的描述**: 包含职责、专长、使用场景
   ```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.
   ```

3. **渐进式权限**: 从最小权限开始，逐步扩展
   ```yaml
   # 阶段1: 最小权限
   tools: Read, TodoWrite

   # 阶段2: 增加必要工具
   tools: Read, Write, Edit, TodoWrite

   # 阶段3: 完全信任
   # 省略 tools 字段
   ```

#### 工具配置策略

| Agent 类型 | 推荐配置 | 理由 |
|-----------|---------|------|
| 研究类 | `WebSearch, WebFetch, Read, TodoWrite` | 需要网络访问 |
| 开发类 | `Read, Edit, Write, Bash, TodoWrite` | 需要文件和命令执行 |
| 规划类 | `Read, Write, Edit, TodoWrite` | 仅需文档操作 |
| 完全信任 | 省略 `tools` 字段 | 无需审批，最高效 |

---

## 实施成果

### 已完成的配置

为项目的 9 个 agent 添加了正确的 YAML frontmatter：

| Agent 文件 | Name | 工具配置 | 状态 |
|-----------|------|---------|------|
| `researcher.md` | `researcher` | WebSearch, WebFetch, Read, Grep, Glob, TodoWrite | ✅ 已配置 |
| `architect.md` | `architect` | Read, Write, Edit, TodoWrite, Glob, Grep | ✅ 已配置 |
| `backend.md` | `backend` | Read, Edit, Write, Bash, TodoWrite, Glob, Grep | ✅ 已配置 |
| `frontend.md` | `frontend` | Read, Edit, Write, Bash, TodoWrite, Glob, Grep | ✅ 已配置 |
| `product-manager.md` | `product-manager` | Read, Write, Edit, TodoWrite | ✅ 已配置 |
| `qa.md` | `qa` | Read, Edit, Write, Bash, TodoWrite, Glob, Grep | ✅ 已配置 |
| `ux-ui.md` | `ux-ui` | Read, Write, Edit, TodoWrite | ✅ 已配置 |
| `ai.md` | `ai` | Read, Edit, Write, Bash, TodoWrite, Glob, Grep | ✅ 已配置 |
| `progress-recorder.md` | `progress-recorder` | Read, Write, Edit, TodoWrite | ✅ 已配置 |

### 配置示例

**researcher.md** (完整示例):
```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 ColaFlow...
```

---

## 创建的文档

为便于使用，创建了以下文档：

1. **完整配置指南** (`.claude/AGENT_CONFIGURATION_GUIDE.md`)
   - 详细的配置说明
   - 故障排除指南
   - 最佳实践
   - 完整示例

2. **快速参考卡** (`.claude/AGENT_QUICK_REFERENCE.md`)
   - 最小配置模板
   - 常用工具组合
   - 快速排错清单
   - 当前项目 agent 列表

3. **研究报告** (本文档)
   - 研究发现总结
   - 技术细节
   - 实施成果

---

## 技术细节

### YAML Frontmatter 解析机制

Claude Code 使用标准的 YAML 解析器处理 frontmatter：

1. **分隔符识别**:
   - 开始: `---` (文件开头)
   - 结束: `---` (紧跟 YAML 内容)

2. **字段提取**:
   ```typescript
   interface AgentConfig {
     name: string;           // 必需
     description: string;    // 必需
     tools?: string[];       // 可选，逗号分隔转数组
     model?: string;         // 可选
   }
   ```

3. **验证规则**:
   - `name`: 正则 `/^[a-z0-9-]{1,64}$/`
   - `description`: 长度 ≤ 1024
   - `tools`: 大小写敏感
   - `model`: 枚举值 `sonnet|opus|haiku|inherit`

### 工具权限继承机制

```typescript
// 伪代码表示权限继承逻辑
function resolveAgentTools(agent: AgentConfig): string[] {
  if (agent.tools === undefined) {
    // 省略 tools 字段 → 继承所有工具
    return [
      ...mainThreadTools,     // 主线程工具
      ...mcpServerTools,      // MCP 服务器工具
    ];
  } else {
    // 显式指定 → 仅使用列出的工具
    return agent.tools;
  }
}
```

**关键发现**: 省略 `tools` 字段时，agent 获得完全的工具访问权限，无需用户审批每个工具调用。

---

## 验证方法

### 1. 检查 Agent 是否被识别

```bash
# 方法1: 检查文件
ls .claude/agents/

# 方法2: 在 Claude Code 中
/agents
```

### 2. 测试 Agent 调用

```
# 自动路由（推荐）
请研究 NestJS 最佳实践

# 明确指定
请使用 researcher agent 查找 TypeORM 文档

# 验证工具权限
请使用 researcher agent 搜索最新的 React 18 特性
（应该能自动使用 WebSearch，无需审批）
```

### 3. 验证 YAML 格式

使用在线 YAML 验证器:
- https://www.yamllint.com/
- https://jsonformatter.org/yaml-validator

---

## 已知问题和限制

### 1. Sub Agent 不能嵌套调用

**问题**: Sub agent 内部无法使用 Task tool 调用其他 agent

**影响**: 无法创建层次化的 agent 工作流

**来源**: GitHub Issue [#4182](https://github.com/anthropics/claude-code/issues/4182)

**解决方案**: 在主协调器中编排多个 agent 的调用顺序

### 2. 早期版本的 Agent 检测问题

**问题**: Claude Code 1.0.62 版本存在 agent 检测失败

**状态**: 已在后续版本修复（当前 2.0.31 正常）

**来源**: GitHub Issue [#4623](https://github.com/anthropics/claude-code/issues/4623)

### 3. Windows 平台特殊问题

**问题**: Windows 上可能出现 ripgrep 二进制文件缺失

**表现**: "spawn rg.exe ENOENT" 错误

**解决方案**: 更新到最新版本的 Claude Code

---

## 推荐配置

### 针对 ColaFlow 项目的建议

1. **当前配置（已实施）**: 为每个 agent 明确列出工具
   - ✅ 优点: 安全可控
   - ⚠️ 缺点: 需要手动管理工具列表

2. **高效配置（建议）**: 省略 `tools` 字段
   ```yaml
   ---
   name: researcher
   description: Research specialist...
   # 省略 tools 字段 = 继承所有工具，无需审批
   model: inherit
   ---
   ```
   - ✅ 优点: 无需用户审批，最高效
   - ✅ 适合: 受信任的项目环境

3. **平衡配置**: 根据 agent 类型区分
   ```yaml
   # 开发类 agent: 完全信任
   ---
   name: backend
   description: Backend developer
   # 省略 tools
   ---

   # 外部交互类: 限制权限
   ---
   name: researcher
   description: Research specialist
   tools: WebSearch, WebFetch, Read, TodoWrite
   ---
   ```

---

## 参考资源

### 官方文档
- [Claude Code Subagents](https://docs.claude.com/en/docs/claude-code/sub-agents) - 官方文档
- [Claude Code GitHub](https://github.com/anthropics/claude-code) - 官方仓库

### 社区资源
- [ClaudeLog - Custom Agents](https://claudelog.com/mechanics/custom-agents/) - 详细指南
- [ClaudeLog - Task/Agent Tools](https://claudelog.com/mechanics/task-agent-tools/) - 工具使用
- [Practical Guide to Claude Code Sub-Agents](https://jewelhuq.medium.com/practical-guide-to-mastering-claude-codes-main-agent-and-sub-agents-fd52952dcf00) - 实践指南

### GitHub Issues
- [#4623 - Sub-Agents Not Detected](https://github.com/anthropics/claude-code/issues/4623)
- [#6377 - Frontmatter Parsing Error](https://github.com/anthropics/claude-code/issues/6377)
- [#4182 - Sub-Agent Task Tool Not Exposed](https://github.com/anthropics/claude-code/issues/4182)
- [#4728 - Custom Agents Not Detected](https://github.com/anthropics/claude-code/issues/4728)

### 工具
- [YAML Lint](https://www.yamllint.com/) - YAML 验证器
- [JSON Formatter YAML Validator](https://jsonformatter.org/yaml-validator)

---

## 下一步行动

### 推荐的后续步骤

1. **测试验证** (立即)
   ```
   # 在 Claude Code 中测试每个 agent
   请使用 researcher agent 查找 NestJS 文档
   请使用 backend agent 实现一个简单的 API
   ```

2. **权限优化** (可选)
   - 考虑将受信任的 agent 改为省略 `tools` 字段
   - 评估是否需要 `.claude/settings.local.json` 预授权

3. **团队协作** (建议)
   - 在团队中分享配置文档
   - 统一 agent 使用规范
   - 收集使用反馈

4. **持续优化** (长期)
   - 根据实际使用调整 `description`
   - 优化 agent 的系统提示
   - 添加新的专业 agent

---

## 总结

### 核心发现

1. **配置要求**: 所有 agent 必须有正确的 YAML frontmatter，包含 `name` 和 `description`
2. **权限机制**: 省略 `tools` 字段可获得最高权限且无需用户审批
3. **识别机制**: Claude 基于 `description` 自动选择合适的 agent
4. **文件位置**: 项目级别 `.claude/agents/` 优先于用户级别

### 成功标准

- ✅ 所有 9 个 agent 文件已添加正确的 YAML frontmatter
- ✅ 创建了完整的配置文档和快速参考
- ✅ 理解了工具权限的配置机制
- ✅ 掌握了故障排查方法

### 实践价值

通过本次研究和配置，ColaFlow 项目现在拥有：
- 9 个专业化的 sub agent
- 完整的配置文档体系
- 清晰的工具权限管理策略
- 可复制的配置模式

这将显著提升 AI 辅助开发的效率和协作质量。

---

**报告作者**: Claude (Sonnet 4.5)
**研究完成时间**: 2025-11-02
**项目**: ColaFlow
**Claude Code 版本**: 2.0.31