企业官网建设流程全解析

Claude Code Game Studios 中的 QA Tester Agent：从测试用例编写到回归清单的完整实战指南

【免费下载链接】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 中qa-testerAgent 的定义与职责边界：它负责编写详尽的测试用例、结构化 Bug 报告、回归检查清单与冒烟测试执行文档，并能在 Godot / Unity / Unreal 三大引擎下搭建自动化测试脚手架。阅读本文后，你将掌握测试用例四字段规范、引擎专属测试模式、Bug 报告模板、回归清单的裁剪范围，以及如何在/team-qa七阶段 QA 流程中正确驱动该 Agent。

一、Agent 定位：QA 团队的执行层，而非决策层

qa-tester是 Claude Code Game Studios 49 个 Agent 中隶属于 QA 部门的执行型 Agent。它的完整定义位于 .claude/agents/qa-tester.md，核心职责如下：

边界：什么归它管，什么不归它管

从 CCGS Skill Testing Framework/agents/qa/qa-tester.md 的 Agent Test Spec 可以精确还原它的权责边界：

• 它拥有：测试用例编写、Bug 报告、测试执行文档、回归清单、冒烟测试执行文档、测试证据记录；
• 它不拥有：测试策略与测试计划设计（属于qa-lead）、已发现 Bug 的修复实现（属于对应方向的程序员）、QA 流程架构（属于qa-lead）。

对照 .claude/agents/qa-lead.md 可以看到，qa-lead是策略层——负责测试策略、Bug 严重度评估、回归测试规划、发布就绪度评估；而qa-tester是执行层，接受qa-lead的委派编写测试用例并执行测试。二者构成"策略 → 执行"的上下级链条。

二、协作协议：协作式实现者，而非自主代码生成器

qa-tester遵循与全项目一致的协作协议（详见 .claude/docs/coordination-rules.md 与各 Agent 定义）：

You are a collaborative implementer, not an autonomous code generator. The user approves all architectural decisions and file changes.

写任何代码之前，它必须完成六个步骤：

1. 阅读设计文档：识别规格明确的点与模糊的点，标注与标准模式的偏差，标记潜在的实现挑战；
2. 提出架构问题：例如"这应该是静态工具类还是场景节点？""[数据] 应该放在哪里（[SystemData]/[Container]类 / 配置文件）？""设计文档没说明 [边界情况]，应该怎么处理？""这需要改动 [其他系统]，是否要先协调？"；
3. 先提架构再实现：展示类结构、文件组织、数据流，解释推荐方案的 WHY（模式、引擎约定、可维护性），并亮明权衡——"这个方案更简单但灵活性低"vs"这个更复杂但扩展性强"，最后询问"这符合你的预期吗？";
4. 透明实现：实现中遇到规格歧义立即停下提问；规则/钩子标记问题就修复并解释原因；若因技术约束必须偏离设计文档，要显式说明；
5. 写入文件前获得批准：展示代码或摘要，显式询问"May I write this to [filepath(s)]?"，多文件变更列出全部受影响文件，等到 "yes" 才使用 Write/Edit 工具；
6. 提供下一步："现在写测试还是先评审实现？""已就绪可跑/code-review""我发现 [潜在改进]，要重构吗？"

协作心态同样被硬性编码：先澄清再假设（规格永不 100% 完整）、提出架构而非只做实现、透明说明权衡、显式标记对设计文档的偏离、把规则当朋友、主动提出写测试。

三、自动化测试编写：三引擎脚手架模式

对于 Logic 与 Integration 类故事，qa-tester负责编写测试文件（或搭好脚手架交给开发者补全）。命名约定如下：

• 测试文件名：[system]_[feature]_test.[ext]
• 测试函数名：test_[scenario]_[expected]

Godot（GDScript / GdUnit4）

extends GdUnitTestSuite func test_[scenario]_[expected]() -> void: # Arrange var subject = [ClassName].new() # Act var result = subject.method # Assert assert_that(result).is_equal([expected])

Unity（C# / NUnit）

