Code Debugger

Overview

在修改代码前先建立完整上下文关系网络，最小化变更并记录可追溯的调试文档，确保修复可验证、可回滚、可复盘。

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

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

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

Workflow

1. 上下文构建

• 解析用户任务，识别涉及模块与边界。
• 使用 rg/文件浏览定位入口与相关模块，梳理调用链、变量依赖和数据流向。
• 检查 .debug/：若已有同模块记录则加载；若模块不同则新建，避免混杂上下文。
• 评估影响范围与潜在回归点，只改必要代码。

2. 问题定位与实施

• 基于上下文网络定位根因，给出 1-2 个方案并评估风险。
• 采用最小改动原则实施修复或增量功能，保持现有架构与风格一致。
• 添加必要的边界检查和错误处理。

3. 验证与记录

• 运行现有测试或提供明确的手动验证步骤。
• Debug-Checkfix 闭环（必选）：完成代码修改后，根据项目技术栈执行相应的自动检查（见下方「技术栈与推荐检查」），将「修复 → 检查 → 修正」形成闭环；检查结果纳入验证并写入 .debug/。
• 更新 .debug/ 记录：问题、根因、变更、验证（含 checkfix 结果）、影响评估。
• 根据反馈迭代修复与文档。

4. 文档同步与部署约束（必选）

• 前端功能变更：必须同步更新 docs/ 用户说明书，默认面向零基础用户，步骤写到可直接照做。
• 后端/API/环境变更：必须同步更新开发与部署文档，明确命令、执行顺序、预期输出、失败排查与回滚。
• 每次功能或环境更新后，必须检查既有部署指导是否需要联动修改（如 docs/DEPLOYMENT.md、docs/README.md）。

技术栈与推荐检查（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 记录。

文档写作标准（后端/部署）

• 读者假设：默认读者为首次接手该项目的开发者，不依赖口头传递。
• 必写要素：前置条件、环境准备、逐步命令、验证方式、常见错误处理、回滚方案。
• 文档目标：开发者仅靠文档即可完成开发、部署、验证与故障定位。

.debug 文档规则

目录与命名

• 统一放在 .debug/。
• 每个功能模块单独一份：.debug/<module>-debug.md。

模块隔离

• 交叉度计算：(共享函数数 + 共享变量数 + 共享数据结构数) / 总组件数。
• 交叉度 > 30%：合并到现有文档。
• 交叉度 < 30%：新建文档。

推荐模板（精简版）

# [模块] Debug 记录

## 元信息
- 模块名称:
- 创建时间:
- 最后更新:
- 相关文件:
- 依赖模块:
- 用户说明书路径（涉及前端功能时）:
- 开发/部署文档路径（涉及后端或环境时）:

## 运行上下文与测试规则（首次确认后填写，后续优先读取此处，不再反复询问）
- 运行环境: [本机 Windows / WSL / NAS-Samba+SSH 或远程]
- SSH 方式（若远程）: [如 ssh nas、ssh user@host]
- 远程项目路径（若远程）: [如 /mnt/dev/xxx]
- 验证/Checkfix 执行方式: [如：在本地终端执行 / ssh nas "cd /mnt/dev/xxx && ..."]

## 上下文关系网络
- 文件结构
- 函数调用链
- 变量依赖图
- 数据流向

## Debug 历史
### [YYYY-MM-DD HH:MM] [任务标题]
- 问题描述
- 根因定位
- 解决方案
- 代码变更（文件/函数）
- 验证结果
- 影响评估
- 文档更新（新增/修改的 docs 文件与更新点）

## 待追踪问题
## 技术债务记录
## 架构决策记录（可选）

Response Format (recommended)

在开始与完成任务时，优先用以下结构输出关键信息：

## 任务分析
## 开发环境/运行上下文
[本机 / WSL / NAS-Samba+SSH 或远程；若远程，SSH 方式与项目路径如 /mnt/dev/xxx]
## 上下文探索
## .debug 文档状态
## 执行方案
## 更新记录