ColaFlow/.claude/AGENT_QUICK_REFERENCE.md

Claude Code Agent 配置速查表

最小可用配置

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

Your system prompt here...

推荐配置模板

---
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: 继承所有工具（最简单，无需用户审批）

---
name: agent-name
description: Agent description
# 省略 tools 字段 = 继承所有工具
model: inherit
---

选项2: 限制工具访问（更安全）

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

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

验证配置

# 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