メニュー
遇到任何 bug、测试失败或异常行为时使用，在提出修复方案之前执行
Codex または Claude でインストール この Prompt をコピーして Codex、Claude、または他のアシスタントに貼り付けると、Skill ページを確認してインストールできます。
SOC 職業分類に基づく
| name | systematic-debugging |
| description | 遇到任何 bug、测试失败或异常行为时使用，在提出修复方案之前执行 |
随意修复既浪费时间又会引入新 bug。草率的补丁只会掩盖深层问题。
核心原则： 在尝试修复之前，务必先找到根本原因。只修症状就是失败。
敷衍走流程等于违背调试的精神。
不做根因调查，不许提修复方案
如果你还没完成第一阶段，就不能提出修复方案。
用于任何技术问题：测试失败、生产环境 bug、异常行为、性能问题、构建失败、集成问题。
尤其在以下情况必须使用：
以下情况也不要跳过： 问题看起来很简单、你很赶时间、领导要求立刻修好。
你必须完成每个阶段后才能进入下一个。
在尝试任何修复之前：
仔细阅读错误信息
read_file(path="<错误日志或堆栈跟踪文件路径>") 阅读完整错误信息稳定复现
检查近期变更
run_command(command="git diff") 查看工作区变更，run_command(command="git log --oneline -10") 查看近期提交search_content(pattern="...") 或 read_file(path="...") 检查相关代码在多组件系统中收集证据
对每个组件边界：记录进入和离开的数据，验证环境/配置传递，检查每一层的状态。执行一次以收集证据，确定断裂点，然后针对该组件深入调查。
跟踪数据流
参见 root-cause-tracing.md 了解完整的反向追踪技术。
先找到模式，再修复：
search_content(pattern="...") 在同一代码库中找到类似的正常代码，并用 read_file(path="...") 完整阅读参考实现科学方法：
修复根本原因，而非症状：
创建失败的测试用例 - 最简化的复现，尽可能用自动化测试。使用 test-driven-development 技能编写规范的失败测试
实施单一修复 - 修复已定位的根本原因，每次只改一处，不做"顺便改改"的优化，不捆绑重构
验证修复 - 测试通过了吗？其他测试没有被破坏吧？问题真的解决了吗？
如果修复不起作用
如果 3 次以上修复都失败了：质疑架构
架构问题的信号： 每次修复都暴露新的共享状态/耦合/其他位置的问题；修复需要"大规模重构"；每次修复都在其他地方产生新的症状。
停下来质疑： 这个模式从根本上合理吗？我们是不是在"惯性驱动"下坚持了错误方案？应该重构架构还是继续修补症状？
在尝试更多修复之前，和你的搭档讨论。 这不是假设失败——这是架构有误。
如果你发现自己在想：
以上这些都意味着：停下来。回到第一阶段。
如果 3 次以上修复都失败了： 质疑架构（见第四阶段第 5 步）
当你看到这些信号时： 停下来。回到第一阶段。
| 借口 | 现实 |
|---|---|
| "问题很简单，不需要走流程" | 简单问题也有根本原因。对于简单 bug，流程很快就能走完。 |
| "紧急情况，没时间走流程" | 系统化调试比反复猜测式修复更快。 |
| "先试一下，再排查" | 第一次修复就定下了基调。从一开始就做对。 |
| "确认修复有效后再写测试" | 没有测试的修复留不住。先写测试才能证明修复有效。 |
| "一次修多个问题省时间" | 无法隔离哪个生效了。还会引入新 bug。 |
| "参考实现太长了，我自己改改" | 一知半解必然出 bug。完整阅读。 |
| "我看出问题了，让我修一下" | 看到症状 ≠ 理解根因。 |
| "再试一次"（在 2 次以上失败后） | 3 次以上失败 = 架构问题。质疑模式，不要继续修。 |
| 阶段 | 关键活动 | 通过标准 |
|---|---|---|
| 1. 根因 | 阅读错误、复现、检查变更、收集证据 | 理解了什么出了问题以及为什么 |
| 2. 模式 | 找到正常示例、对比 | 识别出差异 |
| 3. 假设 | 提出理论、最小化验证 | 假设被验证或产生新假设 |
| 4. 实施 | 创建测试、修复、验证 | bug 已修复，测试通过 |
如果系统化排查后发现问题确实是环境相关、时序相关或外部因素导致的：
但是： 95% 的"找不到根因"其实是排查不充分。
以下技术是系统化调试的组成部分，可在本目录中找到：
root-cause-tracing.md - 沿调用栈反向追踪 bug，找到最初的触发点defense-in-depth.md - 找到根因后，在多个层级添加校验condition-based-waiting.md - 用条件轮询替代硬编码等待时间相关技能：
在开始任何对话时使用——确立如何查找和使用技能，要求在任何响应（包括澄清性问题）之前调用 Skill 工具
在任何创造性工作之前必须使用此技能——创建功能、构建组件、添加功能或修改行为。在实现之前先探索用户意图、需求和设计。
中文 review 沟通参考——话术模板、分级标注（必须修复/建议修改/仅供参考）、国内团队常见反模式应对。
中文 commit 与 changelog 配置参考——Conventional Commits 中文适配、commitlint/husky/commitizen 中文模板、conventional-changelog 中文配置。仅在用户显式 /chinese-commit-conventions 时调用，不要根据上下文自动触发。
中文文档排版参考——中英文空格、全半角标点、术语保留、链接格式、中文文案排版指北约定。仅在用户显式 /chinese-documentation 时调用，不要根据上下文自动触发。
国内 Git 平台配置参考——Gitee、Coding.net、极狐 GitLab、CNB 的 SSH/HTTPS/凭据/CI 接入差异与镜像同步配置。仅在用户显式 /chinese-git-workflow 时调用，不要根据上下文自动触发。