debug-like-expert

针对复杂问题的深度分析调试模式。当常规故障排查失败时，此技能会启动系统化的调查流程，包括收集证据、检验假设和严格验证。

此技能强调，对自己编写的代码要比对不熟悉的代码更加怀疑，因为对“代码应该如何运行”的认知偏差可能会让你忽视实际的实现错误。运用科学方法系统地找出根本原因，而不是采用快速修复。

<context_scan> 每次调用时都运行，以检测特定领域的调试专业知识：

# What files are we debugging?
echo "FILE_TYPES:"
find . -maxdepth 2 -type f 2>/dev/null | grep -E '\.(py|js|jsx|ts|tsx|rs|swift|c|cpp|go|java)$' | head -10

# Check for domain indicators
[ -f "package.json" ] && echo "DETECTED: JavaScript/Node project"
[ -f "Cargo.toml" ] && echo "DETECTED: Rust project"
[ -f "setup.py" ] || [ -f "pyproject.toml" ] && echo "DETECTED: Python project"
[ -f "*.xcodeproj" ] || [ -f "Package.swift" ] && echo "DETECTED: Swift/macOS project"
[ -f "go.mod" ] && echo "DETECTED: Go project"

# Scan for available domain expertise
echo "EXPERTISE_SKILLS:"
ls ~/.claude/skills/expertise/ 2>/dev/null | head -5

开始调查前先呈现调查结果。 </context_scan>

<domain_expertise> 特定领域的专业知识位于 ~/.claude/skills/expertise/

领域技能包含全面的知识，包括调试、测试、性能和常见陷阱。调查前，先判断是否应加载领域专业知识。

<scan_domains>

ls ~/.claude/skills/expertise/ 2>/dev/null

此操作会显示可用的领域专业知识（例如 macos-apps、iphone-apps、python-games、unity-games）。

如果未找到专业知识技能： 在没有领域专业知识的情况下继续（优雅降级）。此技能仍可使用通用调试方法正常工作。 </scan_domains>

<inference_rules> 如果用户的描述或代码库中包含领域关键词，请推断相应领域：

关键词/文件	领域技能
"Python"、"game"、"pygame"、".py" + 游戏循环	expertise/python-games
"React"、"Next.js"、".jsx/.tsx"	expertise/nextjs-ecommerce
"Rust"、"cargo"、".rs" 文件	expertise/rust-systems
"Swift"、"macOS"、".swift" + AppKit/SwiftUI	expertise/macos-apps
"iOS"、"iPhone"、".swift" + UIKit	expertise/iphone-apps
"Unity"、".cs" + Unity 导入项	expertise/unity-games
"SuperCollider"、".sc"、".scd"	expertise/supercollider
"Agent SDK"、"claude-agent"	expertise/with-agent-sdk

如果推断出领域，请确认：

Detected: [domain] issue → expertise/[skill-name]
Load this debugging expertise? (Y / see other options / none)

</inference_rules>

<no_inference> 如果无法明显判断领域，请提供选项：

What type of project are you debugging?

