debugging

模式：认知／提示词驱动——没有独立的实用脚本；在 Agent 上下文中使用。

系统化调试

概述

随机修复会浪费时间并引入新 bug。快速打补丁会掩盖根本问题。

核心原则： 始终先找到根本原因，再尝试修复。只修复症状等于失败。

违背流程的字面要求，就是违背调试的本意。

铁律

1. 绝不在完成第 1 阶段的根本原因调查前提出或实施修复——没有根本原因依据的修复只是猜测，最终会失败或引入新 bug。
2. 务必在调试前可靠地复现 bug——如果无法稳定复现，你调试的就不是真正的问题。
3. 绝不在验证假设时一次做出多项更改——同时进行多项更改，就无法确定是哪项更改解决了问题。
4. 务必在修复尝试失败 3 次后停下来审视架构——如果每次修复都暴露出新问题，问题就在架构，而非症状。
5. 绝不在实施修复前跳过创建失败测试用例的步骤——没有测试，就无法验证修复是否有效，也无法确认它不会导致回归。

适用场景

适用场景

任何技术问题都适用：

• 测试失败
• 生产环境中的 bug
• 意外行为
• 性能问题
• 构建失败
• 集成问题

尤其适用于以下情况：

• 时间紧迫（紧急情况容易让人想要猜测）
• “只需快速修一下”看起来显而易见
• 你已经尝试过多种修复方法
• 之前的修复不起作用
• 你还没有完全理解问题

不要在以下情况下跳过：

• 问题看起来很简单（简单的 bug 也有根本原因）
• 你很赶时间（仓促行事必然导致返工）
• 经理要求立即修复（系统化调试比反复试错更快）

何时使用：debugging 还是 smart-debug

场景	使用 debugging	使用 smart-debug
简单、可在本地复现的 bug	是	小题大做
已知根本原因所在区域	是	可选
静态分析／代码审查发现的 bug	是	否
运行时／生产环境问题	从这里开始	首选
间歇性／难以复现的问题	升级处理	是
需要假设排序门槛	否	是（阻塞式）
需要插桩和日志分析	否	是
由可观测性驱动（跟踪、APM）	否	是

经验法则：对于直接明了的 bug，从 debugging 开始。当需要对假设排序、进行结构化插桩，或 bug 只会间歇性出现／仅出现在生产环境时，升级到 smart-debug。

另请参阅：.claude/skills/smart-debug/SKILL.md

四个阶段

必须完成每个阶段后，才能进入下一阶段。

阶段 1：根因调查

在尝试任何修复之前：

1. 仔细阅读错误消息

   • 不要跳过错误或警告
   • 它们通常包含确切的解决方案
   • 完整阅读堆栈跟踪
   • 记录行号、文件路径和错误代码

2. 稳定地重现问题

   • 能否可靠地触发问题？
   • 具体步骤是什么？
   • 每次都会发生吗？
   • 如果无法重现，就收集更多数据，不要猜测

3. 检查近期更改

   • 哪些更改可能导致了这个问题？
   • Git diff、近期提交
   • 新增的依赖项、配置更改
   • 环境差异

4. 在多组件系统中收集证据

   当系统包含多个组件时（CI - 构建 - 签名、API - 服务 - 数据库）：

   提出修复方案之前，先添加诊断检测：

   For EACH component boundary:
     - Log what data enters component
     - Log what data exits component
     - Verify environment/config propagation
     - Check state at each layer
   
   Run once to gather evidence showing WHERE it breaks
   THEN analyze evidence to identify failing component
   THEN investigate that specific component
   

   示例（多层系统）：

   # Layer 1: Workflow
   echo "=== Secrets available in workflow: ==="
   echo "IDENTITY: ${IDENTITY:+SET}${IDENTITY:-UNSET}"
   
   # Layer 2: Build script
   echo "=== Env vars in build script: ==="
   env | grep IDENTITY || echo "IDENTITY not in environment"
   
   # Layer 3: Signing script
   echo "=== Keychain state: ==="
   security list-keychains
   security find-identity -v
   
   # Layer 4: Actual signing
   codesign --sign "$IDENTITY" --verbose=4 "$APP"
   

   这可以揭示： 哪一层发生故障（密钥 - 工作流正常，工作流 - 构建失败）

   对于分布式/微服务系统，优先使用 OpenTelemetry 跟踪：

   # Query traces by component (preferred over manual echo/env logging)
   pnpm trace:query --component <service-name> --event <event-name> --since <ISO-8601> --limit 200
   
   # When trace ID is already known
   pnpm trace:query --trace-id <traceId> --compact --since <ISO-8601> --limit 200
   

   跟踪碎片化（每个服务都有自己的根 span，跨边界的跟踪 ID 不匹配） = 上下文传播中断。在调查业务逻辑之前，先修复 traceparent/tracestate 请求头转发。

   检测门槛（生成假设之前）： 如果静态分析后仍不清楚运行时行为，请先在关键决策节点添加有针对性的日志语句，再生成假设。使用会话级日志文件（.claude/context/tmp/debug-{sessionId}.log）捕获运行时状态。人工参与环节：添加检测后，请用户重现错误，再分析结果。只有收集到运行时证据后，才能进入阶段 2。

