Project Init
🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Yaojia Wang
405
.claude/verify-agents.md
Normal file
405
.claude/verify-agents.md
Normal file
@@ -0,0 +1,405 @@
|
||||
# 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)
|
||||
|
||||
---
|
||||
|
||||
**提示**: 定期运行验证脚本，确保配置始终正确！
|
||||
Reference in New Issue
Block a user