CCGS UI Programmer Agent 测试规范全解读：领域边界、跨角色协作与引擎 UI 工具链的验收基线-二趣网

CCGS UI Programmer Agent 测试规范全解读：领域边界、跨角色协作与引擎 UI 工具链的验收基线

【免费下载链接】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（CCGS）中 UI Programmer 专项 Agent 的行为测试规范（CCGS Skill Testing Framework/agents/specialists/ui-programmer.md）展开，完整解析其职责域划分、5 条测试用例的判定逻辑与协议合规清单，并结合仓库中的质量标尺、Agent 编目与 Godot 4.6 引擎参考文档，说明这套规范如何在真实项目中落地为可执行、可复现的 Agent 验收流程。读完本文，你将掌握 CCGS 如何用「静态断言 + 行为用例 + 协议合规」三层结构约束一个 UI 实现型 Agent，以及如何把它接入/skill-test测试框架进行逐条验证。

一、文档定位：一份用于质量验证的 Agent 行为测试规范

在 CCGS 中，Agent 的"岗位说明书"并不直接描述功能，而是描述应当表现出的行为。UI Programmer 的这份文档属于agents/specialists/层级，与 agent-test-spec.md 模板同构：由 Agent Summary、Static Assertions（静态断言）、Test Cases（测试用例）、Protocol Compliance（协议合规）、Coverage Notes（覆盖说明）五个部分构成。

它在整个质量保障体系中的位置可以从 catalog.yaml 中确认：ui-programmer的spec字段被登记为CCGS Skill Testing Framework/agents/specialists/ui-programmer.md，category为specialist——即与 gameplay-programmer、technical-artist、ux-designer 等并列的核心专项 Agent。根据 CCGS Skill Testing Framework/CLAUDE.md 的说明，Agent 规范文件（agents/[tier]/[name].md）统一包含「5 条测试用例 + 协议合规断言」，并且这些规范描述的是当前行为而非理想行为——它们是从 Agent 定义中逆向读出的，可能编码了 bug。因此，当 Agent 在实践中表现异常时，正确顺序是：先修正 Agent 本体，再更新规范使其与修复后的行为一致；规范失败应被理解为"需要调查"，而非"Agent 绝对错了"。

二、UI Programmer 的职责领域与边界

2.1 明确拥有的域

文档在 Agent Summary 中划定了 UI Programmer 的核心领域：

菜单界面（Menu screens）
HUD（Heads-Up Display）
物品栏/库存界面（Inventory screens）
对话气泡（Dialogue boxes）
UI 框架代码（UI framework code）
数据绑定（Data binding）

2.2 明确不拥有的域

同时，文档严格声明了两条边界，防止越权：

UX 流程设计不属于 UI Programmer，归属ux-designer（交互流程、信息架构、输入方案设计）；
视觉风格方向不属于 UI Programmer，归属art-director/technical-artist。

这一划分在 ux-designer 测试规范中形成了双向印证：ux-designer 的 Case 2 明确写着"UI 代码实现属于ui-programmer，应重定向"，并补充"UX 流程规格应作为实现参考提供给 ui-programmer"。也就是说，两份规范互为对方的边界契约——设计端不写代码，实现端不设计流程。

2.3 模型档位与门禁

Model tier：Sonnet（默认）——与 quality-rubric.md 中 specialist 类目（S1–S3）以及"Sonnet model tier（default per coordination-rules）"的 lead 类目 L3 一致；
No gate IDs assigned——UI Programmer 不触发导演级（director）门禁，属于纯执行型专项 Agent。

三、静态断言：结构性检查（Static Assertions）

规范要求通过 4 项静态断言来约束 Agent 定义文件本身的结构：

#	断言	含义
1	`description:`字段存在且领域相关	必须提及 menus / HUDs / UI framework / data binding 等关键词
2	`allowed-tools:`列表包含 Read、Write、Edit、Bash、Glob、Grep	具备读写与检索能力，可产出实现代码
3	模型档位为 Sonnet	符合 specialist 默认档位
4	Agent 定义不得声称拥有 UX 流程设计与视觉美术方向的权威	与 2.2 的边界契约一致

这些断言与通用模板 agent-test-spec.md 中"Frontmatter hasname,description,model,toolsfields"的要求呼应，只是针对 UI 领域做了更细的约束——尤其是第 4 条，用结构化的方式把"不越权"写死成可检查的规则，而不是依赖模型自觉。

四、五条行为测试用例：判定逻辑逐条拆解

Case 1：域内请求——按 UX 规格实现库存界面

输入："Implement the inventory screen from the UX spec indesign/ux/inventory-flow.md."

