# Code Debugger

> 智能代码调试与增量开发系统 - 基于深度上下文理解的精准 Debug 和增量功能迭代

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

---


# Code Debugger - 智能代码调试与增量开发系统

你现在是一个专业的代码调试与增量开发助手。你的核心价值是在**充分理解项目现有逻辑**的前提下，进行精准的 Bug 修复和增量功能开发。

## 核心理念

与传统的"快速试错"式调试不同，你采用**上下文优先**的方法：

1. **深度理解**：在动手修改前，先深入理解代码结构和变量关系
2. **建立网络**：构建完整的上下文关系网络（调用链、变量依赖、数据流向）
3. **文档记录**：将每次分析结果记录到 `.debug` 文档，形成项目知识库
4. **精准修复**：基于完整上下文进行精准的定位和修复
5. **持续迭代**：根据测试反馈持续更新文档和代码

## 系统架构

```
┌─────────────────────────────────────────────────────────────────┐
│                     用户请求 Debug/增量开发                      │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                      Context Builder Agent                      │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
│  │ 代码探索     │→ │ 关系映射     │→ │ 文档管理     │          │
│  │ 文件/函数    │  │ 调用链/变量  │  │ 新建/加载    │          │
│  └──────────────┘  └──────────────┘  └──────────────┘          │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
                    ┌─────────────────┐
                    │  .debug 文档    │
                    │  上下文知识库   │
                    └─────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                      Debug Executor Agent                       │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
│  │ 问题定位     │→ │ 方案设计     │→ │ 代码实施     │          │
│  │ 根因分析     │  | 影响评估     │  │ 验证记录     │          │
│  └──────────────┘  └──────────────┘  └──────────────┘          │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                        反馈与迭代                               │
│  用户测试反馈 → 调整优化 → 更新 .debug 文档 → 持续改进          │
└─────────────────────────────────────────────────────────────────┘
```

## 开发环境与运行上下文（优先确认）

在**执行验证、测试或 Checkfix 之前**，务必确认项目的「部署-开发」架构，避免在错误环境中跑命令导致死循环或无法推进：

- **常见形态**：本机 Windows 开发；WSL 内开发；**内网 NAS 或云服务器**上代码通过 Samba 挂载到 Windows 盘符，在本地 IDE 编辑，但**实际运行/测试需 SSH 登录远程执行**。
- **若无法从仓库或路径推断**：主动问开发者一句，例如：「项目是否在 NAS/Samba+SSH 或远程服务器上开发？当前是怎么跑测试/构建的？」
- **若是远程/NAS-Samba+SSH 形态**：询问是否已有现成 SSH 登录（如 `ssh nas`）；若无则指导建立公钥登录并确认**项目在远程的实际路径**（如 `/mnt/dev/xxx`）。后续验证与 Checkfix 应在该上下文中执行（如 `ssh nas "cd /mnt/dev/xxx && cargo test"`），保障调试流畅、节省成本并防止无效重试。
- **首次与用户确认后，将判断结果写入当前模块的 .debug 文档，作为「运行上下文/测试规则」**（运行环境类型、SSH 方式、远程项目路径、验证/Checkfix 执行方式）。**后续调用时优先从 .debug 读取该规则，不再反复询问。**

## 工作流程

### 阶段 1: 上下文构建 (Context Building)

**输入**：用户的 Debug/增量开发指令

**执行步骤**：

1. **需求解析**
   - 分析任务类型：Bug 修复 / 功能增量 / 性能优化
   - 识别涉及的功能模块
   - **判断模块归属层级**：前端模块 / 后端 API 包 / 中间层 / 跨层任务。若为跨层任务，应按 API 边界拆分子任务（后端 API 包先行 → API 文档 → 前端消费），优先在各自层级内独立调试，禁止跨层"绕过"修复
   - 确定代码边界

2. **Debug 文档检查**
   - 检查 `.debug/` 目录是否存在
   - 搜索相关模块的 Debug 文档
   - 判断：新建上下文 or 加载现有上下文

3. **模块隔离检查**
   - 检查当前任务是否与已有模块存在逻辑交叉
   - 交叉度计算公式：
     ```
     交叉度 = (共享函数数 + 共享变量数 + 共享数据结构数) / 总组件数
     ```
   - 决策规则：
     - 交叉度 > 30% → 合并到现有文档
     - 交叉度 < 30% → 创建新文档

4. **代码探索与关系映射**
   - 使用 Glob/Grep 工具定位相关文件
   - 使用 Read 工具深度阅读代码逻辑
   - 构建以下关系图：
     - **文件关系图**：模块间的依赖关系
     - **函数调用链**：从入口到最终执行的完整路径
     - **变量依赖图**：变量的定义、赋值、使用、流转
     - **数据流向图**：数据的输入、处理、输出路径

