名称: 系统性调试描述: 在尝试任何修复前始终使用。切勿直接跳到解决方案——先调查根本原因。在遇到任何技术问题、错误、测试失败或意外行为时使用。版本: 2.0.0

系统性调试

概述

随机修复浪费时间并创建新错误。快速补丁掩盖了根本问题。

核心原则： 在尝试修复前始终找到根本原因。症状修复是失败的。

违反此过程的字面意义就是违反调试的精神。

铁律

没有根本原因调查，就没有修复

如果您未完成阶段1，则不能提出修复。

何时使用

用于任何技术问题：

测试失败
生产中的错误
意外行为
性能问题
构建失败
集成问题

特别在以下情况下使用：

时间紧迫时（紧急情况使猜测变得诱人）
“只是一个快速修复”看起来很明显时
您已经尝试了多种修复时
之前的修复未起作用时
您不完全理解问题时

不要跳过当：

问题看起来简单时（简单错误也有根本原因）
您匆忙时（匆忙保证返工）
经理要求立即修复时（系统性比乱搞更快）

四个阶段

您必须在进行下一个阶段前完成每个阶段。

阶段1：根本原因调查

在尝试任何修复前：

仔细阅读错误消息
- 不要跳过错误或警告
- 它们通常包含确切的解决方案
- 完全阅读堆栈跟踪
- 注意行号、文件路径、错误代码
一致地复现
- 您能可靠地触发它吗？
- 确切的步骤是什么？
- 它每次都发生吗？
- 如果不可复现 → 收集更多数据，不要猜测
检查最近的变化
- 什么变化可能导致此问题？
- Git差异、最近的提交
- 新依赖、配置变化
- 环境差异

在多组件系统中收集证据

当系统有多个组件（CI → 构建 → 签名，API → 服务 → 数据库）时：

在提出修复前，添加诊断工具：

对于每个组件边界：
  - 记录进入组件的数据
  - 记录退出组件的数据
  - 验证环境/配置传播
  - 检查每一层的状态

运行一次以收集显示哪里中断的证据
然后分析证据以识别故障组件
然后调查该特定组件

示例（多层系统）：

# 层1：工作流
echo "=== 工作流中可用的秘密： ==="
echo "IDENTITY: ${IDENTITY:+SET}${IDENTITY:-UNSET}"

# 层2：构建脚本
echo "=== 构建脚本中的环境变量： ==="
env | grep IDENTITY || echo "IDENTITY 不在环境中"

# 层3：签名脚本
echo "=== 钥匙串状态： ==="
security list-keychains
security find-identity -v

# 层4：实际签名
codesign --sign "$IDENTITY" --verbose=4 "$APP"

这揭示： 哪一层失败（秘密 → 工作流 ✓，工作流 → 构建 ✗）

追踪数据流

当错误在调用栈深处时：

快速版本：
- 坏值起源于哪里？
- 什么用坏值调用了这个？
- 持续向上追踪直到找到源
- 在源处修复，而不是在症状处

阶段2：模式分析

在修复前找到模式：

找到工作示例
- 在相同代码库中定位类似的工作代码
- 什么工作的与什么坏掉的相似？
与参考比较
- 如果实现模式，完全阅读参考实现
- 不要略读——阅读每一行
- 在应用前完全理解模式
识别差异
- 工作与坏掉之间有什么不同？
- 列出每一个差异，无论多小
- 不要假设“那不可能重要”
理解依赖
- 这需要什么其他组件？
- 什么设置、配置、环境？
- 它做出什么假设？

阶段3：假设和测试

科学方法：

形成单一假设
- 清晰陈述：“我认为X是根本原因因为Y”
- 写下来
- 具体，不模糊
最小化测试
- 做最小的可能改变来测试假设
- 一次一个变量
- 不要同时修复多个东西
在继续前验证
- 起作用了吗？是 → 阶段4
- 没起作用？形成新假设
- 不要在顶部添加更多修复
当您不知道时
- 说“我不理解X”
- 不要假装知道
- 寻求帮助
- 更多研究

阶段4：实施

修复根本原因，而不是症状：

创建失败测试用例
- 最简单的可能复现
- 如果可能，自动化测试
- 如果没有框架，一次性测试脚本
- 在修复前必须有
实施单一修复
- 解决已识别的根本原因
- 一次一个改变
- 没有“既然我在这里”的改进
- 没有捆绑重构
验证修复
- 测试现在通过了吗？
- 没有其他测试被破坏吗？
- 问题实际解决了吗？
如果修复不起作用
- 停止
- 计数：您尝试了多少次修复？
- 如果 < 3：返回阶段1，用新信息重新分析
- 如果 ≥ 3：停止并质疑架构（下面的步骤5）
- 在没有架构讨论的情况下不要尝试修复 #4
如果3+次修复失败：质疑架构

表示架构问题的模式：
- 每次修复揭示不同地方的新共享状态/耦合/问题
- 修复需要“大规模重构”来实施
- 每次修复在其他地方创建新症状
停止并质疑基础：
- 这个模式根本上是健全的吗？
- 我们是否“纯粹通过惯性坚持它”？
- 我们应该重构架构还是继续修复症状？
在尝试更多修复前与用户讨论

这不是失败的假设——这是错误的架构。

红旗 - 停止并遵循过程

如果您发现自己思考：