5. 追踪数据流

   当错误出现在调用栈深处时：

   请参阅此目录中的 root-cause-tracing.md，了解完整的反向追踪方法。

   简要步骤：

   • 错误值最初来自哪里？
   • 哪段代码使用了这个错误值调用当前代码？
   • 持续向上追踪，直到找到源头
   • 在源头修复，而不是处理表面症状

阶段 2：模式分析

修复之前，先找出模式：

1. 查找可正常工作的示例

   • 在同一代码库中找到类似且正常工作的代码
   • 类似的功能中，哪些部分运行正常？

2. 对照参考实现

   • 如果要实现某种模式，请完整阅读参考实现
   • 不要略读，要逐行阅读
   • 完全理解该模式后再应用

3. 找出差异

   • 正常代码和出错代码之间有哪些不同？
   • 列出所有差异，无论多么细微
   • 不要假设“那不可能有影响”

4. 理解依赖关系

   • 这需要哪些其他组件？
   • 需要哪些设置、配置和环境？
   • 它基于哪些假设？

阶段 3：假设与测试

遵循科学方法：

1. 提出单一假设

   • 清楚地表述：“我认为 X 是根因，因为 Y”
   • 把它写下来
   • 明确具体，不要含糊

2. 以最小改动进行测试

   • 只做验证假设所需的最小改动
   • 一次只更改一个变量
   • 不要一次修复多个问题

3. 验证后再继续

   • 是否有效？是 — 进入阶段 4
   • 无效？提出新假设
   • 不要在现有修复上继续叠加更多修复

4. 遇到不确定时

   • 直说“我不理解 X”
   • 不要假装知道
   • 寻求帮助
   • 进一步研究

阶段 4：实现

修复根本原因，而非表面症状：

1. 创建失败测试用例

   • 尽可能简单地复现问题
   • 尽可能编写自动化测试
   • 如果没有测试框架，则编写一次性测试脚本
   • 修复前必须先创建
   • 使用 tdd 技能编写规范的失败测试

2. 实施单一修复

   • 解决已确定的根本原因
   • 一次只做一项更改
   • 不要顺便进行其他改进
   • 不要捆绑重构

3. 验证修复

   • 测试现在是否通过？
   • 是否有其他测试失败？
   • 问题是否确实已解决？

4. 清理

   • 移除本次调试会话中添加的所有检测代码（日志语句、临时诊断代码）
   • 验证清理结果：搜索本次会话的调试 ID 或检测标记，确认生产代码中没有残留的调试内容
   • 示例：rg "debug-{sessionId}" --type-add 'src:*.{js,ts,cjs,mjs}' -tsrc .

5. 如果修复无效

   • 停止
   • 统计：你尝试过多少次修复？
   • 如果少于 3 次：返回阶段 1，根据新信息重新分析
   • 如果达到或超过 3 次：停止并质疑架构（见下文第 6 步）
   • 未讨论架构前，不要尝试第 4 次修复

6. 如果 3 次或更多修复均失败：质疑架构

   表明存在架构问题的模式：

   • 每次修复都会在不同位置暴露新的共享状态、耦合或问题
   • 修复需要“大规模重构”才能实施
   • 每次修复都会在其他地方引发新的症状

   停止并质疑根本问题：

   • 这种模式从根本上是否可靠？
   • 我们是否只是在“纯粹凭惯性坚持下去”？
   • 应该重构架构，还是继续修复表面症状？

   尝试更多修复之前，先与人类搭档讨论

   这不是假设失败，而是架构本身有误。

危险信号——停止并遵循流程

如果你发现自己在想：

• “先快速修一下，之后再调查”
• “先试着改一下 X，看看有没有用”
• “多改几处，然后运行测试”
• “跳过测试，我会手动验证”
• “很可能是 X，我来修一下”
• “我还没完全弄明白，但这个办法可能有效”
• “模式建议用 X，但我会换个方式处理”
• “主要问题如下：[未经调查就列出修复方案]”
• 尚未追踪数据流就提出解决方案
• “再试一次修复”（已经尝试过 2 次或更多时）
• 每次修复都会在不同位置暴露新问题

以上任何一种情况都意味着：停止。返回阶段 1。

**如果 3 次或更多修复均失败：**质疑架构（见阶段 4.5）

人类搭档提醒你做错了的信号

留意这些纠正：

• “这不是没发生吗？”——你未经验证就做出了假设
• “这样能让我们看到……吗？”——你本该补充证据收集
• “别猜了”——你还没弄清情况就提出修复方案
• “深入思考这个问题”——质疑根本问题，而不只是表面症状
• “我们卡住了吗？”（感到沮丧时）——你的做法不起作用

**看到这些信号时：**停止。返回阶段 1。

常见借口

