CCGS 结构化缺陷报告工作流：深入解析 `/bug-report` 技能的行为规范与测试体系

CCGS 结构化缺陷报告工作流：深入解析/bug-report技能的行为规范与测试体系

【免费下载链接】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

/bug-report是 Claude Code Game Studios（CCGS）技能框架中用于把一段随意的用户描述转写为结构化缺陷（Bug）报告的实用型技能。本文以其行为测试规格（bug-report.md）为核心骨架，逐层拆解它必须遵守的 7 个必填字段、追问补齐机制、查重与"May I write"协作协议、无导演门禁（Director Gate）的运维定位，并结合仓库中的 catalog、质量评分卡与上下游技能（/bug-triage、/hotfix）源码，说明该技能如何被自动化验证以及如何融入完整的缺陷生命周期。

一、技能定位：把口头描述变成可执行的缺陷单据

1.1 它解决什么问题

在 CCGS 中，/bug-report属于utility类别下的运营型技能，其核心职责只有一个：接收用户的自然语言缺陷描述，产出结构化的缺陷报告文档。它不负责修复缺陷，也不负责优先级排序——这两件事分别由/hotfix和/bug-triage承接。

从行为规格的 Skill Summary 看，技能的输出是一份包含以下 7 个必填字段的报告：

如果用户最初的描述缺少上述任意一个字段，技能不能直接开始写报告，而必须通过追问（follow-up questions）补全缺口后再产出草稿。这一"先补全、再成文"的约束是整个技能行为规范的基石。

1.2 输出位置与命名规范

• 报告统一写入production/bugs/bug-[date]-[slug].md
• 日期部分如2026-04-06
• slug由标题清洗（sanitize）而来，例如标题 "Game crashes when entering boss arena" 对应文件名bug-2026-04-06-game-crashes-boss-arena.md

在写入文件之前，技能必须发起 "May I write" 询问，并携带完整的文件路径（例如 "May I write toproduction/bugs/bug-2026-04-06-game-crashes-boss-arena.md?"），得到用户批准后才落盘。

1.3 无导演门禁：运营型技能的定位

与设计、评审类技能不同，/bug-report不使用任何 Director Gate。规格中明确写道：

None./bug-reportis an operational documentation skill. No director gates apply.

也就是说，缺陷报告是日常运营文档工作，不需要 creative-director、technical-director 等导演 Agent 介入审批。这与 quality-rubric.md 中utility类别的定义一致——该类技能只需要通过 7 项静态检查；如果某个 utility 技能确实会触发门禁，则门禁的全/简/单人模式逻辑也必须正确，但对/bug-report而言这一条不适用。

二、静态断言：技能结构可被自动校验

/bug-report的行为规格第一部分是 Static Assertions (Structural)，这部分由/skill-test static自动校验，无需任何测试夹具（fixture）：

• 具备必要的 frontmatter 字段：name、description、argument-hint、user-invocable、allowed-tools
• 至少包含 2 个阶段（phase）标题
• 包含结论关键词COMPLETE
• 在写报告之前包含 "May I write" 协作协议用语
• 结尾有下一步交接（handoff），例如指向/bug-triage（重新排优先级）或/hotfix（处理 CRITICAL）

这套静态断言不是本技能独有，而是整个测试框架的统一门槛。根据 README.md，可以用以下命令对任意技能执行静态检查：

/skill-test static bug-report # 只检查 bug-report 一个技能 /skill-test static all # 检查全部 72 个技能

只有当静态断言通过后，才进入下一阶段的行为规格测试（/skill-test spec bug-report）。

三、行为测试用例：五个场景定义技能的正确行为

规格的核心是 5 个测试用例，每个用例包含Fixture（前置状态）、Input（输入）、Expected behavior（预期行为）、Assertions（断言）四要素。这些用例就是/bug-report技能的"验收标准"。

3.1 Case 1：Happy Path —— 崩溃类缺陷应判定为 CRITICAL

前置状态：production/bugs/目录存在且为空，无相似历史报告。

输入：用户描述 "Game crashes when player enters the boss arena"。

预期行为：