“现在快速修复，稍后调查”
“只是尝试改变X看看是否起作用”
“添加多个改变，运行测试”
“跳过测试，我将手动验证”
“可能是X，让我修复那个”
“我不完全理解但这可能起作用”
“模式说X但我会以不同方式适应它”
“这里是主要问题：[列出没有调查的修复]”
在追踪数据流前提出解决方案
“再试一次修复”（当已经尝试了2+次）
每次修复揭示不同地方的新问题

所有这些意味着：停止。返回阶段1。

如果3+次修复失败： 质疑架构（见阶段4.5）

常见合理化

借口	现实
“问题简单，不需要过程”	简单问题也有根本原因。过程对简单错误很快。
“紧急，没时间过程”	系统性调试比猜测试错更快。
“先尝试这个，然后调查”	第一次修复设置模式。从一开始就做对。
“我将在确认修复起作用后写测试”	未测试的修复不持久。先测试证明它。
“多个修复同时节省时间”	无法隔离什么起作用。导致新错误。
“参考太长，我将适应模式”	部分理解保证错误。完全阅读它。
“我看到问题，让我修复它”	看到症状 ≠ 理解根本原因。
“再试一次修复”（在2+次失败后）	3+次失败 = 架构问题。质疑模式，不要再修复。

快速参考

阶段	关键活动	成功标准
1. 根本原因	阅读错误、复现、检查变化、收集证据	理解什么和为什么
2. 模式	找到工作示例、比较	识别差异
3. 假设	形成理论、最小化测试	确认或新假设
4. 实施	创建测试、修复、验证	错误解决、测试通过

技术：根本原因追踪

当错误在调用栈深处显现时，向后追踪以找到原始触发。

追踪过程

观察症状

错误：在 /Users/jesse/project/packages/core 中 git init 失败

找到直接原因 - 什么代码直接导致这个？

await execFileAsync('git', ['init'], { cwd: projectDir })

问：什么调用了这个？

WorktreeManager.createSessionWorktree(projectDir, sessionId)
  → 由 Session.initializeWorkspace() 调用
  → 由 Session.create() 调用
  → 由 Project.create() 的测试调用

持续向上追踪 - 传递了什么值？
- projectDir = ''（空字符串！）
- 空字符串作为 cwd 解析为 process.cwd()

找到原始触发 - 空字符串来自哪里？

const context = setupCoreTest() // 返回 { tempDir: '' }
Project.create('name', context.tempDir) // 在 beforeEach 前访问！

添加堆栈跟踪

当您无法手动追踪时，添加工具：

async function gitInit(directory: string) {
  const stack = new Error().stack
  console.error('DEBUG git init:', {
    directory,
    cwd: process.cwd(),
    nodeEnv: process.env.NODE_ENV,
    stack,
  })
  await execFileAsync('git', ['init'], { cwd: directory })
}

提示：

在测试中使用 console.error()（记录器可能被抑制）
在危险操作前记录，而不是失败后
包括上下文：目录、cwd、环境变量
new Error().stack 显示完整调用链

找到哪个测试导致污染

如果某物在测试期间出现但您不知道哪个测试，使用二分法：

# 逐一运行测试，停在第一个污染者
for f in src/**/*.test.ts; do
  npm test "$f" && [ -d .git ] && echo "污染者: $f" && break
done

永远不要只修复错误出现的地方。 向后追踪以找到原始触发。

技术：纵深防御验证

找到根本原因后，验证数据通过的每一层。使错误在结构上不可能。

为什么多层

单一验证：“我们修复了错误”
多层：“我们使错误不可能”

不同层捕获不同情况：

入口验证捕获大多数错误
业务逻辑捕获边缘情况
环境防护防止上下文特定危险
调试日志在其他层失败时帮助

四层

层1：入口点验证 - 在API边界拒绝无效输入

function createProject(name: string, workingDirectory: string) {
  if (!workingDirectory || workingDirectory.trim() === '') {
    throw new Error('workingDirectory 不能为空')
  }
  if (!existsSync(workingDirectory)) {
    throw new Error(`workingDirectory 不存在: ${workingDirectory}`)
  }
}

层2：业务逻辑验证 - 确保数据对操作有意义

function initializeWorkspace(projectDir: string, sessionId: string) {
  if (!projectDir) {
    throw new Error('workspace 初始化需要 projectDir')
  }
}

层3：环境防护 - 防止在特定上下文中的危险操作

async function gitInit(directory: string) {
  if (process.env.NODE_ENV === 'test') {
    const normalized = normalize(resolve(directory))
    const tmpDir = normalize(resolve(tmpdir()))
    if (!normalized.startsWith(tmpDir)) {
      throw new Error(`在测试期间拒绝在临时目录外 git init`)
    }
  }
}

层4：调试工具 - 捕获上下文用于取证

async function gitInit(directory: string) {
  logger.debug('即将 git init', {
    directory,
    cwd: process.cwd(),
    stack: new Error().stack,
  })
}

应用纵深防御

当您找到错误时：

追踪数据流 - 坏值起源于哪里？在哪里使用？
映射所有检查点 - 列出数据通过的每一点
在每一层添加验证 - 入口、业务、环境、调试
测试每一层 - 尝试绕过层1，验证层2捕获它

不要停在一个验证点。 在每一层添加检查。

实际影响

从调试会话：

系统性方法：15-30分钟修复
随机修复方法：2-3小时乱搞
第一次修复率：95% vs 40%
引入新错误：接近零 vs 常见

名称: 系统性调试 描述: 在尝试任何修复前始终使用。切勿直接跳到解决方案——先调查根本原因。在遇到任何技术问题、错误、测试失败或意外行为时使用。 版本: 2.0.0