借口	事实
“问题很简单，不需要流程”	简单问题也有根本原因。处理简单 bug 的流程很快。
“情况紧急，没时间走流程”	系统化调试比反复猜测和试错更快。
“先试试这个，再调查”	第一次修复会定下模式。从一开始就做好。
“确认修复有效后再写测试”	未经测试的修复无法持久。先写测试才能证明修复有效。
“一次修复多个问题可以节省时间”	无法确定哪些修复有效，还会引入新 bug。
“参考资料太长，我照着模式调整就行”	理解不全面必然导致 bug。要完整阅读。
“我看到问题了，让我来修复”	看到症状不等于理解根本原因。
“再试着修复一次”（已经失败 2 次以上）	失败 3 次以上说明存在架构问题。质疑现有模式，不要再次尝试修复。

快速参考

阶段	关键活动	成功标准
1. 根本原因	阅读错误信息、复现问题、检查变更、收集证据	理解是什么以及为什么
2. 模式	查找有效示例、进行比较	找出差异
3. 假设	提出理论、进行最小化测试	得到证实或提出新假设
4. 实施	创建测试、修复、验证	Bug 已解决，测试通过

流程得出“没有根本原因”时

如果系统化调查表明，问题确实由环境导致、与时间有关或源自外部因素：

1. 你已经完成了流程
2. 记录你调查过的内容
3. 实施恰当的处理方式（重试、超时、错误消息）
4. 添加监控/日志记录，以便今后调查

但是： 95% 的“没有根本原因”案例，都是调查不充分导致的。

辅助技术

以下技术是系统化调试的一部分，可在此目录中使用：

• root-cause-tracing.md - 沿调用栈反向追踪 bug，找到最初的触发因素
• defense-in-depth.md - 找到根本原因后，在多个层级添加验证
• condition-based-waiting.md - 用条件轮询替代任意设置的超时
• find-polluter - 用于测试污染二分查找（因共享状态导致的随机失败测试）：从项目根目录运行 .claude/tools/analysis/find-polluter/find-polluter.sh（Windows 上运行 find-polluter.ps1），以确定哪个测试污染了整个测试套件。

相关技能：

• tdd - 用于创建失败的测试用例（阶段 4，第 1 步）
• verification-before-completion - 在宣称成功前，验证修复确实有效

实际效果

根据调试会话的数据：

• 系统化方法：15-30 分钟即可修复
• 随机修复方法：反复折腾 2-3 小时
• 首次修复成功率：95%，而非 40%
• 引入新 bug：几乎为零，而非经常发生

AI 辅助调试与现代可观测性（2025+）

OpenTelemetry：新的堆栈跟踪

对于分布式系统，OpenTelemetry 跟踪取代了手动收集 echo/env 证据的方式。跟踪通过 span ID 和 trace ID 展示请求跨越服务边界的完整历程（W3C Trace Context 标准：traceparent/tracestate 标头）。

分布式故障的证据优先级（按顺序优先采用）：

1. Distributed traces (OpenTelemetry spans, correlated trace IDs)
2. Structured logs with correlation IDs
3. Metrics with timestamps
4. Manual instrumentation (Phase 1 Step 4 bash examples)

常见症状——跟踪片段化： 每个服务都显示自己的根 span，跨越边界的 trace ID 不匹配。这意味着上下文传播已中断——在调查业务逻辑之前，先修复标头转发。

AI 辅助根因分析

基于 LLM 的调试 Agent（2025 年模式）通过读取生产跟踪并结合代码库上下文进行关联分析，提出最小复现案例，以增强第 1 阶段。

适合使用 AI 辅助的情况：

• 复杂度高、影响波及多个服务的分布式故障
• 需要快速识别根因的值班事件
• 将生产跟踪转换为确定性的测试复现程序

使用 AI 辅助时，不要跳过第 1 阶段。 AI 提议只是待验证的假设——在实现任何 AI 提议的修复之前，先执行第 3 阶段（假设测试）。AI 无法取代系统化调查，但能加快证据收集。

反模式

反模式	失败原因	正确做法
“先快速修复，之后再调查”	快速修复会变成永久方案；根因会以不同症状再次出现	始终先完成第 1 阶段，再修改生产代码
一次进行多项更改	无法确定哪项更改修复或破坏了系统；会引入回归问题	每次假设测试只做一项更改；验证后再进行下一项更改
未经测试就采用 AI 提议的修复	AI 提议只是待验证的假设，并非事实；盲目应用会跳过第 3 阶段	将 AI 提议视为待测试的假设，而非可直接实现的答案
3 次失败后还尝试第 4 次修复	在错误方案上进行 N+1 次修复尝试会加重问题	修复尝试失败 3 次后，升级到架构评审
修复前跳过失败的测试	无法验证修复是否有效，也无法发现回归问题	先创建失败的测试；它能证明根因并验证修复

记忆协议（强制）

开始之前： 阅读 .claude/context/memory/learnings.md

完成之后：

• 新模式 -> .claude/context/memory/learnings.md
• 发现问题 -> .claude/context/memory/issues.md
• 做出决策 -> .claude/context/memory/decisions.md

假定会发生中断：如果没有记录在记忆中，就等于没有发生。