1. 提取标题为 "Game crashes when entering boss arena"；
2. 识别崩溃类报告应判定为CRITICAL严重级别；
3. 与用户确认复现步骤、预期行为（不应崩溃）、实际行为（崩溃）、受影响系统（arena/boss）及构建版本；
4. 起草完整的结构化报告；
5. 询问 "May I write toproduction/bugs/bug-2026-04-06-game-crashes-boss-arena.md?"；
6. 批准后写入文件，结论为 COMPLETE。

断言要点：7 个必填字段全部在场；崩溃报告严重级别为 CRITICAL；文件名符合bug-[date]-[slug].md约定；"May I write" 必须带完整路径；结论为 COMPLETE。

3.2 Case 2：Minimal Input —— 信息缺失时逐个追问

前置状态：用户只提供 "Sometimes the audio cuts out"，无任何历史报告。

预期行为：

1. 识别缺失字段：复现步骤、预期 vs 实际行为、严重级别、受影响系统、构建版本；
2. 针对每个缺失字段提出定向追问（可逐条或结构化提示，但至少 3 个追问）；
3. 用户逐项补充后，技能才汇编出完整报告；
4. 询问 "May I write?" 并在批准后写入。

断言要点：至少提出 3 个追问；所有字段补齐前报告不得定稿；缺失字段未补齐时禁止写文件；全部补齐并写入后结论为 COMPLETE。

这一用例直接对应 Skill Summary 中"缺失字段先追问再起草"的硬性约束，杜绝了"拿着半句话就写报告"的偷懒行为。

3.3 Case 3：Possible Duplicate —— 查重优先，链接而非新建

前置状态：production/bugs/bug-2026-03-20-audio-cut-out.md已存在，标题相似、严重级别 MEDIUM。

输入：用户描述 "Audio randomly stops working"。

预期行为：

1. 扫描既有报告，发现相似的音频缺陷；
2. 明确告知用户："A similar bug report exists: bug-2026-03-20-audio-cut-out.md"；
3. 给出两个选项：作为重复链接（在既有报告中补充交叉引用）或仍然新建；
4. 若用户选择链接，需再次询问 "May I update the existing report?" 才能修改既有文件；
5. 无论走哪条路径，结论都是 COMPLETE。

断言要点：新建前必须先浮出相似报告；用户有选择权（不被强制链接或新建）；修改既有文件前必须再次 "May I update" 确认；两条路径都以 COMPLETE 收尾。

值得注意的是，重复检测需要读取production/bugs/目录下已有的报告——这正是/bug-report与下游/bug-triage共享同一数据源的体现。

3.4 Case 4：Multi-System Bug —— 多系统影响合并在单份报告

前置状态：无既有报告。

输入：用户描述 "After finishing a level, the save system freezes and the UI doesn't show the completion screen"。

预期行为：

1. 从描述中识别出 2 个受影响系统：Save System和UI；
2. 报告在 Affected System(s) 下列出两个系统；
3. 严重级别评估为HIGH（存档冻结存在数据丢失风险）；
4. 询问 "May I write" 并写入。

断言要点：两个受影响系统都出现在报告中；只创建一份报告（而不是每个系统各建一份）；严重级别反映影响最大的组件（存档冻结 → HIGH 或 CRITICAL）；结论 COMPLETE。

3.5 Case 5：Director Gate Check —— 确认无门禁、无导演 Agent

前置状态：任意缺陷描述。

预期行为：

1. 正常创建并写入缺陷报告；
2. 不生成任何导演 Agent；
3. 输出中不出现任何 gate ID；
4. 无需门禁检查即达到 COMPLETE。

断言要点：不调用导演门禁；不出现门禁跳过消息；无门禁检查也能以 COMPLETE 结束。

四、协议合规清单：技能质量的第二道防线

除了逐用例断言，规格末尾还给出了 Protocol Compliance 清单，等价于技能的"通用行为底线"：

• 起草报告前收集全部 7 个必填字段
• 对任何缺失字段提出追问
• 新建报告前检查是否存在相似既有报告
• 写入前询问 "May I write toproduction/bugs/bug-[date]-[slug].md?"
• 报告文件写入后结论为 COMPLETE

这五项与 templates/skill-test-spec.md 模板中的协议合规部分一脉相承——所有技能规格都要求"写入前先征求许可""不以任何方式自动建文件"，/bug-report把这一通用协议落实到了"查重 + 全路径 May I write"的具体操作上。

五、Coverage Notes：已知未覆盖的边界情形

