Claude Code /debug 技能：会话调试与问题排查

什么是 /debug 技能？

/debug 是 Claude Code 的会话调试技能，专门用于排查和解决当前会话中遇到的问题。它可以读取会话调试日志，分析问题原因，帮助你快速恢复正常的开发工作。

核心特性

日志分析：读取并解析会话调试日志
问题诊断：自动识别常见问题模式
解决建议：提供具体的修复建议

基本用法

运行调试技能

/debug

不带参数时，会读取最近的调试日志进行全面分析。

聚焦特定问题

/debug "工具执行失败"
debug "文件读取超时"
debug "网络请求错误"

通过描述问题聚焦分析方向。

工作原理

1. 日志收集

/debug 读取 Claude Code 的调试日志，包括：

会话历史
工具调用记录
错误堆栈
性能指标

2. 问题分析

系统分析日志，识别常见问题模式：

工具执行问题：权限不足、参数错误、超时
上下文问题：Token 限制、内存溢出
网络问题：连接失败、超时
文件问题：路径错误、权限拒绝

3. 建议生成

根据问题类型生成修复建议：

解决步骤
配置调整
命令示例

实际案例

案例 1：工具执行失败

> /debug "Bash tool failed"

分析结果：

问题：Bash 工具执行超时

可能原因：
1. 命令执行时间过长
2. 进程卡住
3. 系统资源不足

建议：
- 使用 timeout 命令限制执行时间
- 检查命令是否陷入死循环
- 尝试分批执行

案例 2：上下文溢出

> /debug

分析结果：

问题：上下文窗口超出限制

最近消息：
- 读取了 50+ 个大文件
- 对话历史过长

建议：
- 使用 /compact 压缩上下文
- 开启自动压缩：settings.json 中设置 autoCompact
- 拆分大型任务为多个小任务

案例 3：MCP 服务器连接失败

> /debug "MCP server error"

分析结果：

问题：MCP 服务器连接失败

检查：
- GitHub MCP: 连接超时
- Database MCP: 认证失败

建议：
- 检查 ~/.claude/settings.json 中的 MCP 配置
- 重新配置认证信息
- 查看服务器日志

日志位置

Claude Code 调试日志的位置：

macOS

~/Library/Logs/Claude/

Linux

~/.local/share/claude/logs/

Windows

%APPDATA%/Claude/logs/

常见问题

Q: /debug 需要网络吗？

不需要，/debug 只分析本地日志。

Q: 日志会保留多久？

默认保留最近 7 天的日志。

Q: 可以导出日志吗？

可以，使用 claude debug --export 导出完整日志。

Q: 隐私问题

调试日志包含会话内容，请注意不要分享包含敏感信息的日志。

总结

/debug 技能是 Claude Code 问题排查的利器：

快速定位：自动分析日志找出问题
智能建议：提供具体解决方案
无需网络：完全本地分析

当你的 Claude Code 会话遇到问题时，首先尝试 /debug！

加载中...