# 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) --- **提示**: 定期运行验证脚本，确保配置始终正确！