32 篇博文 含有标签「debugging」

你正在值班，凌晨三点，告警触发：过去一小时内 AI 聊天功能的用户满意度下降了 18%。你打开日志，却看到……什么都没有。每个请求都返回了 HTTP 200，延迟正常，没有任何报错。

这就是 AI 事故的体验。传统值班的肌肉记忆——grep 堆栈跟踪、找到异常、部署修复——在这里完全失效。系统并没有崩溃，它做的正是它被设计来做的事。只是输出结果是错的。

一家金融科技初创公司在他们的系统提示词中添加了一个逗号。第二天，他们的发票生成机器人开始输出乱码，在有人追踪到原因之前，他们已经损失了 8,500 美元。没有抛出任何错误。没有触发任何报警。应用程序继续运行，虽然错了但很自信。

这就是在生产环境中调试 LLM 的真实样子。没有指向行号的堆栈追踪。没有你可以检查的核心转储（core dump）。系统不会崩溃——它在继续运行的同时，悄无声息地产生降级的输出。传统的调试直觉不再适用。大多数工程师的反应是随机调整提示词，直到看起来好一点，然后基于三个示例进行部署，并称其已修复。结果两周后，问题又以另一种形式浮出水面。

有一种更好的方法。LLM 的故障遵循系统性的模式，而这些模式对结构化的调查有反应。这就是这套方法论。

周一早上，一张工单传了过来：你负责的 AI 功能的用户满意度在周末下降了 18%。你打开部署日志，心里一沉。周五的发布包含了来自供应商的模型版本升级、产品团队的提示词（prompt）优化、内容审核后的检索语料库（retrieval corpus）刷新，以及因 API 字段重命名而进行的工具架构（tool schema）更新。四个变更。一次回退。完全不知道该归咎于哪个变量。

这就是多变量回归问题（multi-variable regression problem），它是生产环境 AI 系统中最难处理的一类故障。倒不是因为这种故障有多罕见——行为回退（behavioral regressions）时有发生——而是因为当团队快速迭代时，产生这种问题的条件几乎是必然的。那些看起来单独都很安全的变更堆积在一起，同时发布，最后让你在黑暗中摸索着进行调试。

你的智能体在开发环境中运行得完美无缺。它能回答测试查询、调用正确的工具、产出干净的输出。然后它上了生产环境，在一个十二步工作流的第七步出了问题。日志显示最终输出是一堆垃圾，但你完全不知道为什么。

你开始加打印语句。你在编排代码中到处散布 logger.debug() 调用。你盯着成千上万行输出，然后意识到你在用单进程的工具调试一个分布式系统。这就是大多数团队在 AI 智能体上犯的根本错误——他们把智能体当作程序来对待，但智能体的行为更像分布式系统。

你的 Agent 上周二在生产环境出了故障。一个客户报告了错误的回答。你调出日志，看到最终输出，也许还有几条中间的 print 语句——然后你就卡住了。你无法重新运行 Agent 来重现同样的故障，因为模型不会产生相同的 token，你的工具调用的 API 现在返回了不同的数据，嵌入在提示词中的时间戳也已经变了。Bug 消失了，你只能盯着间接证据发呆。

这就是 AI Agent 的根本调试问题：传统软件是确定性的，所以你可以通过重建输入来复现 bug。Agent 系统不是。每次运行都是模型采样、实时 API 响应和时间依赖状态的独特组合。没有专门的工具，事后调试就变成了取证猜测。

确定性重放通过在执行过程中记录每个非确定性来源，并在重放时替换这些记录来解决这个问题——把你无法复现的 Agent 运行变成你可以像调试器一样逐步跟踪的东西。

三个智能体并发处理同一个客户账户更新。三者都记录了成功。最终数据库状态同时出现了三处错误，且始终没有抛出任何异常。团队花了两周时间怪罪模型。

问题不在模型。是竞态条件。

这是生产环境多智能体系统中被误诊次数最多的故障模式：由并发状态访问引发的数据损坏，因为下游智能体会基于损坏的输入自信地进行推理，从而被误认为是幻觉。模型并没有在编造内容，它只是在忠实地处理垃圾数据。

当 AI Agent 在生产环境中失败时，你很少能准确知道它是何时出错的。你看到的只是最终输出——一个幻觉答案、一个跳过的步骤，或者一个参数错误的工具调用——但实际的失败可能发生在三个步骤之前。这是软件工程尚未解决的核心调试问题：Agent 以一系列决策的形式执行，当你意识到出问题时，证据已经埋藏在交织的 LLM 调用、工具调用和状态变更的长轨迹中。

