القائمة
Use when 程序出现错误、异常、崩溃，或行为与预期不符，或测试失败，或无法定位问题根因时。触发场景：调试、debug、报错、错误、异常、bug、问题排查、故障排查、不工作、崩溃、无法运行、出错了、为什么不生效、运行报错、跑不起来、程序挂了。
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
| name | debug-expert |
| description | Use when 程序出现错误、异常、崩溃，或行为与预期不符，或测试失败，或无法定位问题根因时。触发场景：调试、debug、报错、错误、异常、bug、问题排查、故障排查、不工作、崩溃、无法运行、出错了、为什么不生效、运行报错、跑不起来、程序挂了。 |
铁律：先理解，再修改。 禁止在没有复现和定位根因之前就修改代码（猜测式修改往往掩盖真实问题）。
在完成**阶段二（假设清单）**和**阶段三（最小复现）**之前，禁止对任何代码做出修改。 即便你"知道"原因，也必须先建立假设清单并尝试复现，再动手修改。
references/debug-log-template.md），包含假设清单、最小复现、证据链、验证命令与回归建议。../code-review-expert/references/quality-gates-checklist.md。tdd-master（TDD 开发大师）：先写能复现问题的测试，再修复writing-plans（实施计划编写）：把修复拆成可执行步骤（适合复杂问题）code-review-expert（代码审查专家）：变更后做质量门禁收集足够的背景信息（每次最多问 2-3 个问题）：
必须了解：
按需追问：
明确禁止：在没有完整错误信息时就开始猜测原因。
根据现有信息，生成 2-5 个可能的假设（从最可能到最不可能排序）：
假设清单：
1. [假设 A]：可能性 高/中/低，理由：[...]
2. [假设 B]：可能性 高/中/低，理由：[...]
3. [假设 C]：可能性 高/中/低，理由：[...]
验证计划：先验证假设 1，因为 [原因]。
思考方向：
在验证假设之前，先建立最小可复现的测试案例：
# 目标：用最少的代码稳定复现问题
# 好处：
# 1. 确认问题确实存在（而非环境问题）
# 2. 排除无关因素
# 3. 修复后可用作回归测试
# 最小复现示例
def test_bug_reproduction():
# 最简单的触发路径
result = problematic_function(minimal_input)
assert result == expected # 这一行会失败
如果无法复现：
加载 references/root-cause-analysis.md 获取系统化分析工具。
使用二分法逐步缩小问题范围：
定位策略：
1. 确认问题的边界（从哪里开始出错，到哪里结束）
2. 在中间点添加检查点，判断问题在前半段还是后半段
3. 重复，直到定位到具体的函数/行
常用调试工具：
# Python：pdb 调试
import pdb; pdb.set_trace() # 设置断点
# 或者使用 print 调试（快速但临时）
print(f"DEBUG: variable={variable!r}, type={type(variable)}")
# 日志记录
import logging
logging.debug("状态: %s", state)
# 查看进程状态
ps aux | grep process_name
# 查看端口占用
lsof -i :8080
# 查看系统日志
journalctl -u service_name -n 100 --no-pager
# 查看 Docker 容器日志
docker logs container_name --tail 100
加载 references/debugging-patterns.md 获取特定类型问题的调试模式。
定位根因后：
制定修复方案（不要第一个想到的方案就是最好的）：
实施修复
验证清单（完成前强制检查，不得跳过）：
rg 全局搜索）根因：[什么导致的]
触发条件：[什么情况下会触发]
修复方式：[如何修复]
预防措施：[如何防止再次发生]
系统对比两个环境：
# 对比环境变量
diff <(env | sort) <(ssh prod 'env | sort')
# 对比依赖版本
pip freeze vs pip freeze（生产）
# 对比配置文件
diff local.env prod.env
先测量，再优化，不要靠直觉：
# Python 性能分析
import cProfile
cProfile.run('main_function()', sort='cumulative')
# 简单计时
import time
start = time.perf_counter()
# ...代码...
print(f"耗时：{time.perf_counter() - start:.3f}秒")
遇到以下想法，立刻停下，回到当前应该所在的阶段：
| 借口 | 现实 |
|---|---|
| "错误很明显，我知道原因，直接改就好" | "明显原因"往往是症状不是根因。30 秒建个假设清单不会耽误你。 |
| "问题太紧急，没时间走流程" | 猜测式修改引入新 bug 比走流程耗时更长。紧急时更要冷静。 |
| "已经修了类似的 bug，这次一样" | 表面相似的 bug 根因可能完全不同。相似性是陷阱。 |
| "最小复现太麻烦，能复现就行" | 无法最小复现 = 无法确认修复 = 留下定时炸弹。 |
| "测试过了，差不多能用" | "差不多"不是通过标准。必须运行验证清单中的每一项。 |
| "这个问题太随机，复现不了" | 随机问题 = 竞态条件/内存问题。不复现不代表可以跳过假设阶段。 |
references/root-cause-analysis.md — 根因分析工具和框架references/debugging-patterns.md — 常见问题类型的调试模式超压缩通信模式。通过去掉废话、冠词和客套语，在保持完整技术准确性的同时削减约 75% token 用量。 当用户说"caveman 模式"、"简洁模式"、"少废话"、"省 token"、"简短点"或调用 /caveman 时触发。
对用户的计划或设计进行不留情面的深度追问，直到达成共同理解，逐一解决决策树的每个分支。当用户想要压力测试计划、检验设计时触发。触发词：追问我、grill me、逐一问我、挑战我的方案、深度追问、质疑设计、设计评审追问。
将当前对话压缩为交接文档，供下一个 Agent 会话接续工作。触发词：交接、handoff、下一个会话、会话摘要、接续工作、传给下一个 agent。
在代码库中发现架构"深化"机会——将浅模块变成深模块的重构，提升可测试性和 AI 可导航性。与 architecture-advisor 互补：architecture-advisor 设计新架构，本技能改善现有代码库结构。触发词：改进代码库架构、架构深化、找重构机会、模块耦合太紧、难以测试、代码难以理解、架构改进、improve architecture、refactor opportunities。
快速验证设计的一次性原型。区分两条分支——逻辑/状态模型用终端交互 App，UI 布局用多变体路由切换。当用户想原型验证、检验数据模型或状态机、探索多种 UI 方案时触发。触发词：原型、prototype、验证方案、快速试验、让我玩一玩、试几个设计。
Use when 已有书面实施计划、任务相对独立，且在本会话内通过子代理逐任务落实时。触发场景：执行实施计划、子代理开发、按计划实现、Task 派发实现、两阶段代码审查、plan execution。