第 11 期 | Bug 终结者：基于栈追踪 (Stack Trace) 的自动修复 — Claude Code 终极大师课

🎯 学习目标

学完本期你将掌握：

如何将报错信息直接粘贴给 Claude Code 进行自动诊断
Claude 从栈追踪 → 定位文件 → 修改代码 → 二次验证的完整修复闭环
结构化提交 Bug 上下文的最佳实践
多层嵌套错误的系统化排查策略

📖 核心概念讲解

11.1 传统调试 vs Agent 调试

维度	传统调试	Claude Code 调试
流程	看报错 → 搜 Google → 试方案 → 手动改	粘贴报错 → Claude 自动读文件 → 定位根因 → 一键修复
耗时	30 分钟 ~ 数小时	通常 1-3 分钟
知识依赖	需要开发者熟悉框架内部机制	Claude 拥有海量框架知识
二次验证	手动重跑测试	Claude 自动 `npm test` 验证

11.2 Bug 修复的黄金流程

粘贴 Stack Trace
      │
      ▼
Claude 分析调用链(Call Stack)
      │
      ▼
Grep / Read 定位问题文件
      │
      ▼
理解代码上下文
      │
      ▼
Edit 修改代码
      │
      ▼
Bash 重新运行验证(npm test / 重现命令)
      │
      ▼
通过 → 提交修复  ✅
失败 → 进入自愈循环 🔄

11.3 三种常见 Bug 类型

类型 1: 单点错误 (Single Point Failure)
  特征: 栈追踪直接指向出错行
  难度: ⭐ 简单
  示例: TypeError: Cannot read property 'map' of undefined

类型 2: 链式错误 (Chain Error)
  特征: 真正原因在上游，报错在下游
  难度: ⭐⭐⭐ 中等
  示例: API 返回结构变了，导致 5 层深的组件报空指针

类型 3: 幽灵错误 (Phantom Error)
  特征: 只在特定环境或时序下出现
  难度: ⭐⭐⭐⭐⭐ 困难
  示例: Race condition, 热重载导致的状态不一致

💻 模拟 Claude TUI 交互

场景 1：粘贴报错，一键修复

> 运行 npm run dev 后出现以下报错，请修复：
  TypeError: Cannot read properties of undefined (reading 'map')
    at UserList (src/components/UserList.tsx:24:18)
    at renderWithHooks (node_modules/react-dom/...)
    at mountIndeterminateComponent (...)

╭─ Claude ─────────────────────────────────────────────╮
│                                                      │
│  我来分析这个错误。栈追踪显示问题出在                │
│  `UserList.tsx` 第 24 行的 `.map()` 调用。           │
│                                                      │
│  🔍 Tool: Read → src/components/UserList.tsx         │
│                                                      │
│  找到了！第 24 行:                                    │
│  `{users.map(u => <UserCard key={u.id} ... />)}`    │
│                                                      │
│  问题: `users` 在数据还没加载时是 `undefined`，       │
│  而 `.map()` 不能在 `undefined` 上调用。              │
│                                                      │
│  🔍 Tool: Read → src/hooks/useUsers.ts               │
│  这个 Hook 的初始返回值确实没有默认值。               │
│                                                      │
│  ⚙️ Tool: Edit → src/hooks/useUsers.ts               │
│  ╭─ DIFF ────────────────────────────────────╮       │
│  │ - const [users, setUsers] = useState();    │       │
│  │ + const [users, setUsers] = useState([]);  │       │
│  ╰────────────────────────────────────────────╯       │
│                                                      │
│  ⚙️ Tool: Bash                                       │
│  $ npm run dev                                        │
│  ✅ Compiled successfully                             │
│                                                      │
│  ✅ 修复完成。根因是 useState 缺少默认空数组,         │
│  导致初次渲染时 users 为 undefined。                  │
│                                                      │
╰──────────────────────────────────────────────────────╯

场景 2：链式错误的深层追踪

> 部署到生产环境后报 500 错误：
  Error: ENOENT: no such file or directory,
  open '/app/config/secrets.json'
    at Object.openSync (fs.js:498:3)
    at loadConfig (src/config/loader.ts:15:22)
    at initDatabase (src/db/connection.ts:8:18)
    at startServer (src/index.ts:12:3)