传统的调试假设确定性。你可以重现 bug，设置断点，检查状态。Agent 调试同时打破了这三个假设。相同的输入可以产生不同的执行路径。重现失败需要捕获发生那一刻的精确上下文、模型温度和外部状态。而且在实时推理循环中“设置断点”甚至不是大多数 Agent 框架所支持的功能。

人工智能编程助手已经从简单的代码补全工具进化为成熟的开发伙伴。Claude Code 代表了这一演进的下一个阶段，它提供了一个可被称为**“自主编程”**的框架。这款工具旨在深度集成到你的工作流中，做很多之前 AI coding 做不到的事情：

• 代码理解与问答： 充当项目专家，为新团队成员讲解大型代码库的运作方式，极具价值。
• 大规模重构： 擅长修改庞大文件（例如超过 18,000 行），凭借其对全局代码关系的理解，在其他 AI 工具束手无策时依然表现出色。
• 调试： 提供逐步推理过程，助你找到错误的根本原因，而非像其他工具那样只给出修复方案却无从解释。
• 复杂功能生成： 遵循 “探索 → 计划 → 实现” 的工作流。你可以引导它先分析问题并制定详细计划，然后再编写代码。
• 测试驱动开发 (TDD)： 可以指导它先编写失败的测试用例，然后生成能让测试通过的最精简代码，从而显著加速 TDD 循环。

接下来，让我们深入探索这些能助你驾驭其强大功能的技巧。

1. 基础设置：工作流的核心​

坚实的配置是高效工作流的基石。在这一步投入的时间，将在后续的每一次交互中为你带来丰厚的回报。

• 使用 CLAUDE.md 作为项目记忆：在任何项目的根目录下，都应该有一个简洁的 CLAUDE.md 文件。该文件充当项目的“短期记忆”，包含了关键的架构原则、编码规范和测试流程。为了保持文件简洁、重点突出，可以使用 imports 语法（如 @docs/testing.md）来引用更详细的文档。你可以通过以 # 开头的消息快速添加新规则，或使用 /memory 命令直接编辑这份记忆。
• Monorepo 感知：现代开发常常涉及 Monorepo。为了让 Claude 能够访问多个包以进行跨目录分析和重构，可以使用 --add-dir 标志，或在你的 .claude/settings.json 文件中定义 additionalDirectories。这对于跨越代码库多个部分的任务至关重要。
• 键盘与终端快捷操作：速度至关重要。掌握快捷键可以简化你的交互流程。使用 Esc Esc 快速编辑上一条消息。运行一次 /terminal-setup 命令，即可启用 Shift+Enter 来输入换行符。对于 Vim 爱好者，/vim 命令可以让你在熟悉的 Vim 模式下进行编辑。

2. 优化日常工作流​

有了坚实的基础，你就可以引入一些实践来减少阻力，提升日常工作效率。

使用正确的模式​

CLI 提供了几种权限模式，以适应不同的任务和风险偏好：

• default：最安全的新手起点。在执行有潜在风险的操作前，它会提示你进行确认，在安全和速度之间取得了良好平衡。
• acceptEdits：一种“实时编码”模式，它会自动接受文件编辑而无需提示。非常适合快速迭代以及在你密切监督流程的场景。
• plan：一种为代码审查等任务设计的“安全”模式。在此模式下，Claude 可以分析和讨论代码，但不能修改任何文件。
• bypassPermissions：完全跳过所有权限提示。请极其谨慎地使用此模式，并且只在意外更改不会造成任何后果的沙盒环境中使用。

你可以在 .claude/settings.json 中设置默认模式，或使用 --permission-mode 标志为单次会话指定模式。

斜杠命令与自定义​

重复性任务是自动化的绝佳候选。通过创建自定义斜杠命令，将你最常用的提示词转化为可复用的工具。只需将它们作为带有 YAML frontmatter 的 Markdown 文件存储在 .claude/commands/ 目录中即可。

• 在 frontmatter 中使用 allowed-tools 来限制命令可以执行的操作，增加一层安全性。
• 使用 ! 前缀可以运行 shell 命令（例如 !git status -sb），并将其输出直接注入到你的提示词上下文中。
• 使用 $ARGUMENTS 向你的命令传递参数，使其更加灵活和强大。

恢复会话与并行工作​

