Habilidades root-cause-tracing

🔍

root-cause-tracing

Name: root-cause-tracing
Author: DYAI2025

Seguro ⚙️ Comandos externos📁 Acceso al sistema de archivos

追溯错误到源头

调试工作往往只是处理症状而非找到根本原因。此技能教授通过调用栈进行系统性回溯追踪,以识别错误的原始触发点,从而防止错误反复出现。

Soporta: Claude Codex Code(CC)

📊 70 Adecuado

Descargar el ZIP de la skill

Subir en Claude

Ve a Configuración → Capacidades → Skills → Subir skill

Activa y empieza a usar

Pruébalo

Usando "root-cause-tracing". Error: git init failed in /Users/project/packages/core

Resultado esperado:

**从症状向后追溯:**
1. `git init` 以空 `cwd` 运行 → 解析为 `process.cwd()`
2. `WorktreeManager.createSessionWorktree()` 以空 projectDir 调用
3. `Session.create()` 从测试设置传递了空字符串
4. 测试在 `beforeEach` 运行前访问了 `context.tempDir`
**根本原因:** 顶层变量初始化访问了空值
**建议修复:** 将 tempDir 改为 getter,如果在 beforeEach 前访问则抛出错误
**深度防御层级:**
- 层级1: Project.create() 验证目录不为空
- 层级2: WorkspaceManager 验证路径存在
- 层级3: NODE_ENV 守卫拒绝在 tmpdir 外执行 git 操作
- 层级4: 在 git 操作前记录堆栈跟踪

Usando "root-cause-tracing". Tests are creating .git directories in the source folder during CI

Resultado esperado:

**使用二分法查找污染源:**
运行 find-polluter.sh 脚本:
```bash
./find-polluter.sh '.git' 'src/**/*.test.ts'
```
**脚本的作用:**
- 按排序顺序逐个运行测试
- 检查每个测试后是否出现 .git
- 在第一个创建污染的测试处停止
**如果污染在任何测试前就存在:**
在二分前运行 `rm -rf .git` 以建立干净状态
**识别测试后:**
- 仅运行该测试: `npm test path/to/test.ts`
- 检查测试设置中的 tempDir 或目录处理
- 查找使用动态路径调用 git 操作的位置

Auditoría de seguridad

Seguro

v6 • 1/21/2026

The skill is legitimate debugging methodology documentation. Static findings are false positives triggered by example shell commands in documentation (npm test, grep) and a bisection script for test pollution detection. SHA256 hash strings in the report were misidentified as cryptographic vulnerabilities or C2 keywords. No malicious intent or actual security risks present.

Archivos escaneados

919

Líneas analizadas

hallazgos

Auditorías totales

Auditado por: claude Ver historial de auditorías →

Puntuación de calidad

Arquitectura

100

Mantenibilidad

Contenido

Comunidad

100

Seguridad

Cumplimiento de la especificación

Lo que puedes crear

调试复杂的测试失败

当测试在调用栈深处失败且直接错误消息无法揭示源头时,通过链条向后追溯,找到是哪个测试设置或夹具引入了有问题的状态。

修复反复出现的生产环境错误

当同一错误在修复后持续重现时,使用根本原因追溯找到原始触发点,并在源头实施适当的验证,而不是修补症状。

识别测试污染源

当测试创建了不需要的文件或状态(如在错误位置的.git目录),但无法确定是哪个测试造成的时,使用二分技术隔离污染源。

Prueba estos prompts

基本错误追踪

I'm getting an error: [error message]. The stack trace shows [stack trace]. Trace backward through the call chain to find the original trigger. What called the immediate cause and what value was passed that led to this error?

使用检测工具进行调试

I need to trace where [problematic behavior] is originating. Add stack trace logging before the operation that fails. The function that directly causes the issue is [function name]. Help me construct the instrumentation and analyze the output.

查找测试污染源

Something is creating [unwanted file or state] during tests but I do not know which test. The test pattern is [pattern like 'src/**/*.test.ts']. Guide me through using the bisection technique to identify the specific test responsible.

应用深度防御

I found the root cause of [bug]: [description of root cause]. Help me design validation at multiple layers to make this bug impossible to reintroduce. Include checks at the entry point, intermediate layers, and the operation itself.

Mejores prácticas

在进行任何修复之前,始终通过完整的调用链向后追溯。在错误出现的地方修复只是在处理症状,而非原因。
在有问题的操作之前添加堆栈跟踪日志,而不是在它失败之后。捕获目录、cwd和相关参数。
找到根本原因后,在多个层级实施验证。每个层级都使错误更难意外重新引入。

Evitar

在错误显现的地方修复,而不是追溯找到无效数据或状态的起源位置。
只在直接原因处添加检查,而不在早期入口点验证,导致错误可以绕过检查。
使用可能在测试环境中被抑制的日志记录器,而不是使用 console.error 输出关键调试信息。

Preguntas frecuentes

何时应该使用根本原因追溯而不是常规调试?

当错误出现在长调用链的深处、同一错误在修复后持续复发,或错误消息未明确指出问题所在时,应使用根本原因追溯。如果修复只能防止症状出现,而没有解决为什么无效数据到达该点的原因,就需要进行追溯。

如何追踪我没有编写的代码?

在有问题的操作之前添加检测工具,记录堆栈跟踪、目录和参数。这会显示外部代码中的调用来源。然后使用记录的参数从该入口点向前追溯,以理解数据流。

什么是测试污染,为什么它很重要?

测试污染是指一个测试留下的状态(文件、目录、数据库记录)影响其他测试。这会导致间歇性失败并使调试困难。二分技术可以找到创建污染的具体测试。

如何判断是否找到了真正的根本原因?

当满足以下条件时,表示您已找到根本原因:在该点的修复可以防止错误发生,修复不需要在多个下游点进行更改,错误无法通过不同路径绕过修复到达同一有问题的操作。

错误修复中的深度防御是什么?

深度防御是指在入口点和失败操作之间的多个层级添加验证。如果一个层级被绕过,另一个层级会捕获问题。这使得错误无法通过未来的代码更改意外重新引入。

如何使用 find-polluter.sh 脚本?

运行 `./find-polluter.sh <file_or_dir_to_check> <test_pattern>`。例如: `./find-polluter.sh '.git' 'src/**/*.test.ts'`。脚本会逐个运行测试,并在第一个创建指定文件或目录的测试处停止。首先使用 `rm -rf .git` 删除任何现有污染。