企业官网建设流程全解析

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.yaml），bug-report属于utility类别、优先级为low，测试规格文件位于CCGS Skill Testing Framework/skills/utility/bug-report.md。根据 质量评分卡 中 utility 类别指标 U1/U2 的要求，这类技能必须通过 7 项静态结构检查，且不触发导演门禁（Director Gate）——Bug 上报是运营性工具，不设导演审批环节。

Phase 1：参数解析——四种模式的入口判定

技能执行的第一步是根据调用参数判定运行模式：

边界行为：如果调用时完全没有提供参数，技能必须先向用户索要 Bug 描述，不能凭空开始生成。这一"缺参即询问"的约定在 hotfix 测试规格 中也有对应体现——信息不足时先提问、不行动，是这套体系的一贯原则。

Phase 2A：描述模式——从一句话到完整报告

描述模式按三步推进：

1. 解析描述中的关键信息：发生了什么（what broke）、何时发生（when）、如何复现（how to reproduce）、预期行为是什么（expected behavior）。
2. 代码库检索补充上下文：使用 Grep/Glob 搜索相关文件，推断受影响系统与疑似文件清单。
3. 起草报告：按固定模板输出，模板内容见下一节。

全字段 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 / Trivial），Priority采用 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.md；slug 由标题净化生成，是实现细节、不纳入断言。

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，提取复现步骤与预期结果，然后执行三步验证：

1. 重跑复现步骤：用 Grep/Glob 检查导致 Bug 的代码路径是否仍如描述存在；若修复已删除或修改该路径，记录变更内容。
2. 运行相关测试：若该 Bug 所属系统在tests/下有对应测试文件，通过 Bash 运行并汇报通过/失败。
3. 回归扫描：在代码库中 grep 是否出现导致该 Bug 的模式的新实例。

验证结论只有三种，且语义严格：

验证完成后，技能必须询问："May I updateproduction/qa/bugs/[BUG-ID].mdto set Status: Verified Fixed / Still Present / Cannot Verify?"——这是本仓库全局协作协议（见 CLAUDE.md 与 COLLABORATIVE-DESIGN-PRINCIPLE：Question → 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"协作协议

无论哪种模式产出的报告，落盘前都必须经过用户授权：

1. 向用户呈现完整的 Bug 报告草稿；
2. 询问："May I write this toproduction/qa/bugs/BUG-[NNNN].md?"
3. 同意则写入文件（必要时自动创建目录），判定COMPLETE——Bug 报告已归档；
4. 拒绝则在此停止，判定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].md；
• production/qa/bug-triage-*.md：triage 输出留档，用于追踪未结案清单；
• 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 管理体系的设计原则：

1. 结构化优先于叙事：固定的字段、量化的频率区间、编号复现步骤，保证报告能被其他 AI Agent 与人类无歧义地消费、排序与复现。
2. 验证是关闭的前提：VERIFIED FIXED → 关闭 是唯一合法路径，杜绝"宣称修复即关闭"。
3. 协作而非自治：每一次文件写入都经过 "May I write" 授权，用户始终掌握最终决定权——这正是 README.md 所声明的 "Collaborative, Not Autonomous" 哲学在缺陷管理上的体现。
4. 职责分离：上报（bug-report）、排期（bug-triage）、修复（hotfix + 程序员 Agent）、验证（bug-report verify + smoke-check）各司其职，任一层级不越界。
5. 可测试：技能行为被 测试规格 以 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