• claude --continue：立即跳回到你最近一次的会话中。
• claude --resume：列出过去的所有会话，让你能精确地从上次中断的地方继续。
• Git worktrees：对于大规模重构，可以使用 git worktree 创建隔离的分支。这允许你并行运行多个独立的 Claude 会话，每个会话都有自己的上下文，从而避免混淆和冲突。

用于协作的输出风格​

• /output-style explanatory：在响应中增加一个“洞察 (Insights)”部分，非常适合用于指导初级开发者或在 Pull Request 中解释复杂的变更。
• /output-style learning：在响应中添加 TODO(human) 占位符，主动邀请你参与协作，填补空白。

3. 集成质量与安全保障​

真正的自主需要有护栏。将质量检查和安全网直接集成到你的工作流中，让你能充满信心地进行开发。

使用钩子 (Hooks) 作为安全护栏​

钩子是在特定生命周期事件中自动运行的 shell 命令，提供了一种确定性的方式来强制执行规则。你可以在 .claude/settings.json 中配置它们。

• PreToolUse：在工具使用前运行检查。例如，你可以阻止对敏感文件的编辑，或要求必须存在相应的测试文件才允许写入操作。
• PostToolUse：在工具使用后自动执行清理任务。这非常适合在每次编辑后运行 prettier 或 gofmt 等格式化工具，以及代码检查器和快速测试。
• Notification：当 Claude 需要你输入时发送桌面提醒，这样你就可以在切换任务的同时不会忘记这边的进度。

例如，让 Mac 在任务完成后通知你 - code ~/.claude/settings.json

{
 "hooks": {
      "Stop": [
        {
          "hooks": [
            {
              "type": "command",
              "command": "say \"job's done!\""
            }
          ]
        }
      ]
    }
}

权限与安全​

在你的设置中定义明确的 allow（允许）、ask（询问）和 deny（拒绝）规则，以便在无需频繁提示的情况下管理工具的访问权限。

• Allow：安全、常规的操作，如 Bash(npm run test:*)。
• Ask：你希望手动批准的有潜在风险的操作，如 Bash(git push:*)。
• Deny：用于防止灾难性后果的关键安全规则，如 Read(./.env) 或 Read(./secrets/**)。

专家子智能体 (Subagents)​

对于复杂的项目，你可以定义具有特定角色的项目级智能体，例如 code-reviewer（代码审查员）、test-runner（测试运行器）或 debugger（调试器）。每个智能体都配置了有限的工具集，以防止其越权操作。Claude 可以自动将任务委派给合适的智能体，你也可以明确地调用某个智能体。可以参考这个仓库获取示例。

4. 高级工作流与集成​

通过集成视觉上下文和外部服务，超越基本的文件访问，提升你的工作流。

通过截图和图片提供视觉上下文​

一图胜千言，尤其是在调试 UI 问题时。有三种可靠的方法可以向 Claude Code 提供图片：

1. 从剪贴板粘贴：将截图复制到剪贴板，然后直接用 Ctrl+V 粘贴到终端中（注意：在 macOS 上也是 Ctrl+V，而不是 Cmd+V）。
2. 拖放：将图片文件（PNG, JPEG, GIF, WebP）从你的文件管理器直接拖到 CLI 窗口中。
3. 引用文件路径：在你的提示词中直接包含本地文件路径即可，例如：分析这张截图：/path/to/screenshot.png。

模型上下文协议 (MCP) 集成​

MCP 使 Claude 能够连接到 Jira、GitHub、Notion 或 Sentry 等外部服务。在添加并认证一个 MCP 服务器后，你就可以在提示词中直接引用外部资源，例如 实现 JIRA-ENG-4521 中描述的功能。

非交互式使用与 CI/CD 集成​

对于自动化和脚本编写，可以使用带 -p 标志的打印模式。

• 将其与 --output-format json 或 --output-format stream-json 结合使用，可以生成机器可读的输出，然后通过管道传递给 jq 等其他工具进行进一步处理。
• 使用 --max-turns 为交互次数设置硬性上限，防止自动化脚本中出现失控循环。

5. 成本与性能优化​

强大的模型需要明智地使用。养成这些习惯，以管理你的开销并优化性能。

• 关注开销：随时使用 /cost 命令，获取当前会话成本的实时摘要。
• 有策略地选择模型：使用像 Opus 这样最强大的模型进行高层规划、复杂推理和初步策略制定。然后，切换到像 Sonnet 或 Haiku 这样更快、更经济的模型来执行实现、测试和其他常规任务。
• 状态行：一个流行的社区技巧是在终端添加一个自定义状态行，用于显示实时成本和当前 Git 分支等其他有用信息。ccusage 工具是实现此功能的常用选择。

6. 入门套件：开箱即用的配置​

这里提供了一些可直接复制粘贴的配置文件，助你快速上手。

.claude/settings.json (项目共享)​

此文件用于建立项目范围的权限、钩子和 monorepo 设置。

{
  "defaultMode": "acceptEdits",
  "permissions": {
    "allow": [
      "Read(**/*)",
      "Edit(src/**)",
      "Bash(npm run test:*)",
      "Bash(npm run lint:*)",
      "Bash(go test:*)",
      "Bash(git status:*)",
      "Bash(git diff:*)"
    ],
    "ask": [
      "Bash(git push:*)",
      "Bash(pnpm publish:*)",
      "Bash(npm publish:*)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ],
    "additionalDirectories": ["../apps", "../packages", "../services"]
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|MultiEdit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "python3 - <<'PY'\nimport json,sys\np=json.load(sys.stdin).get('tool_input',{}).get('file_path','')\nblock=['.env','/secrets/','.git/']\nsys.exit(2 if any(b in p for b in block) else 0)\nPY"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|MultiEdit|Write",
        "hooks": [
          { "type": "command", "command": "npx prettier --write . --loglevel silent || true" },
          { "type": "command", "command": "npm run -s lint || true" },
          { "type": "command", "command": "npm run -s test || true" }
        ]
      }
    ],
    "Notification": [
      { "matcher": "", "hooks": [ { "type": "command", "command": "command -v terminal-notifier >/dev/null && terminal-notifier -message 'Claude needs input' -title 'Claude Code' || true" } ] }
    ]
  },
  "statusLine": { "type": "command", "command": "~/.claude/statusline.sh" }
}

