Back to Details

bugfix-workflow

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Bugfix 工作流通用知识库

General Bugfix Workflow Knowledge Base

本 Skill 提供标准化 6 阶段 Bugfix 工作流的通用知识，适用于所有技术栈。
This Skill provides general knowledge of the standardized 6-phase Bugfix workflow, applicable to all tech stacks.

TDD 流程（核心原则）

TDD Process (Core Principles)

RED Phase（先写失败测试）

RED Phase (Write failing tests first)

  1. 测试必须能复现当前 bug
  2. 测试必须在修复前失败
  3. 测试应该测试行为，不是实现
验证命令模板：
bash
make test TARGET={stack} FILTER={test_file}
  1. Tests must reproduce the current bug
  2. Tests must fail before the fix
  3. Tests should verify behavior, not implementation
Verification command template:
bash
make test TARGET={stack} FILTER={test_file}

GREEN Phase（最小实现）

GREEN Phase (Minimal implementation)

  1. 只写让测试通过的最小代码
  2. 不要在此阶段优化
  3. 不要添加未被测试覆盖的功能
  1. Only write the minimal code required to pass the tests
  2. Do not optimize during this phase
  3. Do not add features not covered by tests

REFACTOR Phase（重构）

REFACTOR Phase (Refactoring)

  1. 改善代码结构
  2. 保持测试通过
  3. 消除重复代码
最终验证：
bash
make test TARGET={stack}
make lint TARGET={stack}
make typecheck TARGET={stack}
  1. Improve code structure
  2. Keep tests passing
  3. Eliminate duplicate code
Final verification:
bash
make test TARGET={stack}
make lint TARGET={stack}
make typecheck TARGET={stack}

置信度评分标准

Confidence Scoring Standards

根因分析置信度

Root Cause Analysis Confidence

分数范围行为
≥60自动继续
40-59暂停询问用户
<40停止并收集更多信息
Score RangeAction
≥60Proceed automatically
40-59Pause and ask user
<40Stop and collect more information

代码审查置信度

Code Review Confidence

分数范围级别行为
≥90Critical自动修复
80-89Important自动修复
<80低于阈值不报告
Score RangeLevelAction
≥90CriticalAuto-fix
80-89ImportantAuto-fix
<80Below thresholdDo not report

通用输出格式

General Output Format

Error 结构

Error Structure

json
{
  "id": "BF-{YYYY}-{MMDD}-{NNN}",
  "file": "文件路径",
  "line": 行号,
  "severity": "critical|high|medium|low",
  "category": "错误类型",
  "description": "问题描述",
  "evidence": ["支持判断的证据"],
  "stack": "堆栈信息"
}
json
{
  "id": "BF-{YYYY}-{MMDD}-{NNN}",
  "file": "File path",
  "line": Line number,
  "severity": "critical|high|medium|low",
  "category": "Error type",
  "description": "Issue description",
  "evidence": ["Evidence supporting the judgment"],
  "stack": "Stack trace"
}

Summary 结构

Summary Structure

json
{
  "total": 总数,
  "by_type": { "类型": 数量 },
  "by_file": { "文件": 数量 }
}
json
{
  "total": Total count,
  "by_type": { "Type": Count },
  "by_file": { "File": Count }
}

Solution 结构

Solution Structure

json
{
  "solution": {
    "approach": "修复思路概述",
    "steps": ["步骤1", "步骤2"],
    "risks": ["风险1", "风险2"],
    "estimated_complexity": "low|medium|high"
  },
  "tdd_plan": {
    "red_phase": { "tests": [...] },
    "green_phase": { "changes": [...] },
    "refactor_phase": { "items": [...] }
  },
  "impact_analysis": {
    "affected_files": [...],
    "api_changes": [...],
    "test_impact": [...]
  },
  "security_review": {
    "performed": true/false,
    "vulnerabilities": [...],
    "passed": true/false
  }
}
json
{
  "solution": {
    "approach": "Overview of fix思路",
    "steps": ["Step 1", "Step 2"],
    "risks": ["Risk 1", "Risk 2"],
    "estimated_complexity": "low|medium|high"
  },
  "tdd_plan": {
    "red_phase": { "tests": [...] },
    "green_phase": { "changes": [...] },
    "refactor_phase": { "items": [...] }
  },
  "impact_analysis": {
    "affected_files": [...],
    "api_changes": [...],
    "test_impact": [...]
  },
  "security_review": {
    "performed": true/false,
    "vulnerabilities": [...],
    "passed": true/false
  }
}

Execution Result 结构

Execution Result Structure

