debug-code

name	debug-code
description	系统化代码调试技能，用于错误排查、故障诊断和问题修复。采用6步调试循环（计划→分析→修正→执行→检查→记录），支持多轮迭代调试，提供结构化的问题解决方法。适用于代码错误、运行时异常、性能问题、配置错误等各类调试场景。

代码调试技能 (Code Debug Skill)

版本: 1.0.0 | 基于: Copilot工作流系统 debug-system

🎯 技能概述

本技能提供系统化的代码调试能力，帮助 Copilot 执行专业的故障排查和问题修复。采用6步调试循环和人工确认机制，确保问题得到彻底解决。

核心能力

• 问题诊断: 系统化分析错误现象和根因
• 故障定位: 快速定位问题范围和关键链路
• 方案设计: 提供多种解决方案并评估风险
• 修复验证: 执行修复并验证解决效果
• 经验沉淀: 记录调试过程和经验教训

适用场景

• 当用户遇到"错误"、"异常"、"bug"、"故障"时
• 当用户需要"调试"、"排查"、"修复"问题时
• 当代码运行结果与预期不符时
• 当系统出现性能问题或配置错误时

📋 调试流程

7步标准流程

步骤1: 用户描述问题
    ↓
步骤2: AI解析并格式化
    ↓
步骤3: 用户确认信息 ← 暂停点
    ↓
步骤4: 创建调试环境
    ↓
步骤5: 初始化目录结构
    ↓
步骤6: 执行调试循环 ← 6步循环，可多轮
    ↓
步骤7: 完成检查决策 ← 暂停点

6步调试循环

每轮调试包含以下步骤：

6.1 📋 计划 (Plan)

• 确定本轮调试目标
• 分析上轮遗留问题
• 制定具体测试计划

6.2 🔍 分析 (Analyze)

• 复现问题现象
• 定位问题范围
• 确定关键链路
• 分析错误原因
• 可请求: 网络资源、环境信息、配置详情等

6.3 💡 修正 (Design)

• 设计解决方案
• 评估方案风险
• 选择最优策略

6.4 ⚙️ 执行 (Execute)

• 文件备份: 修改前先备份
• 实施代码修改
• 执行测试验证
• 用户协助: 可能需要用户手动执行测试

6.5 ✅ 检查 (Verify)

• 检查日志和输出
• 分析测试结果
• 确认问题解决状态
• 识别新出现问题

6.6 📊 记录 (Document)

• 更新调试文档
• 执行本轮归档
• 规划下轮目标
• 暂停点: 等待用户确认下轮目标

💡 调试原则

核心方法论

小工作集调试法

• 原理: 创建最小化独立测试环境
• 步骤: 简化环境 → 简化数据 → 精确监控 → 问题复现

官方文档验证法

• 原理: 通过官方文档确认API正确用法
• 步骤:
  1. 识别相关技术栈的官方文档
  2. 获取官方示例和最佳实践
  3. 对比当前代码与官方示例
  4. 基于官方标准修正代码

分层归档原则

• 🔴 Core: 核心解决方案文件
• 📚 Archive: 重要调试历程和文件备份
• 🗑️ Deprecated: 无效或被替代的文件

人机协作模式

• AI负责: 分析、建议、代码生成
• 用户负责: 测试执行、结果确认、决策选择

最佳实践

问题定位:

• 优先使用官方文档验证
• 创建独立测试脚本
• 对比不同版本差异
• 精确监控状态变化

测试策略:

• 使用简单数据作标准测试
• 建立操作前后状态对比
• 设计可重复执行的测试
• 保留完整测试日志

文档记录:

• 实时更新调试记录
• 详细记录失败原因
• 总结有效解决方案
• 归档可复用的方法

📁 目录结构

调试任务的标准目录结构：

debug/
├── workflow_archive/          # 已完成任务的工作流文档存档
└── 1_任务描述/                # 任务专用文件夹
    ├── INDEX.md              # 任务调试索引
    └── 1/                    # 调试轮次
        ├── README.md         # 调试记录
        ├── src/              # 工作文件
        ├── core/             # 核心解决方案
        ├── archive/          # 重要历程和文件备份
        ├── deprecated/       # 废弃文件
        ├── docs/             # 分析文档
        ├── logs/             # 测试日志
        └── files/            # 其他文件

buglist/                       # Bug管理目录
├── bug_list.md               # Bug清单
├── to_fix/                   # 待修复Bug文档
└── fixed/                    # 已解决Bug文档

🛠️ 模板使用

核心模板

模板	用途	使用时机
debug-round-record.md	调试记录	每轮调试开始时
bug-detail.md	Bug详细报告	发现新Bug时
debug-summary.md	调试总结	任务完成时
lessons-learned.md	经验总结	任务完成时

Bug管理模板

模板	用途
bug-list.md	Bug清单管理
task-index.md	任务索引

📝 使用示例

示例1: 运行时错误调试

用户请求:

我的Python程序运行时报错 "KeyError: 'config'"，在读取配置文件时出现

Copilot响应流程:

1. 解析问题：Python项目，KeyError异常，配置读取问题
2. 确认信息（暂停）
3. 创建调试环境
4. 执行调试循环：
   • 分析：检查配置文件结构和代码逻辑
   • 修正：设计解决方案（添加默认值/检查键存在）
   • 执行：实施修改
   • 验证：确认错误消失

示例2: 性能问题排查

用户请求:

这个函数执行很慢，处理1000条数据需要30秒

Copilot响应流程:

1. 分析：识别性能瓶颈
2. 定位：找出耗时操作
3. 设计：优化方案（算法改进/缓存/并行）
4. 验证：性能测试对比

示例3: 配置错误修复

用户请求:

程序连接数据库失败，但配置文件看起来是对的

Copilot响应流程:

1. 检查配置文件格式和内容
2. 验证连接参数（主机、端口、凭据）
3. 测试网络连通性
4. 对比官方文档确认配置正确性

⚠️ 注意事项

暂停点

流程中有多个必须暂停的点：

1. 步骤3: 确认问题信息后暂停
2. 6.6记录: 规划下轮目标后暂停
3. 步骤7: 完成决策前暂停

文件备份

修改任何文件前必须先备份：

Copy-Item "原文件" "archive/原文件_bak.扩展名"

用户协助

AI可能无法直接执行测试，此时需要：

• 请求用户手动执行测试
• 用户反馈格式："测试结果：[成功/失败]，现象：[描述]"

Bug管理

• 发现新Bug → 创建Bug文档到 to_fix/
• 解决Bug后 → 移动文档到 fixed/
• 更新 bug_list.md 状态

🔗 相关资源

• 完整模板目录
• 使用示例
• 原始 debug-system 文档