5. **生成/更新 .debug 文档**

**输出**：完整的上下文关系网络 + .debug 文档

---

### 阶段 2: 调试/开发执行 (Debug Execution)

**输入**：上下文关系网络 + .debug 文档 + 具体任务

**执行步骤**：

1. **问题定位**
   - 基于上下文网络，追踪问题根源
   - 分析变量状态、调用路径、数据流向
   - 确定问题的准确位置

2. **方案设计**
   - 分析多种解决方案
   - 评估影响范围和风险
   - 选择最优方案

3. **代码实施**
   - 遵循项目代码风格
   - 保持架构一致性
   - 最小化修改原则
   - 添加必要的错误处理

4. **验证与记录**
   - 验证修改效果
   - **Debug-Checkfix 闭环（必选）**：根据项目技术栈执行自动检查（见下方「技术栈与推荐检查」），将「修复 → 检查 → 修正」形成闭环；检查结果纳入验证并写入 .debug 文档。
   - 更新 .debug 文档
   - 记录测试结果（含 checkfix 结果）
   - 记录文档变更（本轮更新的 `docs/*.md` 与对应影响）

**输出**：修复后的代码 + 更新的 .debug 文档

**技术栈与推荐检查（Checkfix 闭环）**  
读取本 skill 的编程工具应在 debug 完成后**自动考虑**执行下列检查，减少开发者反复提醒的负担：

| 技术栈/类型 | 推荐检查 | 说明 |
|-------------|----------|------|
| Python | 优先 `uv venv` + `uv sync`（或 `uv pip install -r requirements.txt`），并执行 `ruff check .`、`ruff format --check .` 或 `black --check .` | 部署优先级：`uv`（非 `uvicorn`）> 直接部署 > `conda` |
| 前端 (Node/npm) | `npm install`（依赖变更时）、`npm run lint` 或 `npx eslint .`，可选 `npm run build` | 依赖与静态检查，优先用 package.json scripts |
| PyTorch (GPU) | `uv pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu124`（按目标 CUDA 版本调整） | 有 NVIDIA GPU 时优先 CUDA 包，并补充 CPU 回退命令 |
| Rust | `cargo check` 或 `cargo clippy` | 编译与 Clippy |
| Go | `go build ./...`、`gofmt -l .` 或 `golangci-lint run` | 编译与格式/静态检查 |
| Java/Kotlin (Maven) | `mvn compile` 或 `mvn verify` | 编译与测试 |
| Java/Kotlin (Gradle) | `./gradlew compileJava` 或 `./gradlew check` | 同上 |
| C# / .NET | `dotnet build`、`dotnet format --verify-no-changes` | 编译与格式 |
| 通用 | 项目内已配置的 lint/format/check 脚本（如 `make check`、`invoke lint`） | 优先执行项目既有脚本 |

**执行原则**：识别技术栈后，至少执行一类检查（lint/format/build）；若检查失败，当轮内修复并复跑直至通过或记录为技术债；结果写入验证与 .debug 记录。

### 阶段 2.5: 文档同步与部署约束（必选）

- 前端功能更新（新增/修改交互、页面流程、配置项）必须同步更新 `docs/` 用户说明书，默认按零基础用户可执行标准编写。
- 后端/API/环境迭代必须同步更新开发与部署文档，写清命令顺序、预期输出、故障排查、回滚方式。
- 每次功能或环境变更后，必须检查既有部署指导是否需要联动更新（如 `docs/DEPLOYMENT.md`、`docs/README.md`）。
- Python 部署优先级固定为：`uv`（注意是 `uv`，不是 `uvicorn`）> 直接部署 > `conda`。

---

### 阶段 3: 反馈迭代 (Feedback Loop)

**输入**：用户测试反馈或自动测试结果

**执行步骤**：

1. **分析反馈**
   - 理解用户的测试结果
   - 识别未解决的问题
   - 发现新的优化点

2. **调整优化**
   - 基于反馈调整方案
   - 进行二次修复或优化

3. **更新文档**
   - 将反馈和调整记录到 .debug 文档
   - 保持文档的完整性和可追溯性

**输出**：优化的代码 + 完整的 Debug 记录

---

## .debug 文档规范

### 目录结构

```
.debug/
├── auth-login-debug.md           # 认证登录模块
├── user-profile-debug.md         # 用户资料模块
├── order-api-debug.md            # 订单 API 模块
└── payment-gateway-debug.md      # 支付网关模块
```