.claude/commands/commit.md​

这个自定义命令利用 shell 输出起草一条符合 Conventional Commit 规范的消息。

allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*)
description: Create a conventional commit from current changes

## Context
- Status: !`git status -sb`
- Diff:   !`git diff --staged; git diff`

## Task
Write a Conventional Commit subject (<= 72 chars) and a concise body.
Call out BREAKING CHANGE if needed. Stage relevant files and commit.

.claude/agents/code-reviewer.md​

一个专门负责代码审查的智能体定义。

name: code-reviewer
description: Senior review with focus on correctness, security, tests, readability, performance.
tools: Read, Grep, Glob, Bash

Return a checklist grouped by **Critical**, **Warnings**, and **Suggestions**.
Propose minimal patches where possible. Include test guidance for each critical item.

CLAUDE.md (Memory)​

一个定义了工作风格、质量标准和关键项目文档的示例记忆文件。

# Working style
- Start in **Plan mode**; outline approach, tests, and risks. Wait for approval.
- Execute in **small, reversible steps**; propose staged commits with diffs.
- Place generated docs in `docs/ai/`. Avoid ad-hoc files elsewhere.

# Code quality
- Prefer pure functions and dependency injection.
- JS/TS: strict TS, eslint + prettier; tests via vitest/jest.
- Go: table-driven tests; `gofmt`/`golangci-lint`.
- Security: never read `.env*` or `./secrets/**`; do not write tokens to disk.

# Project map
@README.md
@docs/architecture.md
@docs/testing.md

7. 问题排查与总结​

• 图片粘贴问题：如果从剪贴板粘贴不起作用（在某些 Linux 终端上很常见），请转而使用可靠的拖放或文件路径方法。
• 过于激进的编辑：在日常工作流中，避免使用 bypassPermissions 模式（通过 claude --dangerously-skip-permissions 启动）。更好的方法是使用 acceptEdits 模式，并结合明确定义的 allow/ask/deny 规则。在合并前，务必审查所有差异。
• 记忆膨胀：如果你发现 Claude 开始遗漏指令，可能是你的 CLAUDE.md 文件变得太大了。可以通过将细节移至导入的文档文件中来缩短它。你也可以在会话期间重申关键规则以重新聚焦，或使用 /compact 命令清理会话历史。

Claude Code 不仅仅是一个代码生成器，它是一个用于构建高效的、AI 增强开发流程的平台。通过超越基础的提示词并采纳这些中高级技巧，你可以建立一个更快、更安全、更具协作性的工作流。大胆尝试这些功能，根据你的项目进行调整，并探索软件开发的新范式吧。