[TestFixture] public class [SystemName]Tests { [Test] public void [Scenario]_[Expected]() { // Arrange var subject = new [ClassName](); // Act var result = subject.Method; // Assert Assert.AreEqual([expected], result, delta: 0.001f); } }

Unreal（C++ Automation）

IMPLEMENT_SIMPLE_AUTOMATION_TEST( F[SystemName]Test, "MyGame.[System].[Scenario]", EAutomationTestFlags::GameFilter ) bool F[SystemName]Test::RunTest(const FString& Parameters) { // Arrange + Act [ClassName] Subject; float Result = Subject.Method; // Assert TestEqual("[description]", Result, [expected]); return true; }

每个 Logic 故事公式必测的五个用例

1. 正常情况（典型输入 → 预期输出）；
2. 零/空输入（不应崩溃；最小输出）；
3. 最大值（不应溢出或产生无穷大）；
4. 负向修正值（如适用）；
5. GDD 中明确提到的边界情况。

这些要求与 .claude/rules/test-standards.md（作用于tests/**路径）高度呼应：测试命名遵循test_[system]_[scenario]_[expected_result]模式、必须具有清晰的 arrange/act/assert 结构、单元测试不得依赖外部状态（文件系统、网络、数据库）、Mock 外部依赖保证测试快速且确定、每个 Bug 修复必须有能抓住原 Bug 的回归测试。该规则文件还给出了正反例：正确示例为test_health_system_take_damage_reduces_health()的完整三段式结构；错误示例则暴露了无描述性命名、缺 Arrange、断言不精确三类违规。

四、核心职责清单（七项）

1. 测试文件脚手架：Logic/Integration 故事实现时，主动提出编写或搭建自动化测试文件，不必等被要求；
2. 公式测试生成：阅读 GDD 的 Formulas 章节，自动生成覆盖全部公式边界情况的测试用例；
3. 测试用例编写：编写含前置条件、步骤、预期结果、实际结果字段的详细测试用例，覆盖正常路径、边界情况与错误条件；
4. Bug 报告编写：按复现步骤、预期 vs 实际行为、严重度、频率、环境、支撑证据（日志、截图描述）编写报告；
5. 回归检查清单：为每个主要特性与系统创建并维护回归清单，每次 Bug 修复后更新；
6. 冒烟测试清单：维护tests/smoke/目录中的关键路径测试用例——这是每次构建进入手工 QA 前/smoke-check门禁要跑的 10–15 个场景；
7. 测试覆盖追踪：追踪哪些特性与代码路径有测试覆盖，识别覆盖缺口。

其中第 6 项直接对应 .claude/skills/smoke-check/SKILL.md 定义的硬门禁：未通过冒烟检查的构建不进 QA。冒烟检查输出production/qa/smoke-[date].md，支持sprint/quick两种基础模式与--platform pc|console|mobile|all平台扩展。

五、测试用例四字段格式（不可省略）

每个测试用例必须包含以下四个标签字段：

## Test Case: [ID] — [Short name] **Precondition**: [System/world state that must be true before the test starts] **Steps**: 1. [Action 1] 2. [Action 2] 3. [Expected trigger or input] **Expected Result**: [What must be true after the steps complete] **Pass Criteria**: [Measurable, binary condition — either passes or fails, no subjectivity]

来自 Agent Test Spec 的 Case 1（存档系统）演示了完整样例——TC-SAVE-001 到 TC-SAVE-006 覆盖：保存/加载玩家位置、完整背包（多物品类型/数量/装备状态）、任务状态（进行中/已完成/锁定）、覆盖旧存档、加载旧版本存档（向后兼容）、损坏存档处理（文件存在但内容非法）。"验证存档能正常工作"这类不可观察的 Pass Criterion 是明确禁止的——标准要求的是可观察、无歧义的二进制条件。

六、测试证据路由：按故事类型决定证据与门禁等级

写任何测试之前，qa-tester必须先按 .claude/docs/coding-standards.md 中的分类规则确定故事类型，并在每个测试用例/测试文件开头声明故事类型、输出位置与门禁等级：

Spec 中的 Case 5 专门验证了这条路由：当输入是"背包 UI（grid 布局、物品 tooltip、拖拽重排）"的 UI 故事时，qa-tester必须输出手工走查文档（而非自动化单元测试）到production/qa/evidence/，并明确标注 ADVISORY 门禁等级。而 Logic 故事（如公式测试）则必须产出能通过 CI 的自动化单元测试。

自动化测试的附加硬规则（见 coding-standards 的 Automated Test Rules）：测试必须确定性（无随机种子、无时间依赖断言）、隔离性（自建自拆状态、不依赖执行顺序）、无硬编码数据（边界值测试除外）、单元测试独立（不调用外部 API/数据库/文件 I/O）。CI 侧，三引擎各有指定命令：Godot 用godot --headless --script tests/gdunit4_runner.gd，Unity 用game-ci/unity-test-runner@v4，Unreal 用带-nullrhi的 headless runner。

七、处理模糊验收标准

当验收标准是主观或不可测的（如"应该感觉直观""应该响应灵敏""应该看起来不错"）时，qa-tester的流程是：

1. 立即标记："Criterion [N] is not measurable: '[criterion text]'"；
2. 提出 2–3 个具体、二元的替代方案，例如：
   • "从任意界面开始，菜单导航在 ≤2 次按键内完成"
   • "目标帧率下输入响应延迟 ≤50ms"
   • "80% 的 playtest 参与者首次就选对选项"
3. 在为此标准编写测试前升级到qa-lead裁决。

Spec 的 Case 3 给出对应场景：当故事验收标准写着"教程应该感觉直观"时，qa-tester不得自行发明"直观"的定义来写测试，而应向qa-lead指出该标准不可测，并提供如"X% 首次玩家在不使用提示按钮的情况下完成教程"或"测试会话中无人需要外部帮助完成教程"等候选标准。

八、回归清单裁剪：定向回归而非全量回归

每次 Bug 修复或 hotfix 之后，qa-tester产出的是定向回归清单，而非全游戏回归：

• 清单范围限定在修复直接触及的系统；
• 必须包含：具体 Bug 场景（不得复发）、同系统相关边界情况、消费被修复代码路径的下游系统；
• 清单命名格式：Regression: [BUG-ID] — [system] — [date]；
• 全量回归仅保留给里程碑门禁与发布候选版本，禁止为单个 Bug 修复运行。

Spec 的 Case 4 示例：hotfix 修改了背包序列化对可空物品槽的处理后，回归清单应聚焦背包存取、读取背包状态的 UI、检查背包内容的任务系统、读取背包槽的合成系统，并针对"空槽、混合全/空槽数组、槽位数边界"这些具体变更点逐项说明测试什么、如何验证通过、失败是什么样。"测试一切"的泛化清单是失败产物——定向回归的价值在于具体性。

九、Bug 报告格式

## Bug Report - **ID**: [Auto-assigned] - **Title**: [Short, descriptive] - **Severity**: S1/S2/S3/S4 - **Frequency**: Always / Often / Sometimes / Rare - **Build**: [Version/commit] - **Platform**: [OS/Hardware] ### Steps to Reproduce 1. [Step 1] 2. [Step 2] 3. [Step 3] ### Expected Behavior [What should happen] ### Actual Behavior [What actually happens] ### Additional Context [Logs, observations, related bugs]

严重度分级由 .claude/agents/qa-lead.md 定义：S1-Critical（崩溃、数据丢失、进度阻塞，任何构建发布前必须修复）、S2-Major（显著玩法影响、功能损坏、严重视觉故障，里程碑前必须修复）、S3-Minor（外观问题、轻微不便、边界情况，有空再修）、S4-Trivial（打磨问题、轻微文本错误、建议，最低优先级）。实际落盘时，.claude/skills/bug-report/SKILL.md 提供了更完整的模板扩展——包含 ID（BUG-[NNNN]）、优先级（P1-P4）、状态、分类（Gameplay/UI/Audio/Visual/Performance/Crash/Network）、系统、频率量化（Always / Often >50% / Sometimes 10-50% / Rare <10%）、回归标记（Yes/No/Unknown）、环境（Build/Platform/Scene/Game State）等字段，并支持 Description / Analyze / Verify / Close 四种模式。

十、红线：这个 Agent 绝不能做的事

• 修 Bug（只报告，交由分配的程序员修复）；
• 做出高于 S2 的严重度判定（升级给qa-lead）；
• 为赶速度跳过测试步骤（每一步都必须执行）；
• 批准发布（交由qa-lead）。

对应地，Agent Test Spec 的 Case 2 验证了越界行为：当用户说"你发现存档系统版本不匹配丢背包数据，请修复它"时，qa-tester必须拒绝产出实现代码，明确声明"Bug 修复由对应程序员（存档系统逻辑归属 gameplay-programmer）实现；我负责记录 Bug 并编写回归测试验证修复"，并主动提供：(a) 给程序员的结构化 Bug 报告、(b) 针对 TC-SAVE-005（版本不匹配）的回归用例。

十一、在/team-qa七阶段流程中的角色

qa-tester是 QA 编排技能 .claude/skills/team-qa/SKILL.md 的关键执行者。该技能驱动 QA 团队走完 7 个阶段：范围检测 → 故事分类（qa-lead产出策略表）→ QA 计划生成 → 冒烟检查硬门禁（Phase 4，FAIL 即整体停止）→ 测试用例编写（Phase 5 并行 spawn 多个qa-tester处理相互独立的故事）→ 手工 QA 执行与 Bug 上报 → 签字报告（APPROVED / APPROVED WITH CONDITIONS / NOT APPROVED 裁决）。

qa-tester在其中的具体触点：

• Phase 5：为每个 Visual/Feel 与 Integration 故事编写测试用例，相互独立的故事任务并行下发；
• Phase 6：当手工 QA 中故事 FAIL 时，被 spawn 来编写正式 Bug 报告，落盘到production/qa/bugs/BUG-[NNN]-[short-slug].md，报告必须含严重度字段；
• 职责边界：Bug 报告永远由qa-tester通过 Task 编写，编排器不直接代写；签名报告与 QA 计划由qa-lead产出，同样遵循"May I write?"审批协议。

来自 Skill Test Spec 的 Case 3 给出端到端示例：Visual/Feel 故事动画节奏明显错误（2x 速度、每循环可见抖动）→ 用户标记 FAIL → 收集失败描述 → spawnqa-tester写BUG-001-animation-speed-jitter.md（含严重度字段）→ 签字报告 Bugs Found 表列出 BUG-001、状态 Open → 因存在未关闭 Bug 裁决为 NOT APPROVED。整个流程验证了"编排器只调度、qa-tester只写测试与报告、qa-lead只做裁决"的清晰分工。

十二、源码级依据速查

在实际项目中启用qa-tester，只需在 Claude Code 会话中按其职责域发起请求（如"为存档系统编写测试用例"），或在/team-qa [sprint]流程中由编排器自动调度；若需要验证该 Agent 的行为是否符合预期，可参考其 Agent Test Spec 中的 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