Back to Details

debugging-protocol

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Debugging Protocol

调试协议

Overview

概述

This skill provides a rigorous framework for debugging complex software issues. It moves beyond ad-hoc troubleshooting to a structured process of hypothesis generation and validation.
Use this skill to:
  1. Formalize a debugging session.
  2. Systematically eliminate potential root causes.
  3. Document findings for future reference or team communication.
本Skill提供了一个用于调试复杂软件问题的严谨框架。它跳出了临时故障排查的模式，转向结构化的假设生成与验证流程。
使用本Skill可以：
  1. 规范化调试会话。
  2. 系统性排除潜在根本原因。
  3. 记录调查结果，供未来参考或团队沟通使用。

Protocol Workflow

协议工作流程

To run a structured debugging session, follow these steps:
要开展结构化调试会话，请遵循以下步骤：

1. Initialize the Session

1. 初始化会话

Create a new debugging document using the provided template. This serves as the "source of truth" for the investigation.
Template location: 
assets/debugging-session-template.md
使用提供的模板创建新的调试文档。该文档将作为本次调查的“唯一可信来源”。
模板位置：
assets/debugging-session-template.md

2. Define the Problem

2. 定义问题

Clearly articulate the System Context and Problem Statement.
  • Symptom: What is the observable behavior? How does it differ from expected behavior?
  • Scope: Which components are involved?
清晰阐述系统上下文和问题陈述。
  • 症状：可观察到的行为是什么？与预期行为有何差异？
  • 范围：涉及哪些组件？

3. Formulate Hypotheses

3. 形成假设

List distinct, testable hypotheses.
  • Avoid vague guesses.
  • Differentiate between layers (e.g., "Frontend Hypothesis" vs "Backend Hypothesis").
  • Example: "Race condition in UI state update" vs "Database schema misconfiguration".
列出明确、可测试的假设。
  • 避免模糊猜测。
  • 区分不同层级（例如，“前端假设” vs “后端假设”）。
  • 示例：“UI状态更新中的竞态条件” vs “数据库架构配置错误”。

4. Design Validation Tasks

4. 设计验证任务

For each hypothesis, design a specific validation task.
  • Objective: What are you trying to prove or disprove?
  • Steps: Precise, reproducible actions.
  • Code Pattern: Provide the exact code or command to run (e.g., a specific SQL query, a Python script using the client library, a 
    curl
    command).
  • Success Criteria: Explicitly state what output confirms the hypothesis.
为每个假设设计具体的验证任务。
  • 目标：你要证明或推翻什么？
  • 步骤：精确、可复现的操作。
  • 代码模式：提供要运行的准确代码或命令（例如，特定SQL查询、使用客户端库的Python脚本、
    curl
    命令）。
  • 成功标准：明确说明哪些输出可验证该假设。

5. Execute and Document

5. 执行与记录

Run the tasks in order. For each task, record:
  • Status: ✅ VALIDATED, ❌ FAILED, or ⚠️ INCONCLUSIVE.
  • Findings: Key observations and raw evidence (logs, screenshots).
  • Conclusion: Does this support or refute the hypothesis?
按顺序运行任务。针对每个任务，记录：
  • 状态：✅ 已验证，❌ 未通过，或 ⚠️ 无明确结论。
  • 发现：关键观察结果和原始证据（日志、截图）。
  • 结论：该结果是否支持或反驳假设？

6. Determine Root Cause

6. 确定根本原因

Synthesize the findings into a Root Cause Analysis.
  • Identify the Primary Root Cause.
  • Assign a Confidence Level.
  • Propose specific fixes.
将调查结果整合为根本原因分析。
  • 确定主要根本原因。
  • 设定置信度等级。
  • 提出具体修复方案。

Best Practices

最佳实践

  • Be Specific: Don't just say "check the logs." Say "grep for 'Error 500' in 
    /var/log/nginx/access.log
    ".
  • Isolate Variables: Change one thing at a time.
  • Validate Assumptions: Verify configuration and versions first (e.g., "Task 1: Validate Current Schema").
  • Preserve Evidence: Keep the specific trace IDs, log timestamps, or reproduction scripts.
  • 具体化：不要只说“检查日志”，要说“在
    /var/log/nginx/access.log
    中grep搜索‘Error 500’”。
  • 隔离变量：每次只改变一个变量。
  • 验证假设：首先验证配置和版本（例如，“任务1：验证当前架构”）。
  • 保留证据：保存特定的跟踪ID、日志时间戳或复现脚本。