claude-code-debug

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Claude Code Debug

Claude Code 调试

Troubleshoot extensions, hooks, and unexpected behavior.

排查扩展、Hook及异常运行问题。

Quick Diagnostics

快速诊断

bash

undefined

bash

undefined

Enable debug mode

启用调试模式

claude --debug

Check loaded extensions

查看已加载的扩展

/hooks # View registered hooks /agents # View available agents /memory # View loaded memory files /config # View current configuration

undefined

/hooks # 查看已注册的Hook /agents # 查看可用的Agent /memory # 查看已加载的内存文件 /config # 查看当前配置

undefined

Common Issues

常见问题

Symptom	Quick Check
Skill not activating	Verify description has trigger keywords
Hook not running	Check `chmod +x` , run `/hooks`
Agent not delegating	Add "Use proactively" to description
MCP connection fails	Test server manually with `npx`
Permission denied	Check settings.json allow rules

症状	快速检查项
Skill未激活	确认描述中包含触发关键词
Hook未运行	检查 `chmod +x` 权限，运行 `/hooks` 命令
Agent未执行委托	在描述中添加“主动使用”（Use proactively）
MCP连接失败	使用 `npx` 手动测试服务器
权限被拒绝	检查settings.json中的允许规则

Debug Mode Output

调试模式输出

bash

claude --debug

bash

claude --debug

Shows:

显示内容包括：

- Hook execution and errors

- Hook执行情况及错误

- Skill loading status

- Skill加载状态

- Subagent invocations

- 子Agent调用情况

- Tool permission decisions

- 工具权限决策

- MCP server connections

- MCP服务器连接状态

undefined

undefined

Quick Fixes

快速修复

Skill Not Loading

Skill未加载

bash

undefined

bash

undefined

Check structure

检查结构

ls -la .claude/skills/my-skill/

Must have: SKILL.md

必须包含：SKILL.md

Verify YAML frontmatter

验证YAML前置元数据

head -10 .claude/skills/my-skill/SKILL.md

Must start/end with ---

必须以---开头和结尾

Check name matches directory

检查名称与目录是否匹配

grep "^name:" .claude/skills/my-skill/SKILL.md

undefined

grep "^name:" .claude/skills/my-skill/SKILL.md

undefined

Hook Not Executing

Hook未执行

bash

undefined

bash

undefined

Make executable

设置可执行权限

chmod +x .claude/hooks/my-hook.sh

Test manually

手动测试

echo '{"tool_name":"Bash"}' | .claude/hooks/my-hook.sh echo $? # Check exit code

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

Verify JSON syntax

验证JSON语法

jq '.' ~/.claude/settings.json

undefined

jq '.' ~/.claude/settings.json

undefined

Agent Not Being Used

Agent未被使用

bash

undefined

bash

undefined

Check file location

检查文件位置

ls ~/.claude/agents/ ls .claude/agents/

Verify description includes "Use for:" or "Use proactively"

确认描述中包含"Use for:"或"Use proactively"

grep -i "use" agents/my-agent.md | head -5

Explicitly request

明确请求

"Use the my-agent agent to analyze this"

undefined

undefined

Validation

验证

bash

undefined

bash

undefined

Run all validations

运行所有验证

just test

YAML validation only

仅验证YAML

just validate-yaml

Name matching only

仅验证名称匹配

just validate-names

undefined

just validate-names

undefined

Official Documentation

官方文档

https://code.claude.com/docs/en/hooks - Hooks reference
https://code.claude.com/docs/en/skills - Skills reference
https://code.claude.com/docs/en/sub-agents - Custom subagents
https://code.claude.com/docs/en/settings - Settings configuration

https://code.claude.com/docs/en/hooks - Hook参考文档
https://code.claude.com/docs/en/skills - Skill参考文档
https://code.claude.com/docs/en/sub-agents - 自定义子Agent文档
https://code.claude.com/docs/en/settings - 配置设置文档

Additional Resources

额外资源

```
./references/common-issues.md
```
- Issue → Solution lookup table
```
./references/debug-commands.md
```
- All inspection commands
```
./references/troubleshooting-flow.md
```
- Decision tree

See Also:

claude-code-hooks

for hook debugging,

claude-code-templates

for correct structure

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

另请参阅：

claude-code-hooks

用于Hook调试，

claude-code-templates

用于获取正确的结构