name: claude-code-debug description: “对Claude Code扩展和行为的故障排除。触发条件：调试、故障排除、不工作、技能未加载、钩子未运行、代理未找到。” compatibility: “Claude Code CLI” allowed-tools: “Bash Read” depends-on: [] related-skills: [claude-code-hooks, claude-code-headless, claude-code-templates]

Claude Code 调试

对扩展、钩子和意外行为进行故障排除。

快速诊断

# 启用调试模式
claude --debug

# 检查已加载的扩展
/hooks        # 查看已注册的钩子
/agents       # 查看可用的代理
/memory       # 查看已加载的内存文件
/config       # 查看当前配置

常见问题

症状	快速检查
技能未激活	验证描述中是否包含触发关键词
钩子未运行	检查 `chmod +x`，运行 `/hooks`
代理未委托	在描述中添加“主动使用”
MCP连接失败	使用 `npx` 手动测试服务器
权限被拒绝	检查 settings.json 的允许规则

调试模式输出

claude --debug
# 显示：
# - 钩子执行和错误
# - 技能加载状态
# - 子代理调用
# - 工具权限决策
# - MCP服务器连接

快速修复

技能未加载

# 检查结构
ls -la .claude/skills/my-skill/
# 必须包含：SKILL.md

# 验证YAML前言
head -10 .claude/skills/my-skill/SKILL.md
# 必须以 --- 开始/结束

# 检查名称是否与目录匹配
grep "^name:" .claude/skills/my-skill/SKILL.md

钩子未执行

# 设置为可执行
chmod +x .claude/hooks/my-hook.sh

# 手动测试
echo '{"tool_name":"Bash"}' | .claude/hooks/my-hook.sh
echo $?  # 检查退出代码

# 验证JSON语法
jq '.' ~/.claude/settings.json

代理未被使用

# 检查文件位置
ls ~/.claude/agents/
ls .claude/agents/

# 验证描述是否包含“用于：”或“主动使用”
grep -i "使用" agents/my-agent.md | head -5

# 显式请求
# “使用my-agent代理来分析这个”

验证

# 运行所有验证
just test

# 仅YAML验证
just validate-yaml

# 仅名称匹配验证
just validate-names

官方文档

https://code.claude.com/docs/en/hooks - 钩子参考
https://code.claude.com/docs/en/skills - 技能参考
https://code.claude.com/docs/en/sub-agents - 自定义子代理
https://code.claude.com/docs/en/settings - 设置配置

额外资源

./references/common-issues.md - 问题 → 解决方案查找表
./references/debug-commands.md - 所有检查命令
./references/troubleshooting-flow.md - 决策树

另请参阅： claude-code-hooks 用于钩子调试，claude-code-templates 用于正确结构