Back to Details

debug-methodical

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Debug-Methodical — Debugging en 4 phases

Debug-Methodical — 四阶段系统化调试

Skill inspiré de obra/superpowers. Objectif : forcer une méthode rigoureuse au lieu de "try random fixes until it works".
Règle d'or : un bug sans reproduction stable est un bug mal compris. Ne JAMAIS fixer avant de reproduire.
本Skill灵感来自obra/superpowers。目标： 强制采用严谨的方法，而非“随机尝试修复直到生效”。
黄金法则： 无法稳定重现的bug就是未被理解的bug。绝对不要在重现之前进行修复。

Les 4 phases (strictes, dans l'ordre)

四个严格阶段（按顺序）

Phase 1 : REPRODUCE

阶段1：重现（REPRODUCE）

Objectif : exécuter le bug à volonté, dans un environnement contrôlé.
Checklist :
  • Étapes de reproduction documentées (Given/When/Then)
  • Reproduction déterministe (>= 3 runs consécutifs identiques)
  • Environnement isolé (local, container, test env)
  • Inputs minimaux (le moins de données/steps possible)
  • Version/commit exacts identifiés
Sortie : test automatisé qui échoue en exposant le bug (test de régression).
Signal rouge : "ça marche sur ma machine" / "parfois ça fail" → reproduction insuffisante, retour Phase 1.
目标： 在受控环境中按需触发bug。
检查清单：
  • 记录重现步骤（Given/When/Then格式）
  • 可确定性重现（连续≥3次运行结果一致）
  • 隔离环境（本地、容器、测试环境）
  • 最小化输入（尽可能少的数据/步骤）
  • 确定确切版本/提交记录
输出： 一个能暴露bug的自动化测试用例（回归测试），且该测试当前会失败。
危险信号： “在我机器上正常” / “偶尔失败” → 重现不充分，返回阶段1。

Phase 2 : ISOLATE

阶段2：隔离（ISOLATE）

Objectif : identifier la cause racine, pas juste un symptôme.
Techniques :
  • Bisect : 
    git bisect
    pour trouver le commit fautif
  • Binary search dans le code : commenter la moitié, puis itérer
  • Print-driven debugging : logs aux frontières (entrée/sortie fonctions)
  • Debugger : breakpoints, step-through, variable watch
  • Diff environnements : que diffère-t-il entre "qui marche" et "qui casse" ?
  • Question the premise : l'hypothèse initiale est-elle correcte ?
Checklist :
  • Cause identifiée (ligne / condition / input exact)
  • Explication du pourquoi (pas juste le quoi)
  • Chaîne de causalité documentée (A cause B cause C)
  • Autres manifestations potentielles du même bug identifiées
Signal rouge : "je pense que c'est X" sans preuve → retour isolate avec instrumentation.
目标： 识别根本原因，而非仅仅是症状。
技巧：
  • 二分法：使用
    git bisect
    定位有问题的提交
  • 代码二分搜索：注释一半代码，逐步迭代
  • 打印驱动调试：在函数边界处添加日志（输入/输出）
  • 调试器：断点、单步执行、变量监控
  • 环境对比：“正常环境”和“故障环境”之间有哪些差异？
  • 质疑前提：初始假设是否正确？
检查清单：
  • 已确定原因（确切代码行/条件/输入）
  • 解释为什么会发生（而非仅仅是发生了什么）
  • 记录因果链（A导致B导致C）
  • 识别同一bug可能的其他表现形式
危险信号： “我觉得是X”但无证据 → 返回隔离阶段，添加监测手段。

Phase 3 : FIX

阶段3：修复（FIX）

Objectif : corriger la cause racine avec le minimum de changement.
Checklist :
  • Fix au bon niveau (cause racine, pas symptôme)
  • Changement minimal (KISS, voir rule 05)
  • Pas d'effet de bord sur autres features
  • Pas de fix "au cas où" / spéculatif (voir rule 23 Karpathy)
  • Fix dans le bon layer (domain / infra / UI)
Signaux rouges :
  • Fix qui ajoute un 
    try/catch
    pour masquer l'erreur → traite le symptôme, pas la cause
  • Fix qui nécessite de modifier les tests existants de façon suspecte
  • Fix qui "marche" sans que tu saches pourquoi
目标： 以最小改动修复根本原因。
检查清单：
  • 在正确层级修复（针对根本原因，而非症状）
  • 最小化改动（遵循KISS原则，参见规则05）
  • 不对其他功能产生副作用
  • 不做“以防万一”的推测性修复（参见Karpathy规则23）
  • 在正确层级修复（领域层/基础设施层/UI层）
危险信号：
  • 添加
    try/catch
    来掩盖错误的修复 → 仅处理了症状，而非原因
  • 修复需要可疑地修改现有测试用例
  • 修复“生效”但你不知道为什么

Phase 4 : VERIFY

阶段4：验证（VERIFY）

Objectif : prouver que le fix marche ET n'a rien cassé d'autre.
Checklist :
  • Test de régression (Phase 1) passe maintenant
  • Suite de tests complète passe
  • Reproduction manuelle ne montre plus le bug
  • Scénarios adjacents testés (edge cases proches)
  • Performance non dégradée
  • Logs / monitoring vérifiés en staging si critique
Règle de régression : le test écrit en Phase 1 reste dans la codebase pour toujours. Un bug fixé ne doit JAMAIS réapparaître (voir 
/qa:regression
).
目标： 证明修复有效且未破坏其他功能。
检查清单：
  • 阶段1编写的回归测试现在可以通过
  • 完整测试套件全部通过
  • 手动重现不再出现bug
  • 测试了相邻场景（相近边缘案例）
  • 性能未下降
  • 若为关键问题，已验证预发布环境的日志/监控
回归规则： 阶段1编写的测试用例需永久保留在代码库中。已修复的bug绝对不能再次出现（参见
/qa:regression
）。

Anti-patterns critiques

关键反模式

Anti-patternPourquoi c'est mal
Shotgun debuggingChanger 10 trucs au hasard, aucun apprentissage
Fix du symptômeBug revient sous une autre forme
Skip reproductionFix impossible à valider
Skip verification"ça devrait marcher" — preuve ou pas fini
Pas de test de régressionBug réapparaît dans 3 mois
Fix avec 
catch (Exception)
générique		Masque d'autres bugs
Commit mélangé fix + refactor
git bisect
impossible
反模式危害
霰弹式调试随机修改多处内容，无法从中学习
症状修复bug会以其他形式重现
跳过重现步骤无法验证修复效果
跳过验证步骤“应该会生效”——没有证据就不算完成
不添加回归测试bug会在3个月后重现
使用
catch (Exception)
通用捕获的修复		会掩盖其他bug
修复与重构混合提交无法使用
git bisect
定位问题

Techniques avancées

高级技巧

Pour bugs de concurrence

并发bug排查

  • Forcer les interleavings (sleep stratégique, stress test)
  • Thread dumps / profiler
  • Vérifier les invariants atomiquement
  • 强制触发线程交错（策略性睡眠、压力测试）
  • 线程转储/性能分析器
  • 原子性检查不变量

Pour bugs d'intégration

集成bug排查

  • Snapshot du payload exact (HAR, logs)
  • Reproduire avec 
    curl
    ou client minimal
  • Vérifier versions exactes des dépendances
  • 捕获确切负载快照（HAR、日志）
  • 使用
    curl
    或最小化客户端重现问题
  • 检查依赖库的确切版本

Pour flaky tests

不稳定测试（flaky tests）排查

  • Run 100x pour mesurer le taux de flakiness
  • Identifier la dépendance (temps, ordre, ressource partagée)
  • Ne JAMAIS marquer un test 
    @Flaky
    sans ticket de correction
  • 运行100次以测量不稳定率
  • 识别依赖因素（时间、顺序、共享资源）
  • 绝对不要在未创建修复工单的情况下标记测试为
    @Flaky

Intégration Claude Craft

Claude Craft集成

  • /qa:tdd
     — bug fix en mode TDD (test qui échoue d'abord)
  • /qa:fix
     — correction automatisée des bugs QA
  • /qa:regression
     — registre des tests de régression
  • Skill 
    atomic-tasks
     — découper le debug en phases atomiques
  • Rule 07 (testing) — bug fix = test de régression obligatoire
  • /qa:tdd
     — 以TDD模式修复bug（先编写失败的测试）
  • /qa:fix
     — 自动修复QA发现的bug
  • /qa:regression
     — 回归测试注册表
  • Skill 
    atomic-tasks
     — 将调试拆解为原子阶段
  • 规则07（testing） — bug修复必须包含回归测试

Ressources

资源

  • obra/superpowers
  • Rule 
    .claude/rules/07-testing.md
  • Command 
    /qa:tdd
    , 
    /qa:regression
Date de dernière mise à jour : 2026-04-15 Version : 1.0.0
  • obra/superpowers
  • 规则 
    .claude/rules/07-testing.md
  • 命令 
    /qa:tdd
    , 
    /qa:regression
最后更新日期： 2026-04-15 版本： 1.0.0