system_prompts_leaks 中的 Claude Code Debug Skill 解析：会话级调试日志、守护进程排查与五步诊断流程

本文以 Claude Code 的 debug 技能定义文件 为主体，完整解读这个技能如何为一次 Claude Code 会话开启调试日志、如何定位会话日志与后台守护进程日志的位置，以及它内置的"读日志 → 查特性文档 → 给出修复建议"五步诊断流程。读完后，你将掌握用 /debug 与 claude --debug 两种模式捕获 Claude Code 问题现场的完整方法，以及该技能如何与 claude-code-guide 子代理、配置级联文件协同工作。

一、技能定位与文件结构

debug 是 Claude Code 内置的一个技能（Skill），其完整定义见 debug/SKILL.md，位于本仓库的 Claude Code 技能目录下。文件由两部分组成：

1. YAML frontmatter：声明技能的机器可读元数据；
2. Markdown 正文：技能被调用（即用户执行 /debug）时注入给模型的指令文本。

frontmatter 原文如下：

---
name: debug
description: Enable debug logging for this session and help diagnose issues
---

description 一句话概括了技能的两大职责：为当前会话开启调试日志，并协助诊断问题。这与技能正文的标题 "Help the user debug an issue they're encountering in this current Claude Code session" 完全对应——注意其中的 "this current session"，该技能的作用域明确限定在当前会话，而非全局诊断（全局性的配置体检由同目录的 doctor 技能 承担）。

正文中包含 {debug_log_path}、{user_home}、{working_directory} 等花括号占位符。从仓库中的文件形态看，SKILL.md 是模板文件：技能被调用时，这些占位符会被运行时替换为实际的日志路径、用户主目录和工作目录。同一模板还包含若干"状态注入"段落（如 "No daemon lock or status file found"、"No log file exists yet"），这些是调用时刻对真实环境状态的检测结论，说明 Claude Code 在注入指令前已经执行过一轮环境探测，并把探测结果作为事实前提交给模型。

二、开启调试日志：/debug 的时序语义与 claude --debug 兜底

技能正文的第一个小节 "Debug Logging Just Enabled" 说明了 /debug 调用时的关键时序事实，原文要点如下：

Debug logging was OFF for this session until now. Nothing prior to this /debug invocation was captured.

也就是说，会话内调试日志默认是关闭的，在用户执行 /debug 之前，本次会话中发生的一切都没有被记录到调试日志里。这直接决定了标准的排查动作——指令要求模型：

1. 告知用户"调试日志现已在 {debug_log_path} 开启"；
2. 请用户复现一次问题；
3. 复现后重新读取日志文件，分析新增内容。

如果用户无法复现问题，技能给出第二条路径：用 claude --debug 重启会话，这样可以从进程启动阶段就开始捕获日志，覆盖到会话早期（例如启动加载配置、初始化 MCP 连接）发生的故障——这些故障恰好在"先开会话、后开日志"的模式下会丢失。

这一 --debug 参数在本仓库的另一个技能中有独立佐证。update-config 技能的"Troubleshooting Hooks"小节将 "Use --debug" 列为 hook 排障的最后一步：

Use --debug - Run claude --debug to see hook execution logs

两个技能相互印证：调试日志不仅记录普通错误，还包含 hook 执行日志，因此排查"某个 hook 没有生效/报错"这类问题时，claude --debug 是官方推荐的观察手段。这也解释了为什么 debug 技能要引导用户"复现"——只有复现时触发的 hook 执行、工具调用与错误才会进入日志。

三、会话调试日志：{debug_log_path} 与 [ERROR] / [WARN] 扫描

"Session Debug Log" 小节给出了日志的消费规则：

• 位置：当前会话的调试日志位于 {debug_log_path}（运行时注入的绝对路径）。
• 初始状态：技能注入时该日志文件尚不存在（"No log file exists yet"），它会在调试日志开启后的首次写入时才被创建。
• 扫描方法：不要逐行通读，而是对全文件 grep [ERROR] 和 [WARN] 行来快速定位异常。

