014d62bcc2
🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
406 lines
9.6 KiB
Markdown
406 lines
9.6 KiB
Markdown
# Agent 配置验证清单
|
||
|
||
本文档帮助你验证 Claude Code agent 配置是否正确。
|
||
|
||
## 自动检查清单
|
||
|
||
### 1. 文件结构检查
|
||
|
||
```bash
|
||
# 检查 .claude/agents 目录是否存在
|
||
ls .claude/agents/
|
||
|
||
# 预期输出：列出所有 .md 文件
|
||
# ai.md
|
||
# architect.md
|
||
# backend.md
|
||
# frontend.md
|
||
# product-manager.md
|
||
# progress-recorder.md
|
||
# qa.md
|
||
# researcher.md
|
||
# ux-ui.md
|
||
```
|
||
|
||
✅ **验证点**: 确认所有 agent 文件都存在且以 `.md` 结尾
|
||
|
||
---
|
||
|
||
### 2. YAML Frontmatter 检查
|
||
|
||
对每个文件，确认包含以下内容：
|
||
|
||
```yaml
|
||
---
|
||
name: agent-name # 必须：小写+连字符
|
||
description: ... # 必须：清晰描述
|
||
tools: ... # 可选：工具列表
|
||
model: inherit # 可选：模型配置
|
||
---
|
||
```
|
||
|
||
#### 快速验证命令
|
||
|
||
```bash
|
||
# Windows PowerShell
|
||
Get-Content .claude/agents/*.md -Head 10 | Select-String -Pattern "^---$|^name:|^description:"
|
||
|
||
# 预期输出：每个文件都应该显示
|
||
# ---
|
||
# name: xxx
|
||
# description: xxx
|
||
# ---
|
||
```
|
||
|
||
✅ **验证点**:
|
||
- [ ] 每个文件开头有 `---`
|
||
- [ ] 包含 `name:` 字段
|
||
- [ ] 包含 `description:` 字段
|
||
- [ ] frontmatter 以 `---` 结束
|
||
|
||
---
|
||
|
||
### 3. Name 字段格式检查
|
||
|
||
**格式要求**: 小写字母、数字、连字符（-），1-64字符
|
||
|
||
✅ **正确示例**:
|
||
- `researcher`
|
||
- `backend-dev`
|
||
- `ux-ui`
|
||
- `qa-engineer-2`
|
||
|
||
❌ **错误示例**:
|
||
- `Researcher` (大写)
|
||
- `backend_dev` (下划线)
|
||
- `backend dev` (空格)
|
||
- `研究员` (非ASCII)
|
||
|
||
#### 验证方法
|
||
|
||
打开每个 agent 文件，检查 `name:` 字段：
|
||
|
||
```bash
|
||
# 检查所有 name 字段
|
||
grep "^name:" .claude/agents/*.md
|
||
```
|
||
|
||
---
|
||
|
||
### 4. Description 字段检查
|
||
|
||
**要求**: 清晰描述 agent 的用途和使用场景
|
||
|
||
✅ **好的 description**:
|
||
```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.
|
||
```
|
||
|
||
包含:
|
||
- 角色定义: "Technical research specialist"
|
||
- 核心能力: "finding documentation, best practices"
|
||
- 使用场景: "technology research, API documentation lookup"
|
||
|
||
❌ **不好的 description**:
|
||
```yaml
|
||
description: Research agent # 太简单
|
||
description: Does stuff # 不明确
|
||
```
|
||
|
||
#### 验证方法
|
||
|
||
```bash
|
||
# 查看所有 description
|
||
grep "^description:" .claude/agents/*.md
|
||
```
|
||
|
||
---
|
||
|
||
### 5. Tools 字段检查
|
||
|
||
**可选字段**: 省略则继承所有工具
|
||
|
||
#### 选项A: 省略 tools（推荐）
|
||
```yaml
|
||
---
|
||
name: researcher
|
||
description: Research specialist
|
||
# 没有 tools 字段 = 继承所有工具
|
||
model: inherit
|
||
---
|
||
```
|
||
|
||
#### 选项B: 明确指定 tools
|
||
```yaml
|
||
---
|
||
name: researcher
|
||
description: Research specialist
|
||
tools: WebSearch, WebFetch, Read, TodoWrite
|
||
model: inherit
|
||
---
|
||
```
|
||
|
||
⚠️ **注意**:
|
||
- 工具名称**区分大小写**: `Read` 而非 `read`
|
||
- 逗号分隔，可以有空格: `Read, Write` 或 `Read,Write`
|
||
- 常用工具: `Read`, `Write`, `Edit`, `Bash`, `Glob`, `Grep`, `TodoWrite`, `WebSearch`, `WebFetch`
|
||
|
||
---
|
||
|
||
### 6. 在 Claude Code 中验证
|
||
|
||
#### 方法1: 使用 /agents 命令
|
||
|
||
在 Claude Code 中输入：
|
||
```
|
||
/agents
|
||
```
|
||
|
||
应该看到你的自定义 agent 列表。
|
||
|
||
#### 方法2: 直接测试
|
||
|
||
```
|
||
请使用 researcher agent 查找 NestJS 文档
|
||
```
|
||
|
||
如果 agent 被正确识别，Claude 会：
|
||
1. 调用 researcher agent
|
||
2. 使用 WebSearch 查找文档
|
||
3. 返回研究结果
|
||
|
||
---
|
||
|
||
## 手动检查清单
|
||
|
||
### 每个 Agent 文件检查
|
||
|
||
对每个 `.claude/agents/*.md` 文件，确认：
|
||
|
||
- [ ] 文件以 `.md` 结尾
|
||
- [ ] 文件开头有 `---`
|
||
- [ ] 有 `name:` 字段，格式正确（小写+连字符）
|
||
- [ ] 有 `description:` 字段，描述清晰
|
||
- [ ] 如果有 `tools:` 字段，工具名称正确
|
||
- [ ] frontmatter 以 `---` 结束
|
||
- [ ] `---` 后面有 agent 的系统提示内容
|
||
|
||
### 示例检查模板
|
||
|
||
```markdown
|
||
# ✅ 检查 researcher.md
|
||
|
||
文件路径: .claude/agents/researcher.md
|
||
|
||
1. [ ] 文件存在
|
||
2. [ ] YAML frontmatter 格式正确
|
||
---
|
||
name: researcher
|
||
description: Technical research specialist...
|
||
tools: WebSearch, WebFetch, Read, Grep, Glob, TodoWrite
|
||
model: inherit
|
||
---
|
||
3. [ ] name 格式正确（小写+连字符）
|
||
4. [ ] description 清晰明确
|
||
5. [ ] tools 工具名称正确（首字母大写）
|
||
6. [ ] 有完整的系统提示内容
|
||
```
|
||
|
||
---
|
||
|
||
## 常见问题检查
|
||
|
||
### 问题1: "Agent type 'xxx' not found"
|
||
|
||
检查清单:
|
||
- [ ] 文件在 `.claude/agents/` 目录
|
||
- [ ] 文件名以 `.md` 结尾
|
||
- [ ] 有完整的 YAML frontmatter (`---` 包围)
|
||
- [ ] `name` 字段存在且格式正确
|
||
- [ ] `description` 字段存在
|
||
- [ ] 尝试重启 Claude Code
|
||
|
||
### 问题2: Agent 不被自动调用
|
||
|
||
检查清单:
|
||
- [ ] `description` 包含相关关键词
|
||
- [ ] 尝试明确指定 agent: `请使用 [agent-name] agent ...`
|
||
- [ ] 检查 agent 是否有必需的工具权限
|
||
|
||
### 问题3: YAML 解析错误
|
||
|
||
检查清单:
|
||
- [ ] 开头有 `---`
|
||
- [ ] 结尾有 `---`
|
||
- [ ] YAML 语法正确（使用 https://www.yamllint.com/ 验证）
|
||
- [ ] 没有特殊字符或隐藏字符
|
||
- [ ] 文件编码为 UTF-8
|
||
|
||
---
|
||
|
||
## 快速验证脚本
|
||
|
||
### PowerShell 脚本 (Windows)
|
||
|
||
```powershell
|
||
# 验证所有 agent 文件
|
||
$agentFiles = Get-ChildItem -Path .claude/agents/*.md
|
||
|
||
foreach ($file in $agentFiles) {
|
||
Write-Host "`n========================================" -ForegroundColor Cyan
|
||
Write-Host "验证: $($file.Name)" -ForegroundColor Cyan
|
||
Write-Host "========================================" -ForegroundColor Cyan
|
||
|
||
$content = Get-Content $file.FullName -Raw
|
||
|
||
# 检查 frontmatter
|
||
if ($content -match '^---\s*\n(.*?\n)---') {
|
||
Write-Host "✅ YAML Frontmatter 存在" -ForegroundColor Green
|
||
|
||
$yaml = $matches[1]
|
||
|
||
# 检查 name
|
||
if ($yaml -match 'name:\s*([a-z0-9-]+)') {
|
||
Write-Host "✅ name: $($matches[1])" -ForegroundColor Green
|
||
} else {
|
||
Write-Host "❌ name 字段缺失或格式错误" -ForegroundColor Red
|
||
}
|
||
|
||
# 检查 description
|
||
if ($yaml -match 'description:\s*(.+)') {
|
||
Write-Host "✅ description 存在" -ForegroundColor Green
|
||
} else {
|
||
Write-Host "❌ description 字段缺失" -ForegroundColor Red
|
||
}
|
||
|
||
# 检查 tools
|
||
if ($yaml -match 'tools:\s*(.+)') {
|
||
Write-Host "ℹ️ tools: $($matches[1])" -ForegroundColor Yellow
|
||
} else {
|
||
Write-Host "ℹ️ tools 未指定（将继承所有工具）" -ForegroundColor Yellow
|
||
}
|
||
|
||
} else {
|
||
Write-Host "❌ YAML Frontmatter 缺失或格式错误" -ForegroundColor Red
|
||
}
|
||
}
|
||
|
||
Write-Host "`n========================================" -ForegroundColor Cyan
|
||
Write-Host "验证完成" -ForegroundColor Cyan
|
||
Write-Host "========================================" -ForegroundColor Cyan
|
||
```
|
||
|
||
### Bash 脚本 (Linux/Mac)
|
||
|
||
```bash
|
||
#!/bin/bash
|
||
|
||
echo "开始验证 Claude Code Agent 配置..."
|
||
echo ""
|
||
|
||
for file in .claude/agents/*.md; do
|
||
echo "========================================"
|
||
echo "验证: $(basename $file)"
|
||
echo "========================================"
|
||
|
||
# 检查 frontmatter
|
||
if head -n 20 "$file" | grep -q "^---$"; then
|
||
echo "✅ YAML Frontmatter 存在"
|
||
|
||
# 提取 frontmatter
|
||
yaml=$(awk '/^---$/,/^---$/{if (NR>1) print}' "$file" | head -n -1)
|
||
|
||
# 检查 name
|
||
if echo "$yaml" | grep -q "^name:"; then
|
||
name=$(echo "$yaml" | grep "^name:" | cut -d: -f2 | tr -d ' ')
|
||
echo "✅ name: $name"
|
||
else
|
||
echo "❌ name 字段缺失"
|
||
fi
|
||
|
||
# 检查 description
|
||
if echo "$yaml" | grep -q "^description:"; then
|
||
echo "✅ description 存在"
|
||
else
|
||
echo "❌ description 字段缺失"
|
||
fi
|
||
|
||
# 检查 tools
|
||
if echo "$yaml" | grep -q "^tools:"; then
|
||
tools=$(echo "$yaml" | grep "^tools:" | cut -d: -f2)
|
||
echo "ℹ️ tools:$tools"
|
||
else
|
||
echo "ℹ️ tools 未指定（将继承所有工具）"
|
||
fi
|
||
else
|
||
echo "❌ YAML Frontmatter 缺失或格式错误"
|
||
fi
|
||
|
||
echo ""
|
||
done
|
||
|
||
echo "========================================"
|
||
echo "验证完成"
|
||
echo "========================================"
|
||
```
|
||
|
||
---
|
||
|
||
## 验证通过标准
|
||
|
||
所有检查项都应该为 ✅：
|
||
|
||
### 基础检查
|
||
- ✅ `.claude/agents/` 目录存在
|
||
- ✅ 所有 agent 文件以 `.md` 结尾
|
||
- ✅ 每个文件有正确的 YAML frontmatter
|
||
|
||
### 必需字段检查
|
||
- ✅ 每个 agent 有 `name` 字段（小写+连字符）
|
||
- ✅ 每个 agent 有 `description` 字段（清晰描述）
|
||
|
||
### 功能检查
|
||
- ✅ 在 Claude Code 中能看到自定义 agent（`/agents`）
|
||
- ✅ 能成功调用 agent（测试请求）
|
||
- ✅ Agent 能使用配置的工具
|
||
|
||
---
|
||
|
||
## 下一步
|
||
|
||
验证通过后，你可以：
|
||
|
||
1. **测试 Agent**: 在 Claude Code 中测试每个 agent
|
||
```
|
||
请使用 researcher agent 查找最新的 React 文档
|
||
请使用 backend agent 设计一个 REST API
|
||
```
|
||
|
||
2. **优化配置**: 根据实际使用调整 description 和 tools
|
||
|
||
3. **团队分享**: 与团队成员分享配置文档
|
||
|
||
4. **持续改进**: 收集使用反馈，优化 agent 设计
|
||
|
||
---
|
||
|
||
## 获取帮助
|
||
|
||
如果验证失败或遇到问题：
|
||
|
||
1. **查看文档**:
|
||
- `.claude/AGENT_CONFIGURATION_GUIDE.md` - 完整配置指南
|
||
- `.claude/AGENT_QUICK_REFERENCE.md` - 快速参考
|
||
- `.claude/RESEARCH_REPORT_AGENT_CONFIGURATION.md` - 研究报告
|
||
|
||
2. **在线资源**:
|
||
- [Claude Code 官方文档](https://docs.claude.com/en/docs/claude-code/sub-agents)
|
||
- [ClaudeLog - Custom Agents](https://claudelog.com/mechanics/custom-agents/)
|
||
|
||
3. **检查 GitHub Issues**:
|
||
- [Claude Code GitHub](https://github.com/anthropics/claude-code/issues)
|
||
|
||
---
|
||
|
||
**提示**: 定期运行验证脚本，确保配置始终正确！
|