Claude Code Game Studios 结构化 Bug 报告技能实战指南从描述到修复验证的完整闭环【免费下载链接】Claude-Code-Game-StudiosTurn Claude Code into a full game dev studio — 49 AI agents, 72 workflow skills, and a complete coordination system mirroring real studio hierarchy.项目地址: https://gitcode.com/GitHub_Trending/cl/Claude-Code-Game-Studios本篇指南聚焦 Claude Code Game Studios 仓库中的/bug-report技能.claude/skills/bug-report/SKILL.md它在 49 个 Agent、72 个技能构成的虚拟游戏工作室协作体系中承担缺陷证据沉淀的职责。读完本文你将掌握四种调用模式描述 / 分析 / 验证 / 关闭的完整操作流程、全字段 Bug 报告模板的填写规范、以及与/bug-triage、/hotfix、qa-tester等技能和 Agent 的联动方式从而在 AI 驱动的游戏开发管线中建立一条可复现、可验证、可追溯的缺陷管理链路。技能定位为什么游戏开发管线需要结构化 Bug 报告在 Claude Code Game Studios 中一个 Claude Code 会话被组织成一个完整的游戏工作室导演层Director守护愿景、部门主管Lead拥有领域决策权、专员Specialist负责具体执行。项目根 README.md 明确列出了 QA Testing 与 Production 两类相关技能组其中/bug-report与/bug-triage、/smoke-check、/hotfix共同构成缺陷从发现到关闭的完整生命周期。/bug-report的核心价值在于把一句零散的口头描述游戏在进 BOSS 场景时崩了转化为一份结构化、可复现、带严重度评估与上下文信息的标准文档。其 frontmatter 定义SKILL.md如下--- name: bug-report description: Creates a structured bug report from a description, or analyzes code to identify potential bugs. Ensures every bug report has full reproduction steps, severity assessment, and context. argument-hint: [description] | analyze [path-to-file] user-invocable: true allowed-tools: Read, Glob, Grep, Write ---从技能注册信息看CCGS Skill Testing Framework/catalog.yamlbug-report属于utility类别、优先级为low测试规格文件位于CCGS Skill Testing Framework/skills/utility/bug-report.md。根据 质量评分卡 中 utility 类别指标 U1/U2 的要求这类技能必须通过 7 项静态结构检查且不触发导演门禁Director Gate——Bug 上报是运营性工具不设导演审批环节。Phase 1参数解析——四种模式的入口判定技能执行的第一步是根据调用参数判定运行模式参数形态模式职责无关键字 一段描述Description Mode描述模式从描述生成结构化 Bug 报告analyze [path]Analyze Mode分析模式读取目标文件并识别潜在 Bugverify [BUG-ID]Verify Mode验证模式确认已上报的修复是否真正解决 Bugclose [BUG-ID]Close Mode关闭模式将已验证的 Bug 标记为关闭并写入解决记录边界行为如果调用时完全没有提供参数技能必须先向用户索要 Bug 描述不能凭空开始生成。这一缺参即询问的约定在 hotfix 测试规格 中也有对应体现——信息不足时先提问、不行动是这套体系的一贯原则。Phase 2A描述模式——从一句话到完整报告描述模式按三步推进解析描述中的关键信息发生了什么what broke、何时发生when、如何复现how to reproduce、预期行为是什么expected behavior。代码库检索补充上下文使用 Grep/Glob 搜索相关文件推断受影响系统与疑似文件清单。起草报告按固定模板输出模板内容见下一节。全字段 Bug 报告模板# Bug Report ## Summary **Title**: [Concisetitle] **ID**: BUG-[NNNN] **Severity**: [S1-Critical / S2-Major / S3-Minor / S4-Trivial] **Priority**: [P1-Immediate / P2-Next Sprint / P3-Backlog / P4-Wishlist] **Status**: Open **Reported**: [Date] **Reporter**: [Name] ## Classification - **Category**: [Gameplay / UI / Audio / Visual / Performance / Crash / Network] - **System**: [Which game system is affected] - **Frequency**: [Always / Often (50%) / Sometimes (10-50%) / Rare (10%)] - **Regression**: [Yes/No/Unknown -- was this working before?] ## Environment - **Build**: [Version or commit hash] - **Platform**: [OS, hardware if relevant] - **Scene/Level**: [Where in the game] - **Game State**: [Relevant state -- inventory, quest progress, etc.] ## Reproduction Steps **Preconditions**: [Required state before starting] 1. [Exact step 1] 2. [Exact step 2] 3. [Exact step 3] **Expected Result**: [What should happen] **Actual Result**: [What actually happens] ## Technical Context - **Likely affected files**: [List of files based on codebase search] - **Related systems**: [What other systems might be involved] - **Possible root cause**: [If identifiable from the description] ## Evidence - **Logs**: [Relevant log output if available] - **Visual**: [Description of visual evidence] ## Related Issues - [Links to related bugs or design documents] ## Notes [Any additional context or observations]模板设计要点解读模板的价值不在字段数量而在每类字段服务于一个明确的决策环节Summary 区Severity采用 S1–S4 四级Critical / Major / Minor / TrivialPriority采用 P1–P4 四级Immediate / Next Sprint / Backlog / Wishlist。严重度描述影响本身优先级决定排期两者分离正是 bug-triage 测试规格 中按CRITICAL → HIGH → MEDIUM → LOW排序的输入基础。Classification 区Frequency给出量化区间Always / Often 50% / Sometimes 10–50% / Rare 10%避免偶尔崩一下这类无法排期的模糊表述Regression字段Yes/No/Unknown直接回答这是不是回归缺陷为修复优先级提供关键权重。Environment 区Build版本号或 commit hash、Platform、Scene/Level、Game State存档进度、任务状态等四要素保证了其他工程师或 AI Agent 能在不追问的前提下复现现场。Reproduction Steps 区Preconditions 编号步骤 Expected Result/Actual Result对照是全模板中最不可省略的部分——bug-triage 会专门把缺少复现步骤的报告标记为NEEDS REPRO INFO。Technical Context 区由 Grep/Glob 检索得出的Likely affected files、Possible root cause把现象层与代码层连接起来是后续verify与hotfix直接引用的定位线索。Evidence 区日志输出与视觉证据描述供 QA 复测与验收时对照。描述模式与测试规格的一致性配套的 测试规格bug-report.md从 5 个用例固化了行为契约其中与描述模式直接相关的关键断言包括7 个必填字段缺一不可Title、Repro Steps、Expected Behavior、Actual Behavior、Severity、Affected System(s)、Build/Version。初始描述缺字段时技能必须逐项追问补齐每缺一项至少一次针对性提问直到全部字段齐备才允许定稿规格 Case 2。崩溃类缺陷自动识别为 CRITICAL规格 Case 1输入Game crashes when player enters the boss arena输出 Title、严重度判定、复现步骤确认、文件写入一条龙。多系统 Bug 合并为单报告规格 Case 4例如存档系统冻结且 UI 不显示通关界面应识别出 Save System 与 UI 两个受影响系统写入同一份报告而非拆成两份严重度取影响最大组件的等级存档冻结涉及数据丢失风险 → HIGH 或 CRITICAL。重复报告检查规格 Case 3落盘前扫描既有报告若发现相似条目如Audio randomly stops working对已有的 audio-cut-out 报告必须先提示用户选择链接为重复或仍然新建不得擅自合并或删除。文件命名约定bug-[date]-[slug].md如bug-2026-04-06-game-crashes-boss-arena.mdslug 由标题净化生成是实现细节、不纳入断言。Phase 2B分析模式——让 AI 主动审查代码找缺陷analyze [path]模式下技能读取指定文件并对每一处疑似缺陷生成一份使用上述模板的报告含触发场景与建议修复方案。测试规格与 qa-tester Agent 规格 共同给出了分析模式应重点检查的缺陷类型清单空引用null references例如存档序列化对可空槽位的处理——qa-tester 规格 Case 4 中 hotfix 修改了可空 item slot 序列化后回归清单需覆盖空槽、满/空混合槽数组、槽位数边界条件。差一错误off-by-one errors循环边界、数组索引等经典边界问题。竞态条件race conditions多系统并发访问同一状态时的不一致。未处理的边界情况unhandled edge cases损坏存档文件文件存在但内容非法等见 qa-tester 规格 Case 1 的 TC-SAVE-006。资源泄漏resource leaks对象、句柄、内存未释放。错误的状态转换incorrect state transitions状态机跳转缺失或非法转移。需要强调的职责边界分析模式只负责报告缺陷与建议修复不直接实施修复。这对应质量评分卡中 QA 类别指标 Q1产出工件而非代码与 qa-tester 规格 Case 2——当用户要求请修复存档丢失 Bug时qa-tester 必须拒绝写实现代码转而提供结构化 Bug 报告与回归测试用例修复由对应的 gameplay-programmer 完成。Phase 2C验证模式——修复必须被证明而不是被宣称验证模式是这套体系区别于随手改完就算修好的关键环节。技能读取production/qa/bugs/[BUG-ID].md提取复现步骤与预期结果然后执行三步验证重跑复现步骤用 Grep/Glob 检查导致 Bug 的代码路径是否仍如描述存在若修复已删除或修改该路径记录变更内容。运行相关测试若该 Bug 所属系统在tests/下有对应测试文件通过 Bash 运行并汇报通过/失败。回归扫描在代码库中 grep 是否出现导致该 Bug 的模式的新实例。验证结论只有三种且语义严格判定含义VERIFIED FIXED复现步骤不再产生 Bug且相关测试通过STILL PRESENTBug 按描述仍可复现修复未生效CANNOT VERIFY自动化检查无法得出结论需要人工试玩验证验证完成后技能必须询问May I updateproduction/qa/bugs/[BUG-ID].mdto set Status: Verified Fixed / Still Present / Cannot Verify?——这是本仓库全局协作协议见 CLAUDE.md 与 COLLABORATIVE-DESIGN-PRINCIPLEQuestion → Options → Decision → Draft → Approval在 Bug 流程中的具体落点任何文件写入前都必须征得用户同意。若判定为 STILL PRESENT则重新打开 Bug将 Status 改回 Open并建议重跑/hotfix [BUG-ID]。Phase 2D关闭模式——只有已验证的 Bug 才能关闭关闭模式设有一道硬性前置检查读取production/qa/bugs/[BUG-ID].md确认 Status 为Verified Fixed。如果状态是其他任何值技能必须停止并输出Bug [ID] must be Verified Fixed before it can be closed. Run/bug-report verify [BUG-ID]first.未经验证的修复不允许关闭——这是 SKILL.md 明示的底线规则与修复不能验证就仍是 Open的原则互为表里。关闭动作分两步第一步向 Bug 文件追加关闭记录Closure Record## Closure Record **Closed**: [date] **Resolution**: Fixed — [one-line description of what was changed] **Fix commit / PR**: [if known] **Verified by**: qa-tester **Closed by**: [user] **Regression test**: [test file path, or Manual verification] **Status**: Closed第二步将文件顶部的**Status**: Open更新为**Status**: Closed。随后检查production/qa/bug-triage-*.md——如果该 Bug 出现在未结案的 triage 报告中技能会提示Bug [ID] is referenced in the triage report. Run/bug-triageto refresh the open bug count. 这样保证缺陷统计不会因为关闭动作而过期失真。Phase 3保存报告——May I write协作协议无论哪种模式产出的报告落盘前都必须经过用户授权向用户呈现完整的 Bug 报告草稿询问May I write this toproduction/qa/bugs/BUG-[NNNN].md?同意则写入文件必要时自动创建目录判定COMPLETE——Bug 报告已归档拒绝则在此停止判定BLOCKED——用户拒绝写入。这一先展示草稿、再请求写入、写入才算完成的协议在 测试规格 中被固化为静态断言之一技能文件必须包含 May I write 协作语言、包含 COMPLETE 判定关键字、并在写入前征得同意。这正是该技能通过/skill-test static见 skill-test 测试规格7 项结构检查的前提——其中 Check 4 专门校验allowed-tools声明了 Write 却缺少 May I write 语言这一常见违规。Phase 4下一步联动——Bug 生命周期与相邻技能衔接保存报告后技能根据所处阶段给出下一步建议形成完整的缺陷闭环上报之后描述 / 分析模式运行/bug-triage将新 Bug 与既有未结案 Bug 一起重新排定优先级triage 规格 会读取production/bugs/全部报告按 CRITICAL → HIGH → MEDIUM → LOW 排序标记缺复现步骤与疑似重复项且全程只读、不写任何文件判定恒为 TRIAGED若严重度为 S1 或 S2运行/hotfix [BUG-ID]进入紧急修复流程hotfix 规格从 main 创建 hotfix 分支 → 定点修改 →/smoke-check验证 → 用户确认后合并判定 HOTFIX COMPLETE 或 HOTFIX BLOCKED。开发确认修复合入之后运行/bug-report verify [BUG-ID]——先验证再关闭修复不通过验证就永远是 Open。验证返回 VERIFIED FIXED 之后运行/bug-report close [BUG-ID]——写入关闭记录并更新状态运行/bug-triage刷新未结案计数把已关闭的 Bug 从活跃列表中移除。此外/smoke-check测试规格在实现与 QA 交接之间扮演守门员自动化测试失败或核心冒烟项不通过时判定 FAIL并明确提示修复前不要交接 QA——这与/bug-report的先验证后关闭共同构筑了质量双保险。而 qa-tester Agent 则在修复落地后负责产出定向回归清单只覆盖受影响系统的具体变更点而非全量回归并将测试证据按 coding-standards 规定写入对应位置为验证模式提供可运行的测试依据。约定目录与运行说明整个 Bug 流程围绕production/qa/下的运行期文件展开这些目录在仓库初始化时不一定存在当前仓库production/下仅有 session-state/由技能在获得用户授权后按需创建production/qa/bugs/BUG-[NNNN].md结构化 Bug 报告主目录命名建议采用bug-[date]-[slug].mdproduction/qa/bug-triage-*.mdtriage 输出留档用于追踪未结案清单tests/验证模式运行相关自动化测试的约定位置。使用方式在 Claude Code 会话中直接输入/bug-report加描述或/bug-report analyze src/gameplay/arena.gd、/bug-report verify BUG-0042、/bug-report close BUG-0042。技能允许的工具有限Read、Glob、Grep、Write不会越权编辑源码——修复始终由专门的程序员角色完成。设计要点小结从 SKILL.md 及全套配套规格中可以提炼出这套 Bug 管理体系的设计原则结构化优先于叙事固定的字段、量化的频率区间、编号复现步骤保证报告能被其他 AI Agent 与人类无歧义地消费、排序与复现。验证是关闭的前提VERIFIED FIXED → 关闭 是唯一合法路径杜绝宣称修复即关闭。协作而非自治每一次文件写入都经过 May I write 授权用户始终掌握最终决定权——这正是 README.md 所声明的 Collaborative, Not Autonomous 哲学在缺陷管理上的体现。职责分离上报bug-report、排期bug-triage、修复hotfix 程序员 Agent、验证bug-report verify smoke-check各司其职任一层级不越界。可测试技能行为被 测试规格 以 5 个用例 静态断言固化可通过/skill-test自动化校验保证技能本身的质量可回归。【免费下载链接】Claude-Code-Game-StudiosTurn Claude Code into a full game dev studio — 49 AI agents, 72 workflow skills, and a complete coordination system mirroring real studio hierarchy.项目地址: https://gitcode.com/GitHub_Trending/cl/Claude-Code-Game-Studios创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考