specsfy-specialist-debugging

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Diagnóstico

诊断

Quando usar

何时使用

Acionar quando houver um comportamento observado divergente do esperado, com ou sem reprodução confiável ainda estabelecida.
Acionar também para falha intermitente ("flaky"), regressão após deploy ou degradação de performance com sintoma concreto (timeout, erro, lentidão reportada).
Não acionar para otimizar um sistema que já se comporta corretamente e sem sintoma — isso é
```
$specsfy-specialist-performance-engineering
```
, que parte de um SLO e não de uma falha.
Combinar com
```
$specsfy-specialist-observability
```
quando o ambiente de produção não expuser sinal suficiente para instrumentar o boundary certo.

当观察到的行为与预期不符时触发，无论是否已建立可靠的复现路径。
也适用于间歇性故障（"flaky"）、部署后的回归问题，或有具体症状的性能下降（如超时、报错、反馈卡顿）。
请勿用于优化运行正常且无异常症状的系统——此类场景属于
```
$specsfy-specialist-performance-engineering
```
的范畴，其出发点是SLO而非故障。
当生产环境无法提供足够信号来对正确边界进行插桩分析时，可结合
```
$specsfy-specialist-observability
```
使用。

Fluxo

流程

Capturar comportamento esperado, comportamento observado, ambiente exato e o momento/frequência da última ocorrência — sem isso a hipótese é chute.
Construir uma reprodução confiável ou, quando reprodução direta não for viável, um sinal observável e repetível (log, métrica, trace) que correlacione com a falha.
Reduzir input, componentes envolvidos e janela de tempo até o menor caso que ainda reproduz a falha — cada elemento removido que não muda o resultado é uma variável eliminada da hipótese.
Formular hipóteses falsificáveis e ordená-las pela facilidade de teste e pela probabilidade dado o sintoma observado, não pela mais interessante.
Instrumentar o boundary mais discriminante entre as hipóteses restantes — o ponto onde uma hipótese prevê um valor e a outra prevê outro.
Identificar causa, extensão do impacto (só esse caminho, ou a classe inteira de chamadas) e o mecanismo exato pelo qual ela produz o sintoma.
Se autorizado a corrigir, aplicar a menor mudança que remove a causa e adicionar teste de regressão que falha sem a correção.

收集预期行为、观察到的行为、精确环境以及最后一次出现的时间/频率——缺少这些信息的假设只是猜测。
构建可靠的复现用例；若无法直接复现，则构建一个可观察且可重复的信号（日志、指标、链路追踪）来关联故障。
减少输入、涉及的组件和时间范围，直至得到仍能复现故障的最小用例——每移除一个不影响结果的元素，就从假设中排除一个变量。
提出可证伪的假设，并根据测试难度和观察到的症状对应的概率排序，而非按趣味性排序。
对剩余假设间最具区分度的边界进行插桩分析——即某个假设预测一个值，而另一个假设预测另一个值的节点。
确定根本原因、影响范围（仅该路径，还是整个调用类别）以及产生症状的确切机制。
若获得修复授权，应用能消除根本原因的最小改动，并添加无修复时会失败的回归测试。

Padrões

模式

Não alterar mais de uma causa candidata por vez — mudar duas coisas ao mesmo tempo invalida a atribuição de causa quando o sintoma desaparece.
Separar correlação temporal de causalidade: "começou depois do deploy X" é uma pista, não uma prova, até isolar o mecanismo.
Preservar evidência (logs, estado, dump) antes de reiniciar processo ou limpar estado — o ambiente que falhou pode ser irreproduzível depois.
Comparar ambiente bom e ruim sistematicamente: mesma versão, config, dados, carga e ordem de operações, variando um fator por vez.
Tratar flakiness como sintoma de concorrência, timing, estado compartilhado ou dependência externa até haver prova do contrário — nunca como "só rodar de novo".
Remover instrumentação temporária, verbosa ou sensível (dado pessoal, segredo) antes de concluir o diagnóstico.
Descrever a causa no nível do mecanismo ("a race entre X e Y permite leitura antes da escrita completar"), nunca só no nível do sintoma ("às vezes falha").

每次仅更改一个候选原因——同时更改两项会导致症状消失时无法确定真正的原因。
区分时间相关性与因果关系：“在部署X之后开始出现”是线索，而非证据，除非隔离出具体机制。
在重启进程或清理状态前保留证据（日志、状态、转储）——故障环境可能在之后无法复现。
系统地对比正常环境与异常环境：相同版本、配置、数据、负载和操作顺序，每次仅改变一个因素。
除非有相反证据，否则将间歇性故障视为并发、时序、共享状态或外部依赖问题的症状——绝不能只当作“重新运行即可解决”。
在诊断结束前移除临时、冗余或敏感（个人数据、机密信息）的插桩代码。
在机制层面描述根本原因（如“X与Y之间的竞态条件导致读取操作在写入完成前执行”），而非仅停留在症状层面（如“有时会失败”）。

Antipadrões

反模式

"Adicionar print e rodar de novo" sem hipótese prévia — gera ruído, raramente reduz o espaço de busca e é frequentemente indistinguível de tentativa aleatória.
Corrigir o primeiro ponto onde o erro aparece, sem verificar se ali é a origem ou apenas onde o efeito se torna visível (o
```
NullPointerException
```
raramente nasce onde é lançado).
Declarar "corrigido" porque a reprodução manual parou de falhar uma vez — sem reprodução automatizada e determinística, a ausência do sintoma pode ser apenas sorte ou mudança de timing.
Ignorar teste flaky como "instável, não relacionado" sem investigar — flakiness é evidência de bug real de concorrência ou estado compartilhado na maioria dos casos, não ruído a suprimir.

无预先假设就“添加打印日志并重新运行”——这会产生噪音，很少能缩小搜索范围，且常常与随机尝试无异。
修复首次出现错误的节点，而不验证该节点是根源还是仅为症状显现的位置（
```
NullPointerException
```
很少在抛出的位置产生）。
因手动复现一次未失败就宣称“已修复”——若无自动化且确定性的复现用例，症状消失可能只是运气或时序变化。
未调查就将间歇性测试视为“不稳定、无关”——大多数情况下，间歇性故障是并发或共享状态存在真实Bug的证据，而非可忽略的噪音。

Validação

验证

A reprodução falha de forma determinística antes da correção e passa de forma determinística depois, no mesmo ambiente.
O teste de regressão adicionado falha pelo motivo correto quando a correção é revertida (não por outro motivo incidental).
Cenários adjacentes ao caminho corrigido foram verificados quanto a efeito colateral da mudança.
Existe registro conciso de causa (mecanismo), evidência que a comprova e prevenção (teste, invariante, alarme) adicionada.
Não declarar a causa "resolvida" sem essa evidência — atribuir causa por intuição sem reprodução ou teste de regressão é proibido.

修复前，复现用例在同一环境中确定性失败；修复后，确定性通过。
添加的回归测试在撤销修复时会因正确原因失败（而非其他偶然原因）。
已验证修复路径的相邻场景是否存在改动的副作用。
存在简洁的记录，包含根本原因（机制）、验证证据以及添加的预防措施（测试、不变量、告警）。
若无上述证据，不得宣称根本原因“已解决”——禁止仅凭直觉归因而无复现或回归测试。

specsfy-specialist-debugging

Original

Translation

Diagnóstico

诊断

Quando usar

何时使用

Fluxo

流程

Padrões

模式

Antipadrões

反模式

Validação

验证

Skills relacionadas

相关技能