Claude Code 不总是按照你的预期工作。它会误解需求、执行失败、陷入循环、输出质量不稳定。这篇文章教你一套系统化的调试方法，让 Agent 真正"听话"。

一、为什么 Agent 会"不听话"？

1.1 一个真实的崩溃场景

你花10分钟写了一个复杂需求：

帮我重构这个项目的认证模块，用 JWT 替换 session，要支持刷新 token，还要兼容现有的中间件...

Claude Code 开始执行，然后：

• 第1次：改错了文件
• 第2次：改对了文件，但忘了处理刷新逻辑
• 第3次：加了刷新逻辑，但测试全挂了
• 第4次：你忍不住了，自己上手改

为什么会这样？

1.2 "不听话"的六种类型

二、调试循环：问题 → 诊断 → 修复 → 验证

调试 Agent 就像调试代码一样，需要系统化的方法。

2.1 四步调试法

2.2 一个完整的调试案例

场景：你让 Claude Code 添加一个登录功能，但它改错了文件。

问题：

• 它做了：修改了 auth.service.ts
• 我预期：修改 auth.controller.ts

诊断：

• 问 Claude："你为什么选择修改 auth.service.ts？"
• Claude 回答："因为文件名包含 auth，我以为是入口文件"
• 根本原因：没说清楚"入口文件"是哪个

修复：

• 原需求："添加登录功能"
• 改进需求："在 src/controllers/auth.controller.ts 添加登录接口"

验证：

• 再次执行，确认修改了正确的文件

三、问题诊断方法

3.1 检查原始需求

最常见的问题根源：需求不够具体。

3.2 查看执行日志

Claude Code 会显示每一步操作：