关于 roblox-debugging-bugfix
这是一项面向 Roblox 项目的调试技能，要求先建立可重复的故障复现，再提出假设或修改代码。它使用 Luau 执行和 Studio 工具指导排查，并要求进行最小修复与回归验证。
主要功能
- 01建立快速且可重复的故障复现
- 02探测前排列可证伪假设
- 03检查脚本、实例和运行时输出
- 04实施最小修复并清除调试代码
- 05通过持久回归检查验证修复
适用场景
- 01排查间歇性游戏故障
- 02追踪客户端与服务器状态不一致
- 03调试 UI 更新和事件连接
- 04针对已复现问题验证修复效果
安装
复制下面的命令，在终端中运行。
npx skills add https:/安装后在 Claude Code 中输入/roblox-debugging-bugfix确认已加载。
详细介绍
Roblox 调试修复
目标
不靠猜测，从症状推进到经过验证的修复。对于棘手或偶发的 bug，请遵循以下流程；只有在能说明理由时才跳过某个阶段。
阶段 1 — 先建立复现循环（这是关键）
只要有快速、可重复的通过／失败信号，其他事情都是机械操作。请在此投入大量精力。动手修复前，尽可能积极、大胆地尝试各种方法。
建立复现循环的方法，大致按优先顺序排列：
- Studio 游戏测试复现 — 在 Play 模式下执行能触发 bug 的具体步骤；观察
get_console_output。 execute_luau测试框架 — 使用测试输入直接调用可疑的服务／模块函数并断言结果，而不是点击遍历整个游戏。- 针对性场景 — 创建能触发代码路径的最小实例／状态（一个部件、一个远程对象、一个玩家状态）。
- 重放捕获的负载 — 保存行为异常时的真实远程负载／数据配置，并在隔离环境中重新传入代码路径。
让循环快速、精准且确定：聚焦具体症状，固定任何随机因素／时间因素，并删去无关设置。确定性检查耗时 2 秒，胜过不稳定、耗时 30 秒的检查。
**偶发 bug：**目标是提高复现率，而不是一次就干净地复现。多次循环触发流程，增加压力，缩小时间窗口。复现时有 50% 几率出问题的 bug 是可以调试的；继续提高复现率，直到稳定为止。
如果确实无法建立复现循环，就停下来说明情况——列出你尝试过的方法，并向用户索取环境信息、捕获的材料（日志转储、带时间戳的屏幕录制、出问题的数据），或添加临时检测的许可。没有复现循环时，不要推测。
阶段 2 — 复现
运行循环。确认它能产生用户描述的故障（而不是相似的其他问题），能够重复复现，并且已捕获确切症状，以便稍后验证。
阶段 3 — 提出假设
测试前提出 3–5 个按优先级排序、可证伪的假设——一次只检验一个假设的调试方式容易锚定在最初的猜测上。每个假设都要说明预测：“如果 X 是原因，那么改变 Y 就能让问题消失。”先将排序后的列表展示给用户，再开始探查；用户往往会立即重新排序（“我们刚改过第 3 项”）。如果用户暂时不在线，就按你的排序继续。
阶段 4 — 加入检测
每次探查对应一个假设；一次只改变一个变量。优先检查实际值（inspect_instance、execute_luau），而不是刷屏式输出日志。给每条临时日志都加上唯一前缀，例如 [DEBUG-a4f2]，这样只需运行一次 script_grep 就能清理干净。对于性能回退，先测量（计时／os.clock、MicroProfiler、实例数量），再用二分法定位——日志通常不是合适的工具。
阶段 5 — 修复并检查回归
使用 multi_edit 进行最小且安全的修复。宣布完成前，将复现流程转化为持久的检查，前提是存在合适的验证切入点（execute_luau 断言或有文档记录的游戏测试步骤）。如果没有合适的切入点，这本身就是一项发现——请注明当前架构无法有效锁定该 bug。
调试循环（操作步骤）
- 记录用户可见的症状和预期行为。
- 尽可能在 Play 模式中复现。
- 阅读
get_console_output。 - 使用
script_grep和script_search搜索。 - 使用
script_read阅读相关脚本。 - 使用
search_game_tree和inspect_instance检查相关实例。 - 使用
multi_edit进行最小且安全的修复。 - 重新运行复现流程，再次检查控制台输出。
- 删除所有
[DEBUG-...]检测代码（使用script_grep搜索前缀）。
常见 bug 类型
- 客户端／服务端状态不匹配。
- 远程负载信任问题。
- 服务端状态改变后，UI 未更新。
- 事件连接重复创建或从未断开。
- DataStore 加载／保存竞态。
- 对象路径已重命名或缺失。
- Play 模式下 DataModel 不匹配。
- 角色生成、UI 创建和服务端初始化之间的竞态。
修复规则
- 优先从根本原因入手修复，而不是采取防御性静默处理。
- 不要在未记录上下文的情况下吞掉错误。
- 在信任边界附近添加验证。
- 不要在 Bug 修复中夹带无关的重构。
- 确认没有新增控制台错误。
输出
返回：
- 复现步骤。
- 根本原因（说明哪项假设已被证实）。
- 已更改的文件/脚本。
- 已执行的验证。
- 残余风险。
- 事后复盘：什么本可以避免此 Bug？如果答案涉及架构问题（缺少良好的测试接缝、客户端/服务端边界混乱、存在隐式耦合），请推荐
roblox-code-maintenance-refactor或roblox-luau-architecture——在修复完成后，而不是之前。
下一步
使用 roblox-playtest-qa 验证修复仍然有效（如果涉及 UI/移动端，也使用 roblox-mobile-playtest）。如果事后复盘发现了架构方面的技术债，请交接给 roblox-luau-architecture 或 roblox-code-maintenance-refactor。返回 roblox-game-development-lifecycle 以继续推进路线图。