结合 "Instructions" 小节的第 2 步（见第六节），日志的消费策略是"先看尾部 20 行学习格式，再全局扫错误标记"。文件尾部 20 行被指定为格式样本（"The last 20 lines show the debug file format"），因为调试日志是持续追加的，最近的行最能反映当前的字段布局、级别标签和时间戳样式；模型先"学会"这个格式，再针对 [ERROR]/[WARN] 条目、堆栈跟踪（stack traces）和失败模式（failure patterns） 做全文搜索。

四、守护进程（Daemon）状态：后台会话问题的第二日志源

"Daemon" 小节处理另一类问题来源——Claude Code 的后台守护进程。该小节的注入内容是调用时刻的探测结论：

No daemon lock or status file found — the background daemon does not appear to be running.

其判定逻辑是：通过锁文件和状态文件是否存在来判断后台守护进程是否在运行；若两者皆无，则结论为守护进程未运行。这一状态是动态的——如果你的环境里守护进程正在运行，同一小节注入的将是不同的状态描述。

该小节同时指明了第二日志源的位置与适用场景：当问题涉及后台会话（background sessions）或 claude agents 命令时，即使守护进程日志可能为空，也去查看：

{user_home}/.claude/daemon.log

（即 ~/.claude/daemon.log）。这构成了一个明确的分诊规则：前台交互会话的问题查 {debug_log_path}，后台/agents 相关问题查 daemon.log，两者互为补充而非替代。

五、诊断上下文中的配置级联：三个 settings 文件

"Settings" 小节提醒模型，排查配置相关问题时，配置分布在三个作用域的文件中：

作用域	文件路径
user（用户级）	{user_home}/.claude/settings.json（即 ~/.claude/settings.json）
project（项目级，通常提交入库）	{working_directory}/.claude/settings.json
local（本地级，通常 gitignore）	{working_directory}/.claude/settings.local.json

这三级"用户 → 项目 → 本地"的级联结构在本仓库其他技能文档中得到一致印证。doctor 技能的 Data sources 小节给出了更完整的级联描述：

settings cascade ~/.claude/settings.json (user) → .claude/settings.json (project, checked in) → .claude/settings.local.json (local, gitignored) → managed policy settings

以及两条对诊断极有价值的实现细节：

1. 失效的 JSON 会被整体静默忽略。doctor 技能指出，可用 jq empty <file> 对每个配置文件做"仅解析、不打印内容"的校验，并明确说明 "A file that fails to parse is silently ignored wholesale, which is how 'my settings stopped working' usually happens"——这解释了为什么用户反馈"我的配置突然不生效"时，debug 技能把三个 settings 文件列为必查项：文件语法错误是最常见的静默失效原因。
2. 优先级为 user < project < local。doctor 技能在多处禁用/权限规则中强调，低优先级作用域的取值会被高优先级作用域静默覆盖。因此诊断"某配置不生效"时，必须先确认该键在三级文件中的分布，判断是否被上层覆盖，而不能只看某一份文件。

六、Instructions：五步诊断标准作业流程

技能正文以 "Instructions" 小节给出固定的五步诊断流程，这是整个技能的操作核心，原文逐条如下：

第 1 步 — Review the user's issue description（回顾用户的问题描述） 先明确用户报告的症状，再动手翻日志。该技能的模板中同时包含 "Issue Description" 小节，注入的默认状态是 "The user did not describe a specific issue"，此时的兜底指令为：直接读取调试日志，并总结其中出现的错误、警告或值得注意的问题——即无明确症状时，从日志反向归纳问题。

第 2 步 — 解析日志格式，定位失败模式 "The last 20 lines show the debug file format. Look for [ERROR] and [WARN] entries, stack traces, and failure patterns across the file"。如第三节所述，尾部 20 行用于学习格式，随后对全文件做 [ERROR]/[WARN]、堆栈跟踪与失败模式的模式化搜索。

