ColaFlow/.claude/AGENT_CONFIGURATION_GUIDE.md

Claude Code 自定义 Agent 配置完整指南

本文档提供了在 Claude Code 中配置和使用自定义 sub agent 的完整说明。

目录

1. 基础知识
2. YAML Frontmatter 格式
3. 工具权限配置
4. 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 开头：

---
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 识别
• 示例：

  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 自动继承所有工具权限，无需用户审批。

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

优点：

• ✅ 无需用户审批，agent 可直接使用所有工具
• ✅ 自动获取新增的 MCP 工具
• ✅ 配置简单

缺点：

• ⚠️ 安全性较低（所有工具都可用）

限制工具访问（推荐用于敏感操作）

---
name: backend
description: Backend development specialist
tools: Read, Edit, Write, Bash, TodoWrite, Glob, Grep
model: inherit
---

优点：

• ✅ 更安全（仅授权必要工具）
• ✅ 防止意外操作

缺点：

• ⚠️ 需要明确列出所有需要的工具
• ⚠️ MCP 工具需单独配置

工具使用策略

研究类 Agent

tools: WebSearch, WebFetch, Read, Grep, Glob, TodoWrite

开发类 Agent

tools: Read, Edit, Write, Bash, TodoWrite, Glob, Grep

规划类 Agent

tools: Read, Write, Edit, TodoWrite

---

Agent 识别和加载

如何验证 Agent 是否被识别

1. 检查 agent 文件格式

   # 确保文件以 .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 格式：

   ---
   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 解析错误

常见错误：

# ❌ 错误：缺少结束的 ---
---
name: researcher
description: Research specialist

# ✅ 正确：有完整的分隔符
---
name: researcher
description: Research specialist
---

解决方案：

• 使用在线 YAML 验证器检查语法
• 确保没有隐藏字符（BOM、特殊空格）
• 使用 UTF-8 编码保存文件

问题 4: 工具权限不足

表现：Agent 运行时提示缺少工具权限

解决方案：

1. 方案A：省略 tools 字段（继承所有工具）

   ---
   name: researcher
   description: Research specialist
   # 省略 tools
   ---
   

2. 方案B：明确添加所需工具

   ---
   name: researcher
   description: Research specialist
   tools: WebSearch, WebFetch, Read, TodoWrite
   ---
   

---

最佳实践

1. Agent 设计原则

单一职责

每个 agent 专注一个领域：

• ✅ 好：researcher（技术研究）
• ❌ 坏：general-helper（什么都做）

清晰的边界

# ✅ 好：职责明确
name: backend
description: Backend development for APIs, databases, and business logic

# ❌ 坏：职责模糊
name: developer
description: Writes code

2. Description 最佳实践

# ✅ 优秀的 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. 工具配置策略

渐进式工具授权

# 阶段1：最小权限（测试阶段）
tools: Read, TodoWrite

# 阶段2：增加必要工具（稳定后）
tools: Read, Write, Edit, TodoWrite

# 阶段3：完全权限（信任后）
# 省略 tools 字段

4. 系统提示（System Prompt）设计

---
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. 版本控制

# 将 agent 配置纳入版本控制
git add .claude/agents/
git commit -m "Add custom sub agents configuration"

# 在 .gitignore 中排除敏感配置
# .gitignore
.claude/settings.local.json

6. 团队协作

项目 README 中说明：

## Claude Code Sub Agents

本项目配置了以下 sub agents：

- `researcher` - 技术研究
- `architect` - 架构设计
- `backend` - 后端开发
- `frontend` - 前端开发
- `qa` - 质量保证

使用方式：
bash
# 直接向 Claude 提出请求，它会自动选择合适的 agent
"请研究 NestJS 最佳实践"  # → researcher
"实现用户登录API"        # → backend

---

完整配置示例

示例1: 技术研究 Agent

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

---
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 中可以预先授权常用操作：

{
  "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 权限配置

# 研究类（需要网络访问）
tools: WebSearch, WebFetch, Read, Grep, Glob, TodoWrite

# 开发类（需要文件操作和执行）
tools: Read, Edit, Write, Bash, TodoWrite, Glob, Grep

# 规划类（仅需文档操作）
tools: Read, Write, Edit, TodoWrite

# 完全信任（继承所有工具）
# 省略 tools 字段

---

参考资源

• Claude Code 官方文档
• ClaudeLog - Custom Agents
• YAML 语法验证器

---

最后更新: 2025-11-02 Claude Code 版本: 2.0.31