规格最后的 Coverage Notes 诚实记录了未纳入自动化断言的三类边界情形，这对评估技能鲁棒性很有价值：

1. 严重级别与影响不匹配：用户为崩溃类缺陷标注 LOW 级别时，技能可以建议更高严重级别，但最终尊重用户输入——此行为未纳入测试。
2. Build/Version 为 unknown：构建版本字段是必填，但如果用户确实不知道，unknown是被接受的合法值，且不单独测试。
3. slug 生成：把标题清洗为文件名的实现细节不参与断言测试。

这三条说明该技能的规格在设计上刻意留出了"人机协商"空间：机器负责结构化与提醒，最终决策权在用户。

六、在缺陷生命周期中的位置：与上下游技能的衔接

/bug-report不是孤立存在的，它处于 CCGS 缺陷处理链的入口位置：

6.1 上游输出 →/bug-triage（排序与查重）

/bug-triage 读取production/bugs/下所有未关闭报告，按 CRITICAL → HIGH → MEDIUM → LOW 排序输出分诊表。规格中/bug-report的静态断言要求"结尾有下一步交接"，典型交接目标正是/bug-triage：

• 对缺少复现步骤的报告标记NEEDS REPRO INFO
• 对标题 + 系统 + 严重级别相似的报告标记POSSIBLE DUPLICATE并互相交叉引用
• 全程只读，结论固定为 TRIAGED，供 producer 或 QA lead 决策

也就是说，/bug-report负责创建结构化报告，/bug-triage负责消费这些报告做优先级分诊，二者共享production/bugs/这一数据契约。

6.2 临界缺陷 →/hotfix（紧急修复）

/hotfix 处理时间敏感的紧急修复：从 main 创建 hotfix 分支、定位文件修改、跑/smoke-check验证、确认后合回 main。其手交接（handoff）反向指向/bug-report——修复完成后用/bug-report记录问题本身。这样，一个 CRITICAL 缺陷的完整闭环是：

/bug-report（记录结构化缺陷）→ /bug-triage（分诊排序）→ /hotfix（紧急修复） ↓ /smoke-check（回归验证）→ 合并 main

skill-flow-diagrams.md 的流程图中也明确绘制了/bug-report产出production/bugs/bug-NNN.md的流向，印证了它在框架数据流中的固定位置。

七、如何验证与改进该技能

整个 CCGS Skill Testing Framework 的目的，就是让技能自身可被测试、可被度量：

1. 静态检查：/skill-test static bug-report，验证 frontmatter、阶段标题、COMPLETE 关键词、"May I write" 用语与交接段（7 项检查）。
2. 行为规格测试：/skill-test spec bug-report，按本文第三节的 5 个用例逐条评估。
3. 类别评分卡：/skill-test category bug-report，对照 quality-rubric.md 中utility类别的 U1（通过全部 7 项静态检查）、U2（若触发门禁则模式逻辑正确）指标。
4. 覆盖率审计：/skill-test audit查看技能是否已有 spec、上次测试时间与结果。
5. 失败改进循环：/skill-improve bug-report走"测试 → 诊断 → 提出修复 → 重写 → 重测 → 保留或回滚"闭环。

catalog.yaml是整个测试体系的主注册表，其中bug-report条目如下：

- name: bug-report spec: CCGS Skill Testing Framework/skills/utility/bug-report.md

依据 CLAUDE.md 的说明，规格文件描述的是当前行为而非理想行为，可能编码了潜在缺陷；当技能实际表现与规格不符时，正确做法是先修正技能本身，再同步更新规格——规格失败应被视作"需要调查的信号"，而非"技能必然出错"的定论。

八、结语

/bug-report的规格文件完整定义了一个高质量缺陷报告技能应有的行为边界：七字段全量收集、缺失即追问、查重优先、全路径 May I write、无导演门禁、以 COMPLETE 收尾。它通过 5 个行为用例 + 协议合规清单 + 覆盖说明形成闭环验证体系，并与/bug-triage、/hotfix一起构成 CCGS 从"发现问题"到"排定优先级"再到"紧急修复"的完整缺陷处理流水线。

对于希望在自己的 CCGS 项目中引入缺陷管理纪律的团队，可以直接在production/bugs/下按bug-[date]-[slug].md约定积累报告，用/bug-triage定期分诊、用/hotfix处理临界问题，并通过 catalog.yaml 与/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