期望行为：

先读规格再写码：生产任何代码前必须先读取 UX 规格；
使用项目配置的 UI 框架：UI Toolkit、UGUI、UMG 或 Godot Control 节点，按项目实际引擎选择；
实现规格中定义的全部状态：default、hover、selected、empty-slot、locked-slot——注意 empty-slot 与 locked-slot 这两个易被遗漏的空态/锁定态；
数据绑定走项目数据模型，禁止硬编码值；
公开 UI API 需带文档注释，遵循编码规范。

这条用例的本质是验证"实现忠实于规格 + 遵守工程规范"两个维度。它隐含了一个值得注意的映射：五个 UI 状态（default/hover/selected/empty-slot/locked-slot）与 ux-designer 测试规范 Case 1 中要求定义的交互状态完全一致——设计端产出状态定义，实现端逐状态落地，规范层面已经预埋了"同一份状态清单"的契约。

Case 2：域外请求——正确重定向

输入："Design the inventory interaction flow — what happens when the player equips, drops, or combines items."

期望行为：

不得产出交互流程设计或用户流程图；
明确声明 UX 流程设计归属ux-designer；
将请求重定向给ux-designer；
同时注明：流程规格就绪后，UI Programmer 可以接手实现。

这是一条"拒绝但不沉默"的用例：不是简单拒绝，而是指明归属方 + 说明后续可承接的时机。这与 quality-rubric.md 中 specialist 类目的 S3 指标（"域外请求应重定向到正确的 Agent，而不是沉默拒绝"）完全对齐。

Case 3：自定义动画协调——与 technical-artist 协作

输入："The item selection in the inventory needs a custom bounce animation when selected."

期望行为：

识别出动画曲线与手感（feel）的定义属于 technical-artist 领域；
在没有规格时不得自行发明动画参数（时长、缓动）；
与technical-artist协调获取动画规格：duration（时长）、easing curve（缓动曲线）、overshoot amount（过冲量）；
规格到位后，产出将动画绑定到选择状态的实现。

对照 technical-artist 测试规范的域声明（Shaders、VFX、渲染优化、美术管线工具），动画参数的"手感定义"确实落在 technical-artist 一侧。这条用例精准地检验了 Agent 对参数所有权的敏感度：实现动画代码是 UI Programmer 的活，但定义"弹得有多狠、缓多久"不是——没有规格就乱填数值，正是项目设计哲学中要避免的"hardcoding magic numbers"（见 README.md 的 Why This Exists 章节）。

Case 4：模糊 UX 规格——标记回写而非猜测

输入：UX 规格写了"show item details on selection"，但没有定义空槽位被选中时该发生什么。

期望行为：

识别出规格中的歧义（空槽位选择状态未定义）；
不为该未定义状态做武断的实现决策；
将歧义回传ux-designer，并附上具体问题："What should the detail panel show when an empty inventory slot is selected?"；
可提出两种常见选项（隐藏面板 / 显示占位符）帮助 ux-designer 快速决策。

这条用例把"规格缺口路由回作者"变成了硬性要求。Coverage Notes 中特别强调：此用例验证 Agent 把规格缺口路由回创作方 Agent，而不是自行猜测。它与 CCGS 的协作协议（Ask → Present options → You decide → Draft → Approve，见 README.md）一脉相承——用户和创作方始终保留决策权。

Case 5：上下文传递——引擎 UI 工具链（Godot 4.6）

输入：引擎上下文为 Godot 4.6 + Control 节点 UI。请求："Implement a scrollable item list for the inventory."

期望行为：

使用 Godot 的ScrollContainer+VBoxContainer+ItemList（或等价）模式，不得产出 Canvas 或 UGUI 代码；
对 Godot 项目不得产出 Unity UGUI 或 Unreal UMG 代码（严禁跨引擎代码）；
使用具体 API 前，**核对引擎版本参考（4.6）**中 4.4/4.5 起的 Control 节点 API 变化；
产出与项目配置语言一致的 GDScript 或 C# 代码。

这条用例在仓库中有着扎实的支撑材料。首先，docs/engine-reference/godot/VERSION.md 记录了引擎钉住版本为Godot 4.6（2026 年 1 月发布），且明确指出"LLM 训练数据大概率只覆盖到约 4.3，4.4/4.5/4.6 引入了模型不知道的重大变更，建议任何 Godot API 前必须先对照本目录"——这正好解释了为什么规范要求"用 API 前先查版本参考"。

其次，docs/engine-reference/godot/modules/ui.md 给出了与本例直接相关的 4.6 新行为：

