debugging

调试

开始前请阅读 [[principles/fix-root-causes]]。每次调试都遵循这一原则：追溯根本原因，绝不掩盖表面症状。

流程

1. 复现。 获取确切的错误。运行失败的命令，阅读完整输出。如果无法复现，就无法验证修复是否有效。

2. 阅读错误信息。 错误消息、堆栈跟踪和行号都是数据。在提出假设前，请完整阅读。大多数 Bug 都会明确指出问题所在。

3. 优先怀疑状态，而不是代码。 调试代码前，先检查持久化状态——尤其是重启问题或环境漂移。请参阅 [[principles/fix-root-causes]]。

   • Noodle 状态：.noodle/orders.json（是否有过期项？）、.noodle/sessions/（是否有孤立项？）、.noodle.toml（是否有效？）
   • 环境：tmux 会话（tmux ls）、锁文件、缓存产物
   • 配置：.noodle.toml 验证（noodle start 会报告诊断信息）、技能 frontmatter 解析错误
   • 持久化文件：brain/ 笔记、计划文件、待办事项——检查是否损坏或引用过期

4. 隔离问题。 缩小范围。是哪个文件？哪个函数？哪一行？使用二分法：注释掉一半，查看问题是否仍然存在，然后重复此过程。

5. 找出根本原因。 最先想到的“修复”通常只是修复表面症状。不断追问“为什么？”，直到找到真正原因：

   • 测试失败 → mock 有误 → 接口已更改 → 类型与运行时形状不匹配 → 修复类型
   • 构建失败 → 导入错误 → 循环依赖 → 重构模块
   • 运行时崩溃 → 值未定义 → 缺少 null 检查 → 数据源在为空时返回 null → 在源头处理空情况

6. 修复并验证。 修复根本原因，而不是表面症状。然后进行验证：运行测试、执行构建、测试功能路径。“能编译”不算验证。

7. 检查是否存在同类问题。 如果 Bug 出现在某处，就搜索其他地方是否存在相同模式。修复所有实例，或从结构上杜绝此类问题。

Noodle 专用诊断

调试 Noodle 基础设施故障时：

症状	优先检查
Cook 无法启动	tmux ls、.noodle/orders.json 是否有效、技能解析器路径
订单卡住	.noodle/orders.json 中是否有过期项、.noodle.toml 适配器配置
缺少技能	.noodle.toml 中的 [skills] 路径、.agents/skills/<name>/SKILL.md 是否存在
mise 过期	.noodle/mise.json 中的 generated_at 时间戳、待办同步脚本
会话孤立	.noodle/sessions/<id>/meta.json 状态、tmux ls 中是否有僵尸会话

遇到阻碍时

• 添加检测，不要猜测。 在关键位置添加日志，以查看实际值。读取实际状态（[[principles/prove-it-works]]）。
• 对比变更。 git diff、git log、git bisect。大多数 Bug 都是最近引入的。
• 简化。 将失败案例精简到最小复现。移除所有无关内容。
• 一次只改一处。 同时进行多项更改，就无法确定究竟是什么修复了问题（或导致了问题）。
• 检查假设。 Bug 往往出在你确信无误的部分。逐一验证所有内容。

反模式

• 绕过标志（--no-verify、--force、SKIP_CHECK=true）只会掩盖症状，不会修复原因。
• 重试循环会用概率掩盖间歇性 Bug。
• 盲目调试——同时改三处，“看看有没有帮助”——会模糊因果关系。
• 添加保护条件（if (x !== undefined)），却不追问 x 为什么是 undefined。

修复后

如果此 Bug 可能再次发生，或影响了你的理解，请记录经验。撰写 brain 笔记、更新技能或添加待办事项。系统应从每个 Bug 中变得更智能。请参阅 [[principles/encode-lessons-in-structure]]。