Available domain expertise:
1. macos-apps - macOS Swift (SwiftUI, AppKit, debugging, testing)
2. iphone-apps - iOS Swift (UIKit, debugging, performance)
3. python-games - Python games (Pygame, physics, performance)
4. unity-games - Unity (C#, debugging, optimization)
[... any others found in build/]

N. None - proceed with general debugging methodology
C. Create domain expertise for this domain

Select:

</no_inference>

<load_domain> 选定领域后，读取该技能中的所有参考资料：

cat ~/.claude/skills/expertise/[domain]/reference/*.md 2>/dev/null

这会在调查前加载全面的领域知识：

• 常见问题和错误模式
• 特定领域的调试工具和技术
• 测试与验证方法
• 性能分析与优化
• 已知陷阱和反模式
• 特定平台的注意事项

宣布：“已加载 [domain] 专业知识。正在结合特定领域背景展开调查。”

如果未找到领域技能： 告知用户，并询问是要采用通用方法继续，还是创建该领域的专业知识。 </load_domain>

<when_to_load> 已知领域时，应在调查前加载领域专业知识。

以下情况无需加载领域专业知识：

• 纯逻辑错误（与领域无关）
• 通用算法问题
• 用户明确表示“跳过领域背景” </when_to_load> </domain_expertise>

当常规故障排查失败时，此技能会启动。问题需要系统化调查，而非快速修复。现在请以资深工程师的思维方式展开调试，遵循科学严谨的原则。

重要：如果你编写或修改过正在调试的代码，就会对代码的运行方式抱有认知偏差。你对“代码应该如何运行”的理解可能有误。对自己编写的代码要比对不熟悉的代码更加怀疑——你可能看不见自己未经审视的假设。

<core_principle> 验证，而非假设。 每个假设都必须经过检验。每个“修复”都必须经过验证。没有证据，就不提供解决方案。

尤其要注意： 你设计或实现的代码，在证明无误之前都应视为有问题。你的意图并不重要，重要的只有代码的实际行为。应像质疑他人的设计决策一样，严格质疑自己的设计决策。 </core_principle>

<quick_start>

<evidence_gathering>

提出任何解决方案之前： A. 记录当前状态

• 确切的错误消息或异常行为是什么？
• 确切的复现步骤是什么？
• 实际输出与预期输出分别是什么？
• （如果知道）从什么时候开始出现异常？

B. 梳理系统

• 从入口点追踪执行路径，直到故障点
• 找出涉及的所有组件
• 完整阅读相关源文件，不要只扫一遍
• 记录影响该区域的依赖项、导入项和配置

C. 收集外部知识（需要时）

• 使用 MCP 服务获取 API 文档、库的详细信息或领域知识
• 使用网页搜索查找错误消息、特定于框架的行为或近期变更
• 查阅官方文档，了解预期行为，并与观察到的行为进行对比
• 查找已知问题、重大变更或特定版本的差异

详细的研究策略指南请参阅 reference/when-to-research.md。

</evidence_gathering>

<root_cause_analysis>

A. 提出假设

根据证据，列出可能的原因：

1. [假设 1]——因为[具体证据]
2. [假设 2]——因为[具体证据]
3. [假设 3]——因为[具体证据]

B. 验证每个假设

对于每个假设：

• 什么证据能证明它成立？
• 什么证据能证明它不成立？
• 设计一个最小化测试
• 执行测试并记录结果

关于如何应用科学方法，请参阅 reference/hypothesis-testing.md。

C. 排除或确认

在能够回答以下问题之前，不要继续：

• 哪个假设得到证据支持？
• 有什么证据与其他假设相矛盾？
• 还需要哪些信息？

</root_cause_analysis>

<solution_development>

只有在确认根本原因之后：

A. 设计解决方案

• 解决根本原因所需的最小改动是什么？
• 可能产生哪些副作用？
• 可能破坏哪些功能？

B. 实施并验证

• 进行改动
• 如需验证行为，添加日志或调试输出
• 记录为什么此改动能够解决根本原因

C. 全面测试

• 原问题是否仍会出现？
• 现在能否按复现步骤正常运行？
• 如果有相关测试，请运行这些测试
• 检查相关功能是否出现回归

关于全面的验证方法，请参阅 reference/verification-patterns.md。

</solution_development>

</quick_start>

<critical_rules>

1. 禁止顺手修复：如果无法解释改动为何有效，就不要进行改动
2. 验证一切：检验你的假设。阅读实际代码。检查实际行为
3. 使用所有工具：
   • 使用 MCP 服务获取外部知识
   • 使用网页搜索查找错误消息、文档和已知问题
   • 对复杂推理进行扩展思考（“深入思考”）
   • 阅读文件以获取完整上下文
4. 完整说明推理过程：记录每一步的推理
5. 一次只改一个变量：每次只改一处，验证后再继续
6. 完整阅读：不要略读代码。完整阅读所有相关文件
7. 追查依赖项：如果问题涉及库、配置或外部系统，也要调查它们
8. 质疑之前的工作：先前的“修复”可能有误。以全新的视角重新审查

</critical_rules>

<success_criteria>

开始前：

• 已执行上下文扫描，以识别领域
• 如果有相关领域专长，已加载

调查期间：

• 你是否理解问题发生的原因？
• 你是否验证过修复确实有效？
• 你是否测试过原始复现步骤？
• 你是否检查过副作用？
• 你能否向他人解释解决方案？
• 这个修复能否通过代码审查？

如果以上问题不能全部回答“是”，请继续调查。

重要：只有通过此检查清单后，才能将调试任务标记为完成。

</success_criteria>

<output_format>

## Issue: [Problem Description]

### Evidence
[What you observed - exact errors, behaviors, outputs]

### Investigation
[What you checked, what you found, what you ruled out]

### Root Cause
[The actual underlying problem with evidence]

### Solution
[What you changed and WHY it addresses the root cause]

### Verification
[How you confirmed this works and doesn't break anything else]

</output_format>

<advanced_topics>

如需深入了解，请参阅参考文件： 调试思维：reference/debugging-mindset.md

• 将第一性原理思维应用于调试
• 导致错误修复的认知偏差
• 系统化调查的纪律
• 何时停止并基于新的假设重新开始

调查技巧：reference/investigation-techniques.md

• 二分法／分而治之
• 橡皮鸭调试法
• 最小复现
• 从期望状态倒推
• 在更改代码前增加可观测性

假设检验：reference/hypothesis-testing.md

• 提出可证伪的假设
• 设计能够证实或证伪假设的实验
• 强证据与弱证据的区别
• 如何妥善应对错误的假设

验证模式：reference/verification-patterns.md

• “已验证”的定义（而不只是“运行过了”）
• 测试复现步骤
• 对相邻功能进行回归测试
• 何时应在修复前编写测试

研究策略：reference/when-to-research.md

• 需要外部知识的信号
• 哪些内容该搜索，哪些内容该推理
• 平衡研究时间与实验时间

</advanced_topics>

输出结果附属文件

最后一步，将内容写入 ~/.claude/skill-analytics/last-outcome-debug-like-expert.json：

{"ts":"[UTC ISO8601]","skill":"debug-like-expert","version":"1.0.0","variant":"default",
 "status":"[success|partial|error]","runtime_ms":[estimated ms from start],
 "metrics":{"hypotheses_tested":[n],"root_cause_found":[bool],"fix_verified":[bool]},
 "error":null,"session_id":"[YYYY-MM-DD]"}

如果某些阶段失败但已生成结果，请使用状态 "partial"。仅当未生成任何输出时，才使用 "error"。