12. 调试与排错

调试的原则

来自 superpowers:systematic-debugging Skill 的核心思想:

先找根因,再动手修。 不理解为什么出错就改代码,等于在随机游走。

Claude Code 常见问题分类

1. 安装/环境问题

症状:claude: command not found

排查步骤:

  1. 确认 ~/.npm-global/bin 或 ~/.local/bin 在 PATH 
    echo $PATH | tr ':' '\n' | grep -E '(npm|local)/bin'
  2. macOS 用 ~/.zshrc,Linux 用 ~/.bashrc,加入: 
    export PATH="$HOME/.local/bin:$PATH"
  3. 重启终端

症状:中文乱码

export LANG=en_US.UTF-8
export LC_ALL=en_US.UTF-8

症状:API Key 无效

  1. 检查 Key 前后没有多余空格
  2. 确认账号余额
  3. 看 ~/.claude/logs/ 下日志

2. 工具调用问题

Claude 不读某个文件

> 请用 Read 工具读 ./src/main.py

显式指明工具,别假设它会自动用。

Claude 改了不该改的文件

在 CLAUDE.md 里明确:

# 项目约束
- 不要修改 docs/ 目录
- 不要修改 tests/ 目录
- 改完后必须跑 npm test

或者在对话中说:

> 只改 src/ 目录,其他目录都不要碰

命令执行失败

Claude 会把错误贴出来。常见原因:

  • 缺依赖 → 让它跑 npm install / pip install
  • 权限不足 → 用 sudo 或换用户
  • 网络问题 → 配置代理

3. Skill 相关问题

Skill 没自动触发

排查:

  1. description 写得够具体吗?(用关键词,不要泛泛)
  2. 用户的提问里有触发关键词吗?
  3. 重启 Claude Code——新加的 Skill 需重启生效

Skill 触发错了

description 太宽泛,会被误触发。改窄:

# 之前(太宽)
description: Helps with Python

# 之后(更准)
description: Use when refactoring legacy Python 2 code to Python 3 - applies 2to3 patterns and identifies print statements, xrange, and unicode literals

4. MCP 相关问题

MCP Server 启动失败

# 手动跑一遍,看错误
npx -y @modelcontextprotocol/server-postgres "postgresql://..."

常见原因:

  • 包没装 → npm install -g
  • 路径不对 → 检查 .mcp.json 的 command 和 args
  • Token 无效 → 检查 env

Claude 看不到 MCP 工具

  1. 配置文件位置对吗?(用户级 ~/.claude/mcp.json 或项目级 .mcp.json)
  2. 重启 Claude Code
  3. 用 /mcp 命令查看当前已加载的 MCP Server

5. Workflow 相关问题

Agent 输出不符合 Schema

不要让它自动重试。先看原始输出哪里不对:

const raw = await agent(...)
console.log('RAW:', raw)

调整方法:

  • Schema 太严格 → 放宽
  • Prompt 不清楚 → 加示例
  • 输出格式描述缺失 → 在 prompt 里给示例

Workflow 跑一半卡住

排查:

  1. 看 log() 输出,卡在哪一阶段
  2. 单独跑那个阶段的 agent,看输出
  3. 检查是不是网络/token 问题

Token 暴增

  • 检查有没有把大文件全文塞给 Agent
  • 用 /compact 压缩
  • 拆分任务

调试工作流

步骤 1:复现

写一个最小的复现 case。能不能用 1 行命令触发?

步骤 2:定位

  • 哪一步开始出错?
  • 是工具调用失败,还是 AI 决策出错?
  • 输入是什么?输出是什么?

步骤 3:假设 + 验证

不要瞎猜。列出可能原因,逐个排除。

步骤 4:修

修的时候只改一处。改完跑测试。

步骤 5:防回归

加个测试,或者写进 CLAUDE.md,防止以后再犯。

调试时的 prompt 技巧

让它自我诊断

这个命令失败了,列出 3 个最可能的原因,以及如何验证。

让它读错误信息

仔细读错误堆栈,告诉我错误是从哪一行抛出来的、根本原因是什么。

让它做对照实验

把这个变量从 A 改成 B,跑一遍,把两次输出对比给我。

何时升级求助

  • 重装 Claude Code 仍然同样的问题
  • 怀疑是 API 服务本身的问题
  • 涉及数据丢失风险

去官方 Discord / GitHub Issues / 文档查。

给教师的实用建议

  1. 教学场景慎用 bypassPermissions——学生用可能误删文件
  2. 配置 Git 自动 commit——Claude 改完自动提交,出问题能回滚
  3. 重要操作前备份——尤其在帮学生改项目代码时
  4. 保留日志——~/.claude/logs/ 可能有用

下一步