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

---

**提示**: 定期运行验证脚本，确保配置始终正确！
