ColaFlow/.claude/verify-agents.md

Agent 配置验证清单

本文档帮助你验证 Claude Code agent 配置是否正确。

自动检查清单

1. 文件结构检查

# 检查 .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 检查

对每个文件，确认包含以下内容：

---
name: agent-name          # 必须：小写+连字符
description: ...          # 必须：清晰描述
tools: ...                # 可选：工具列表
model: inherit            # 可选：模型配置
---

快速验证命令

# 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: 字段：

# 检查所有 name 字段
grep "^name:" .claude/agents/*.md

---

4. Description 字段检查

要求: 清晰描述 agent 的用途和使用场景

✅ 好的 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"

❌ 不好的 description:

description: Research agent  # 太简单
description: Does stuff       # 不明确

验证方法

# 查看所有 description
grep "^description:" .claude/agents/*.md

---

5. Tools 字段检查

可选字段: 省略则继承所有工具

选项A: 省略 tools（推荐）

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

选项B: 明确指定 tools

---
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 的系统提示内容

示例检查模板

# ✅ 检查 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)

# 验证所有 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)

#!/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 官方文档
   • ClaudeLog - Custom Agents

3. 检查 GitHub Issues:

   • Claude Code GitHub

---

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