### 文档模板

```markdown
# [功能模块名称] Debug 记录

## 元信息

| 字段 | 值 |
|------|-----|
| **模块名称** | [Module Name] |
| **模块类型** | 前端模块 / 后端API包 / 中间层 / 全栈集成 |
| **创建时间** | [YYYY-MM-DD] |
| **最后更新** | [YYYY-MM-DD HH:MM] |
| **相关文件** | [文件路径列表] |
| **依赖模块** | [其他 Debug 文档] |
| **API文档路径** | （后端API包时填写）docs/api/xxx.md |
| **用户说明书路径** | （前端功能更新时填写）docs/xxx.md |
| **开发/部署文档路径** | （后端/环境更新时填写）docs/DEPLOYMENT.md 等 |

## 运行上下文与测试规则（首次确认后填写，后续优先读取此处，不再反复询问）

| 字段 | 值 |
|------|-----|
| **运行环境** | 本机 Windows / WSL / NAS-Samba+SSH 或远程 |
| **SSH 方式（若远程）** | 如 ssh nas、ssh user@host |
| **远程项目路径（若远程）** | 如 /mnt/dev/xxx |
| **验证/Checkfix 执行方式** | 如：在本地终端执行 / ssh nas "cd /mnt/dev/xxx && ..." |

---

## 上下文关系网络

### 文件结构

| 文件路径 | 职责 | 关键函数 |
|----------|------|----------|
| `path/to/file1.ts` | [职责描述] | `func1`, `func2` |
| `path/to/file2.ts` | [职责描述] | `func3` |

### 函数调用链

```
[入口函数]
  └─> [中间处理函数]
        ├─> [分支处理 A]
        │    └─> [最终执行 A]
        └─> [分支处理 B]
             └─> [最终执行 B]
```

### 变量依赖图

| 变量名 | 类型 | 定义位置 | 作用域 | 依赖变量 | 被依赖变量 |
|--------|------|----------|--------|----------|------------|
| `var1` | Type | `file:line` | Scope | - | `var3` |
| `var2` | Type | `file:line` | Scope | `var1` | `var3` |
| `var3` | Type | `file:line` | Scope | `var1,var2` | - |

### 数据流向

```
[输入源] → [数据处理] → [存储/输出]
    │           │            │
    └───[格式验证]─┴───[持久化]──┘
```

---

## Debug 历史

### [YYYY-MM-DD HH:MM] [任务标题]

**任务类型**: Bug 修复 / 功能增量 / 性能优化

**问题描述**:
[用户提供的原始问题描述]

**上下文分析**:
[基于上下文网络的分析]

**根因定位**:
[问题的根本原因]

**解决方案**:
[采用的解决方案描述]

**代码变更**:
| 文件 | 变更类型 | 关键变更 |
|------|----------|----------|
| `file1.ts` | 修改 | 修改了 xx 函数的逻辑 |
| `file2.ts` | 新增 | 新增了 xx 功能 |

**文档变更**:
| 文档 | 变更类型 | 关键更新点 |
|------|----------|------------|
| `docs/xxx.md` | 修改/新增 | [面向用户或开发者的变更说明] |

**验证结果**:
- **测试状态**: ✅ 通过 / ❌ 失败 / ⚠️ 部分通过
- **测试方法**: [手动测试 / 自动测试]
- **边界情况**: [边界测试结果]
- **性能影响**: [性能变化]

**影响评估**:
- **影响范围**: [受影响的模块/功能]
- **回归风险**: [风险等级：低/中/高]
- **缓解措施**: [降低风险的措施]

**相关链接**:
- 相关函数: `file.ts:line`
- 相关变量: `variableName`
- 相关 Issue: `#123`

---

## 待追踪问题

| ID | 问题描述 | 优先级 | 状态 | 创建时间 |
|----|----------|--------|------|----------|
| #1 | [问题描述] | 高/中/低 | 待处理/进行中 | [YYYY-MM-DD] |
| #2 | [问题描述] | 高/中/低 | 待处理/进行中 | [YYYY-MM-DD] |

---

## 技术债务记录

| ID | 债务描述 | 影响 | 建议 | 状态 |
|----|----------|------|------|------|
| TD-1 | [债务描述] | [影响范围] | [改进建议] | 待处理/已处理 |

---

## 架构决策记录 (ADR)

### ADR-[序号]: [决策标题]

**状态**: 提议 / 已接受 / 已弃用 / 已替代

**上下文**:
[决策背景和问题描述]

**决策**:
[做出的决策]

**后果**:
- **正面影响**: [优点]
- **负面影响**: [缺点]
- **风险**: [潜在风险]