Skip to content

jnMetaCode/superpowers-zh / skills/systematic-debugging

systematic-debugging

Verified

遇到任何 bug、测试失败或异常行为时使用,在提出修复方案之前执行

FileKindSize
SKILL.mdskill md9.2 KB
condition-based-waiting-example.tsscript4.9 KB
condition-based-waiting.mdmarkdown3.5 KB
defense-in-depth.mdmarkdown3.6 KB
find-polluter.shexecutablescript1.9 KB
root-cause-tracing.mdmarkdown5.3 KB

defense-in-depth.md

View on GitHub
# 纵深防御校验

## 概述

当你修复了一个由无效数据引起的 bug 时,在一个地方加校验似乎就够了。但这个单点检查可能会被不同的代码路径、重构或 mock 绕过。

**核心原则:** 在数据经过的每一层都做校验。让这个 bug 在结构上不可能发生。

## 为什么需要多层校验

单层校验:"我们修了这个 bug"
多层校验:"我们让这个 bug 不可能再发生"

不同层级能捕获不同问题:
- 入口校验捕获大多数 bug
- 业务逻辑校验捕获边界情况
- 环境守卫防止特定上下文的危险操作
- 调试日志在其他层级失效时提供帮助

## 四个层级

### 第 1 层:入口校验
**目的:** 在 API 边界拒绝明显无效的输入

```typescript
function createProject(name: string, workingDirectory: string) {
  if (!workingDirectory || workingDirectory.trim() === '') {
    throw new Error('workingDirectory cannot be empty');
  }
  if (!existsSync(workingDirectory)) {
    throw new Error(`workingDirectory does not exist: ${workingDirectory}`);
  }
  if (!statSync(workingDirectory).isDirectory()) {
    throw new Error(`workingDirectory is not a directory: ${workingDirectory}`);
  }
  // ... 继续处理
}
```

### 第 2 层:业务逻辑校验
**目的:** 确保数据对当前操作是合理的

```typescript
function initializeWorkspace(projectDir: string, sessionId: string) {
  if (!projectDir) {
    throw new Error('projectDir required for workspace initialization');
  }
  // ... 继续处理
}
```

### 第 3 层:环境守卫
**目的:** 防止在特定环境中执行危险操作

```typescript
async function gitInit(directory: string) {
  // 在测试中,拒绝在临时目录之外执行 git init
  if (process.env.NODE_ENV === 'test') {
    const normalized = normalize(resolve(directory));
    const tmpDir = normalize(resolve(tmpdir()));

    if (!normalized.startsWith(tmpDir)) {
      throw new Error(
        `Refusing git init outside temp dir during tests: ${directory}`
      );
    }
  }
  // ... 继续处理
}
```

### 第 4 层:调试埋点
**目的:** 记录上下文信息以便事后分析

```typescript
async function gitInit(directory: string) {
  const stack = new Error().stack;
  logger.debug('About to git init', {
    directory,
    cwd: process.cwd(),
    stack,
  });
  // ... 继续处理
}
```

## 应用模式

当你发现一个 bug 时:

1. **追踪数据流** —— 错误值从哪里产生的?在哪里被使用?
2. **标注所有检查点** —— 列出数据经过的每一个节点
3. **在每一层添加校验** —— 入口、业务逻辑、环境、调试
4. **测试每一层** —— 尝试绕过第 1 层,验证第 2 层能否捕获

## 实际案例

Bug:空的 `projectDir` 导致 `git init` 在源代码目录执行

**数据流:**
1. 测试准备 → 空字符串
2. `Project.create(name, '')`
3. `WorkspaceManager.createWorkspace('')`
4. `git init` 在 `process.cwd()` 中执行

**添加的四层防御:**
- 第 1 层:`Project.create()` 校验非空/存在/可写
- 第 2 层:`WorkspaceManager` 校验 projectDir 非空
- 第 3 层:`WorktreeManager` 在测试中拒绝在 tmpdir 之外执行 git init
- 第 4 层:git init 前记录堆栈跟踪

**结果:** 全部 1847 个测试通过,bug 不可能再复现

## 关键洞察

四个层级缺一不可。在测试过程中,每一层都捕获了其他层遗漏的 bug:
- 不同的代码路径绕过了入口校验
- mock 绕过了业务逻辑检查
- 不同平台的边界情况需要环境守卫
- 调试日志发现了结构性误用

**不要止步于一个校验点。** 在每一层都添加检查。
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 195kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 192kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 192kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 192kUpdated Claude CodeCodexVerifiedInstall