Claude Code 调试与排错完全指南

调试基础：理解 Claude 的思考过程

使用 /think 进行深度思考

当你发现 Claude 的回答不符合预期时，可以用 /think 让它更深入地分析问题：

/think
> 分析 src/utils/auth.ts 的实现逻辑，告诉我 JWT token 验证可能存在哪些安全问题

使用 /compact 减少上下文干扰

如果对话太长，Claude 可能”遗忘”早期信息：

/compact 只保留关于用户认证模块的上下文

---

常见问题分类

1. 权限问题

症状：Claude 无法执行命令

错误：Permission denied

解决方案：

# 查看当前权限设置
claude --permission-mode default

# 临时提升权限
claude --permission-mode auto

或在 .claude/settings.json 中配置：

{
  "permissions": {
    "allow": [
      "Bash(npm:*)",
      "Bash(git:*)",
      "Read",
      "Write",
      "Edit"
    ]
  }
}

症状：无法写入文件

错误：Write operation not permitted

检查 settings.json 中的 allow 列表是否包含 Write。

---

2. 模型理解问题

症状：Claude 理解错误需求

原因： 需求描述不够具体

解决方案：

❌ 修复这个 bug
✅ src/components/Login.tsx 的登录表单在用户名为空时点击登录按钮，
   没有显示错误提示。请添加表单验证，用户名不能为空，
   空的时候在用户名输入框下方显示红色文字提示"请输入用户名"

症状：Claude 总是用同一种方式解决问题

原因： 没有指定约束条件

解决方案：

> 重写这个函数，要求：
> 1. 不使用 any 类型
> 2. 使用箭头函数
> 3. 添加 JSDoc 注释

---

3. 代码生成问题

症状：生成的代码有语法错误

原因： 可能是模型幻觉或上下文污染

解决方案：

1. 让 Claude 先检查

> 先用 tsc --noEmit 检查这个文件有没有类型错误

2. 缩小范围

> 只修改 UserService.ts 中的 login 方法，其他文件不要动

症状：代码风格不一致

原因： 没有 CLAUDE.md 或项目配置

解决方案： 创建 CLAUDE.md

# 代码规范
- 使用单引号
- 使用 2 空格缩进
- 函数声明使用 function 关键字
- 组件使用函数式组件

---

4. 上下文问题

症状：Claude “失忆”了

原因： 上下文太长

解决方案：

/compact 保留当前任务的上下文，移除之前的对话

或者直接开启新会话：

/clear

症状：Claude 重复犯同样的错误

原因： 没有及时纠正

解决方案：

> 等等，我之前说过不要用 var，改用 const/let
> 请撤销上次的修改并用 const 重写

---

5. Git 操作问题

症状：提交信息不规范

解决方案：

创建自定义提交命令：

<!-- .claude/commands/commit.md -->
生成规范的 Git 提交信息。
要求：
1. 使用中文
2. 格式：type: subject
3. type 可选：feat, fix, docs, style, refactor, test
4. subject 不超过 50 字
$ARGUMENTS

症状：误提交敏感信息

解决方案：

> 撤销最近一次提交，但保留代码修改

git reset --soft HEAD~1

---

调试技巧

1. 分步验证

不要让 Claude 一次做太多：

> 第一步：只分析 src/auth/ 目录的结构，告诉我有哪些文件
>
> 确认后
> 第二步：阅读 login.ts 的代码，告诉我登录流程
>
> 确认后
> 第三步：找出可能的 bug
>
> 确认后
> 第四步：修复你认为的 bug

2. 让 Claude 先解释再动手

> 先分析这段代码的逻辑，解释每一步在做什么，然后再修改

3. 限制修改范围

> 只修改函数签名和返回类型，不要动实现逻辑
> 只在 src/utils/ 目录下修改，不要动 src/components/

4. 添加验证步骤

> 修改完成后，运行 npm test 验证是否有回归
> 如果测试失败，告诉我具体哪个测试失败了

---

高级调试技巧

使用 /research 进行深入调查

/research
> 搜索项目中所有使用 console.log 的地方，评估哪些可以改为使用正式的日志库

使用 Agent 进行专项调查

> 用 Explore agent 查找项目中所有的 API 调用，列出所有外部服务依赖

---

常见错误信息

错误信息	原因	解决方案
Tool execution failed	工具执行失败	查看具体错误，可能需要权限
Context limit exceeded	上下文超限	用 /compact 压缩或 /clear 清空
Rate limit exceeded	请求频率超限	等待后重试
Permission denied	权限不足	检查 settings.json
File not found	文件不存在	检查路径是否正确

---

问题排查流程

1. 先看错误信息 - 仔细阅读错误提示
2. 检查权限 - settings.json 配置是否正确
3. 缩小范围 - 让 Claude 只处理相关部分
4. 分步验证 - 每步都确认正确
5. 手动验证 - 关键逻辑自己检查

---

预防措施

1. 写好 CLAUDE.md

这是避免大多数问题的根本：

# 项目配置
- 技术栈：Next.js 14 + TypeScript
- 代码规范：参考 eslint

# 约束
- 不允许使用 any
- 不允许 console.log
- 组件必须添加 prop types

# 工作流
- 每次修改前先阅读现有代码
- 改完运行 tsc --noEmit

2. 及时纠正

发现 Claude 犯错立即指出：

> 不对，之前那个方案有问题，因为...
> 请换一个思路

3. 保持警惕

Claude 不是 100% 可靠的：

• 关键代码要自己 review
• 重要操作前先备份
• 测试一定要跑

---

总结

遇到问题时：

1. 理解错误 - 仔细阅读错误信息
2. 缩小范围 - 让 Claude 只处理相关部分
3. 分步进行 - 每次只做一件事
4. 及时验证 - 每步都检查
5. 不要假设 - 有疑问就问

记住：Claude 是强大的工具，但保持批判性思维很重要！