json
{
  "issue_id": "BF-2025-MMDD-001",
  "phases": {
    "red": { "status": "pass|fail|skip", "duration_ms": 1234 },
    "green": { "status": "pass|fail|skip", "changes": [...] },
    "refactor": { "status": "pass|fail|skip", "changes": [...] }
  },
  "overall_status": "success|partial|failed"
}
json
{
  "issue_id": "BF-2025-MMDD-001",
  "phases": {
    "red": { "status": "pass|fail|skip", "duration_ms": 1234 },
    "green": { "status": "pass|fail|skip", "changes": [...] },
    "refactor": { "status": "pass|fail|skip", "changes": [...] }
  },
  "overall_status": "success|partial|failed"
}

影响分析维度

Impact Analysis Dimensions

  1. 直接影响：修改的文件
  2. 间接影响：依赖修改文件的组件
  3. API 影响：是否有破坏性变更
  4. 测试影响：需要更新的测试
  1. Direct Impact: Modified files
  2. Indirect Impact: Components dependent on modified files
  3. API Impact: Whether there are breaking changes
  4. Test Impact: Tests that need to be updated

安全审查清单（常见安全问题）

Security Review Checklist (Common Security Issues)

仅在涉及敏感代码（认证、输入处理、数据存储等）时进行：
  • SQL/命令注入
  • XSS 跨站脚本
  • 敏感信息泄露
  • 认证/授权问题
  • 输入验证不足
Perform only when involving sensitive code (authentication, input handling, data storage, etc.):
  • SQL/Command injection
  • XSS Cross-site scripting
  • Sensitive information leakage
  • Authentication/Authorization issues
  • Insufficient input validation

批次执行策略

Batch Execution Strategy

  1. 默认批次大小：3 个问题/批
  2. 每批完成后：输出批次报告，等待用户确认
  3. 失败处理：记录失败原因，尝试最多 3 次，3 次失败后标记为 failed
  1. Default batch size: 3 issues per batch
  2. After each batch completion: Output batch report and wait for user confirmation
  3. Failure handling: Record failure reason, retry up to 3 times, mark as failed after 3 failures

Bugfix 文档模板

Bugfix Documentation Template

markdown
undefined
markdown
undefined

[问题简述] Bugfix 报告

[Issue Brief] Bugfix Report

日期：{YYYY-MM-DD} 置信度：{confidence}/100 技术栈：{stack}
Date: {YYYY-MM-DD} Confidence: {confidence}/100 Tech stack: {stack}

1. 问题描述

1. Issue Description

1.1 错误信息

1.1 Error Messages

[结构化错误列表]
[Structured error list]

1.2 根因分析

1.2 Root Cause Analysis

[根因描述 + 证据]
[Root cause description + evidence]

2. 修复方案

2. Fix Solution

2.1 TDD 计划

2.1 TDD Plan

RED Phase

RED Phase

[失败测试代码]
[Failing test code]

GREEN Phase

GREEN Phase

[最小实现代码]
[Minimal implementation code]

REFACTOR Phase

REFACTOR Phase

  • 重构项
  • Refactoring items

2.2 影响分析

2.2 Impact Analysis

[影响范围]
[Impact scope]

3. 验证计划

3. Verification Plan

  • 测试通过
  • 覆盖率达标
  • 无回归
undefined
  • Tests passed
  • Coverage meets standard
  • No regression
undefined

知识沉淀标准

Knowledge Precipitation Standards

值得沉淀的知识

Knowledge Worth Precipitating

  1. 新发现的问题模式 - 之前没有记录的错误类型
  2. 可复用的解决方案 - 适用于多种场景的修复模式
  3. 重要的教训 - 容易犯的错误，反直觉的行为
  4. 性能优化 - 测试执行速度提升
  1. Newly discovered issue patterns - Error types not documented before
  2. Reusable solutions - Fix patterns applicable to multiple scenarios
  3. Important lessons - Common mistakes, counterintuitive behaviors
  4. Performance optimization - Test execution speed improvements

不需要沉淀的情况

Cases Not Needing Precipitation

  1. 一次性问题 - 特定于某个文件的 typo
  2. 已有文档覆盖 - 问题已在 troubleshooting 中记录
  1. One-time issues - Typos specific to a single file
  2. Already covered by existing documentation - Issue already recorded in troubleshooting

质量门禁标准

Quality Gate Standards

检查项标准阻塞级别
测试通过100%阻塞
覆盖率>= 90%阻塞
新代码覆盖率100%阻塞
Lint无错误阻塞
TypeCheck无错误阻塞
回归测试无回归阻塞
Check ItemStandardBlocking Level
Test Pass Rate100%Blocking
Coverage>= 90%Blocking
New Code Coverage100%Blocking
LintNo errorsBlocking
TypeCheckNo errorsBlocking
Regression TestNo regressionBlocking