╭─ Claude ─────────────────────────────────────────────╮
│                                                      │
│  这是一个链式错误。让我从底向上追踪：                │
│                                                      │
│  📍 层级 1: src/index.ts:12 → startServer()          │
│  📍 层级 2: src/db/connection.ts:8 → initDatabase()  │
│  📍 层级 3: src/config/loader.ts:15 → loadConfig()   │
│  📍 根因: 尝试读取 '/app/config/secrets.json' 失败   │
│                                                      │
│  🔍 Tool: Read → src/config/loader.ts                │
│                                                      │
│  问题找到了！第 15 行硬编码了文件路径:                │
│  `const config = JSON.parse(                         │
│     fs.readFileSync('/app/config/secrets.json'))`     │
│                                                      │
│  在生产环境中，这个路径不存在。应该使用环境变量。     │
│                                                      │
│  ⚙️ Tool: Edit → src/config/loader.ts                │
│  ╭─ DIFF ────────────────────────────────────╮       │
│  │ - const configPath =                       │       │
│  │ -   '/app/config/secrets.json';            │       │
│  │ + const configPath =                       │       │
│  │ +   process.env.CONFIG_PATH               │       │
│  │ +   || path.join(__dirname,               │       │
│  │ +     '../../config/secrets.json');        │       │
│  ╰────────────────────────────────────────────╯       │
│                                                      │
│  ⚙️ Tool: Read → Dockerfile                          │
│  ⚙️ Tool: Edit → Dockerfile                          │
│  添加: ENV CONFIG_PATH=/etc/app/secrets.json         │
│                                                      │
│  ✅ 修复完成。现在支持通过环境变量配置路径,           │
│  同时保留了本地开发的默认值。                         │
│                                                      │
╰──────────────────────────────────────────────────────╯

💻 代码演示：高效 Bug 调试技巧

# ✅ 策略 1: 直接粘贴完整报错
claude "运行 pytest 后报以下错误，请修复: [粘贴报错]"

# ✅ 策略 2: 管道传输错误日志
npm test 2>&1 | claude -p "分析以下测试失败并修复"

# ✅ 策略 3: 带上下文的 Bug 报告
claude "这个 Bug 只在用户未登录时出现:
  1. 访问 /dashboard
  2. 看到白屏
  3. 控制台报错: [粘贴报错]
  请修复"

# ✅ 策略 4: 自愈循环（Print Mode）
claude -p "运行 npm test，如果有失败就修复，
  反复执行直到所有测试通过"

给 Claude 提供好的 Bug 上下文模板

# 在 CLAUDE.md 中加入调试指南
cat >> CLAUDE.md << 'EOF'

## Bug 修复协议
收到 Bug 报告时:
1. 先用 `Read` 定位栈追踪提到的所有文件
2. 用 `Grep` 搜索相关的变量名或函数名
3. 修复后必须运行 `npm test` 验证
4. 如果测试不通过，进入自愈循环（最多 5 次）
5. 输出修复摘要：根因、修改文件、验证结果
EOF

🔧 涉及的 Tools

工具	调试阶段	作用
`Read`	定位	读取栈追踪中提到的源文件
`Grep`	搜索	在代码库中搜索相关函数或变量
`Edit`	修复	修改源代码中的 Bug
`Bash`	验证	运行测试命令验证修复
`Glob`	发现	查找相关的配置/依赖文件

📝 本期要点回顾

粘贴完整 Stack Trace 是最高效的 Bug 报告方式
Claude 遵循 分析 → 定位 → 修复 → 验证 的自动闭环
链式错误需要 从底向上 追踪调用链
使用 管道传输 可以将终端错误直接传给 Claude
在 CLAUDE.md 中配置 Bug 修复协议 能显著提高修复准确率

第 11 期 | Bug 终结者：基于栈追踪 (Stack Trace) 的自动修复

🎯 学习目标

📖 核心概念讲解

11.1 传统调试 vs Agent 调试

11.2 Bug 修复的黄金流程

11.3 三种常见 Bug 类型

💻 模拟 Claude TUI 交互

场景 1：粘贴报错，一键修复

场景 2：链式错误的深层追踪

💻 代码演示：高效 Bug 调试技巧

给 Claude 提供好的 Bug 上下文模板

🔧 涉及的 Tools

📝 本期要点回顾

🔗 参考资料