第 3 步 — 必要时启动 claude-code-guide 子代理 "Consider launching the claude-code-guide subagent to understand the relevant Claude Code features"。这体现了 debug 技能的边界意识：日志只能告诉你"哪里坏了"，而"这个特性本该如何工作"属于 Claude Code 产品知识，该技能通过子代理委派来解决。本仓库收录的 claude-code-guide 子代理定义 展示了这一委派的完整设计：

• 轻量运行：frontmatter 指定 model: haiku、tools: Bash, Read, WebFetch, WebSearch、permissionMode: dontAsk，以低成本完成文档检索；
• 明确"官方文档优先于记忆"的原则：子代理被要求用 WebFetch 抓取 Claude Code 文档索引，并在无法触达文档时明确告知用户"答案可能已过时"，而不是凭训练记忆作答——这对快速迭代的 CLI 工具尤为关键；
• 覆盖四大知识域：Claude Code CLI 工具、Claude Agent SDK、Claude API、Claude Tag（Claude in Slack）。

第 4 步 — Explain what you found in plain language（用通俗语言解释发现） 要求把日志中观察到的错误模式翻译成用户能理解的语言，而非直接甩出原始日志行。

第 5 步 — Suggest concrete fixes or next steps（给出具体修复建议或下一步动作） 诊断必须落到可执行动作上。结合本仓库可见的其他技能能力，典型的"下一步"可以包括：用 update-config 技能 修正 settings 文件（该技能内置 "CRITICAL: Read Before Write" 与"合并而非替换"的规则，避免修复配置时破坏现有内容）、按第五节的优先级检查配置覆盖、或按第四节切换到 daemon.log 继续排查。

七、设计要点小结

把 debug/SKILL.md 放回 system_prompts_leaks 仓库的 Claude Code 文档群中观察，可以看出几个可复用的工程设计：

1. 数据与指令分离：日志路径、守护进程状态、问题描述等"事实"由运行时探测后注入对应小节；"如何分析"的指令集中在 Instructions，模板本身不含任何硬编码环境数据。
2. 双入口的日志捕获策略：会话中途用 /debug（零成本但只能覆盖之后），无法复现时改用 claude --debug 从启动阶段全程捕获，两者形成互补。
3. 分层日志源分诊：前台会话日志（{debug_log_path}）与后台守护进程日志（~/.claude/daemon.log）按问题类型路由，避免在错误的日志里大海捞针。
4. 模式化日志分析：不要求通读全文，而是"尾部 20 行学格式 + 全局 grep [ERROR]/[WARN]/堆栈/失败模式"，这是为 LLM 上下文预算定制的高效读法。
5. 知识边界外化：产品特性知识交给专职的 claude-code-guide 子代理（文档抓取 + 过时声明），debug 技能只负责"日志证据 → 结论 → 修复建议"的主干。
6. 与体检/配置技能联动：同一技能目录下的 doctor、update-config 等技能共享同一套配置级联事实（三级 settings 文件、~/.claude.json、解析校验方法），debug 技能的 "Settings" 小节正是这一共享知识在诊断场景下的投影。

适用前提与限制

• 本文所有路径与行为描述均以本仓库收录的这份 Claude Code 技能定义为准；{debug_log_path} 等占位符的实际值、以及守护进程锁/状态文件的具体命名，属于 Claude Code 运行时行为，仓库内未给出实现源码，仅能确认文档中的路径与判定逻辑。
• 技能中 "No daemon lock or status file found"、"No log file exists yet" 等表述是调用时刻的探测结果，在不同用户环境注入的内容可能不同。
• claude --debug 会捕获自启动起的全量日志，适用于无法复现场景；已可复现的问题优先使用会话内 /debug，以减小日志噪声。
• 本仓库为 prompt 抓取存档，文件按版本持续更新（见 README.md 的版本表）；引用具体措辞时应以当前仓库中的 debug/SKILL.md 原文为准。