# Debug

> 调试诊断 — 结构化错误定位、根因分析、最小化修复与回归验证。当用户报告运行时错误 / stacktrace / 测试失败 / 脚本异常 / testing 阶段缺陷清单待修复时使用此 skill。本 skill 处理已知症状的根因定位与最小修补；新功能开发循环由 tdd-engine 负责，新测试编写由 testing 负责。

- Skill: `lync-cyber/debug` (Agent Skill, multi-file: 8 files)
- Install (CLI): `npx skillmds@latest add lync-cyber/debug`
- Raw SKILL.md: https://api.skillmd.com/api/skills/lync-cyber/debug/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: lync-cyber (https://skillmd.com/u/lync-cyber)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/lync-cyber/debug

---


# 调试诊断 (debug)

## 能力边界
- 能做: 分析错误/stacktrace、定位根因、应用最小修复、回归验证、检查同类问题
- 不做: 功能开发、性能优化、架构重构、需求变更

## 输入规范
调用方提供以下信息（至少一项）:
- 错误信息 / stacktrace
- 触发命令或复现步骤
- 期望 vs 实际行为描述

## 输出规范
- 修复后的文件（就地修改）
- 回归验证结果（测试通过或命令成功）
- 执行摘要: 根因 + 修复措施 + 验证结果

## 操作指令

> **语言细则**: 根据 `framework.json` `project.languages`，按需载入本 skill `references/lang-<lang>.md`（仅 active 语言，逐个 Read），获取对应语言的调试诊断细则（调试器使用、traceback 解读、日志实践、运行时问题定位）。与本 skill `references/debug-patterns.md`（scan-similar 的特征模式范例）分工：lang-<lang>.md 为完整调试细则，debug-patterns 为同类扫描的模式库。

### 指令1: 完整调试流程 (full)

适用于: 收到错误报告，需要从零开始诊断和修复。

**Step 1: 复现与信息收集**
1. 解析错误信息，提取关键信号: 文件路径、行号、异常类型、错误消息
2. 如有复现命令，执行以确认问题可复现
3. 如错误信息不完整（缺少 stacktrace 或文件路径），通过 AskUserQuestion 请求补充（每批问题数不超过 MAX_QUESTIONS_PER_BATCH）

**Step 2: 定位根因**
1. 从 stacktrace 最内层帧开始，Read 相关文件和行号
2. 向调用链上游追溯，理解数据流和控制流
3. 识别根因类别:
   - **编码/环境**: 字符编码、路径分隔符、平台差异、语言运行时版本
   - **数据/类型**: 空值、类型不匹配、格式解析错误、边界条件
   - **依赖/配置**: 缺失依赖、版本不兼容、配置错误
   - **逻辑**: 算法错误、状态管理、竞态条件
4. 形成根因假设并通过代码阅读或小范围测试验证

**Step 3: 应用修复**
1. 使用 Edit 工具应用最小化修复（只改必要的代码）
2. 如修复模式适用于多个文件，使用 Grep 扫描同类问题并一并修复
3. 确保修复不改变公共接口行为（如需改变，返回 needs_input）

**Step 4: 回归验证**
1. 重新执行触发错误的命令，确认问题已修复
2. 运行相关测试套件（如有），确认未引入新失败
3. 如无自动化测试，手动验证关键路径

**Step 5: 总结**
1. 输出执行摘要: 根因（一句话）、修复措施、验证结果、同类修复（如有）

### 指令2: 快速修复 (quick-fix)

适用于: 根因已明确（如用户已定位到具体文件和行），剩余动作仅为应用修复和验证。

**Step 1**: Read 相关文件确认问题
**Step 2**: 应用修复（Edit）
**Step 3**: Grep 检查同类问题并一并修复
**Step 4**: 回归验证（Bash 运行命令/测试）
**Step 5**: 输出摘要

### 指令3: 同类扫描 (scan-similar)

适用于: 已修复一个问题，需要检查整个项目中是否存在同类问题。

**Step 1**: 从已修复的问题中提取特征模式（如未显式声明编码的文件读写、未转义的正则元字符；语言特定示例见 [debug-patterns.md](references/debug-patterns.md)）
**Step 2**: 使用 Grep 在项目范围内搜索该模式
**Step 3**: 逐一检查匹配项，判断是否存在同类问题
**Step 4**: 对确认存在问题的文件应用修复
**Step 5**: 汇总扫描结果: 检查了 N 个文件，修复了 M 个

## 常见问题模式库
语言/平台特定的症状—修复对照（Python/Windows 等）见 [debug-patterns.md](references/debug-patterns.md)，新增语言在该文档增条。

## Anti-Patterns
- 禁止: 修复表面 symptom 而不查 root cause —— 让最近一次报错消失不等于修了 bug，root_cause 可能在两层调用栈以上
- 禁止: 改测试让它通过而非改实现 —— 测试是契约，把红灯绿掉是把契约改成了已坏状态的快照
- 禁止: 静默 `catch + pass` 吞异常 —— 信号被埋掉后续 debug 复杂度指数上升
- 避免: 一次改多个变量再跑验证 —— 失败时无法定位是哪个改动生效，回到二分查找

## 效率策略
- stacktrace 最内层帧优先 — 80% 的问题在最内层 1-2 帧
- 修复前先 Grep 同类 — 避免修一个漏一个，减少反复调试
- 就地验证 — 修复后立即运行，不等到所有文件都改完