双焦点系统（4.6 变更）：鼠标/触摸焦点与键盘/手柄焦点已分离，二者可同时作用于不同控件，UI 必须同时用鼠标和键盘/手柄测试——这直接关系到 inventory 列表的选中高亮与滚动交互；
4.5 新增FoldableContainer（手风琴式折叠节点）与Recursive Control 行为（单属性递归禁用整个节点层级）；
本地化就绪实践：可见字符串一律用tr()，标签开启autowrap_mode——与 UI Programmer 域中"对话气泡、菜单文案"场景强相关。

一个典型的 Godot 实现骨架（基于该参考文档的 API 模式）大致形如：

extends Control @onready var item_list: ItemList = %ItemList func _ready() -> void: # 数据绑定：从项目数据模型填充，而非硬编码 for item in InventoryModel.items(): item_list.add_item(item.display_name) # 键盘/手柄焦点（4.6 中 grab_focus 仅影响键盘/手柄焦点） %InventoryButton.grab_focus()

五、协议合规清单：验收时逐项勾选

规范末尾给出 6 项协议合规断言，作为任何一轮测试的汇总判定依据：

停留在声明域内（menus、HUDs、UI framework、data binding）
将 UX 流程设计重定向给 ux-designer
实现动画前与 technical-artist 协调动画规格
模糊 UX 规格回传 ux-designer，而非擅自做实现决策
返回结构化输出（实现代码、数据绑定模式、UI 状态的状态机）
对项目使用正确的引擎 UI 工具集——永不跨引擎输出代码

可以看到，6 项中有 4 项都在约束"边界与协作"，只有 2 项关乎产出质量本身。这反映了 CCGS 的设计取向：对执行型 Agent，最大的风险不是代码写得差，而是越权决策和规格失配。

六、覆盖说明：验收后的落地动作

Coverage Notes 补充了三条跟进约定：

Case 1 的库存实现应在production/qa/evidence/下留有 UI 交互测试或人工走查文档——实现不算完，要有证据沉淀；
Case 3 的动画协调确认 Agent 不会在无规格时发明手感参数；
Case 4 的模糊规格验证 Agent 将规格缺口路由回创作方而非猜测。

这三条把"验收通过"延伸到"证据归档"层面，与 quality-rubric.md 中 QA 类目 Q2（测试用例须符合项目的测试证据格式）的设计思路一致。

七、如何用 /skill-test 跑通这套规范

根据 CCGS Skill Testing Framework/CLAUDE.md 定义的测试工作流，验证 ui-programmer 的标准流程是：

读 catalog.yaml，拿到 Agent 的spec:路径（CCGS Skill Testing Framework/agents/specialists/ui-programmer.md）与category（specialist）；
读 Agent 定义文件（.claude/agents/ui-programmer.md，即被测试对象本体）；
读规范文件（本文讨论的这份文档）；
逐用例评估断言，对 5 个 Case 分别给出 PASS / FAIL / PARTIAL；
将结果写入results/并更新catalog.yaml中的last_spec/last_spec_result字段（该目录为 gitignore，不影响仓库本体）。

结构断言（前文第三节的 4 项静态断言）由/skill-test static自动执行；行为断言（第四节 5 个 Case）则依赖人工或 LLM 逐条对照。若想进一步把 ui-programmer 纳入类别评分，可参考 skill-test.md 中定义的四种模式（static / spec / audit / category）与 quality-rubric.md 中 specialist 类目的三把尺子：

指标	判定标准
S1 — Stays in domain	明确将自身限定在声明域内，域外请求予以延迟/转交
S2 — No binding cross-domain decisions	不单方面决定其他专项 Agent 管辖的事项
S3 — Defers correctly	域外请求重定向到正确的 Agent，而非沉默拒绝

对照可见，ui-programmer 规范的 5 个 Case 与 S1–S3 形成了一一对应的可执行投影：Case 2/3/4 分别就是 S3（正确重定向到 ux-designer）、S2（动画参数不越权）、S1（规格歧义不越权决策）的行为化表达。

结语

UI Programmer 测试规范是 CCGS「用结构约束协作」理念的一个缩影：一份不足百行的规范，通过 4 项静态断言守住 Agent 定义的结构底线，通过 5 条行为用例覆盖"实现规格、重定向、动画协调、规格回传、引擎工具链选择"五个高频风险场景，再以 6 项协议合规清单收口。配合catalog.yaml的编目登记、quality-rubric.md的 specialist 类目评分，以及 Godot 4.6 引擎参考这类版本证据文件，任何团队都可以把这套流程直接复制到自己的游戏项目中，对"UI 实现型 AI 工程师"进行可复现、可追溯的质量验收。

<输出文章>

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析