用 team-ui 技能编排完整 UI 流水线：Claude Code Game Studios 的五阶段 UI 团队协作实战指南

用 team-ui 技能编排完整 UI 流水线：Claude Code Game Studios 的五阶段 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

导读

team-ui是 Claude Code Game Studios 提供的团队级编排技能（Skill）：当你在 Claude Code 会话中输入/team-ui [UI feature description]时，它会以流水线编排者的身份，把 UX 设计、视觉设计、实现、评审、打磨五个阶段串成一条带质量门（Gate）的完整链路，并委派ux-designer、ui-programmer、art-director、引擎 UI 专家与accessibility-specialist等子代理协同作业。读完本文，你将掌握该技能的团队构成、委派机制、五个阶段的执行细节、决策点（Decision Points）交互方式、错误恢复协议与底层模板/代理定义，能够在自己的项目中直接复用它把「一个 UI 功能描述」变成「一份经过评审、可交付实现的完整方案」。

一、技能定位：从一个功能描述到一套可交付 UI

team-ui技能的完整定义位于 .claude/skills/team-ui/SKILL.md，其 frontmatter 给出了关键元信息：

从技能描述可以看到，它本身不直接产出设计，而是与/ux-design、/ux-review两个技能以及工作室的 UX 模板协同工作，充当「管弦乐队的指挥」。

整个流水线的骨架是五个阶段加一个前置上下文收集阶段：

Phase 1a 上下文收集 → Phase 1b UX Spec 撰写 → Phase 1c UX Review（质量门） → Phase 2 视觉设计 → Phase 3 实现 → Phase 4 并行评审 → Phase 5 打磨

决策点（Decision Points）机制贯穿始终：在每个阶段切换时，编排者必须使用AskUserQuestion把子代理的提案以可选项形式呈现给用户；完整分析写在对话中，用简洁标签记录决策。用户批准之前不得进入下一阶段——这是「以人为创意总监」的协作原则在流水线层面的落地。

二、团队构成：五个角色的职责边界

team-ui的编排对象是一个固定的五人小组，每个角色都有明确的职责边界，避免越权：

流水线使用的模板（均位于 .claude/docs/templates/）：

• ux-spec.md — 标准屏幕/流程 UX 规格
• hud-design.md — HUD 专属 UX 规格
• interaction-pattern-library.md — 可复用交互模式库
• accessibility-requirements.md — 已承诺的可访问性层级与要求

这些模板的实际内容非常详实：例如ux-spec.md模板包含 15 个章节（Purpose & Player Need、Player Context on Arrival、Navigation Position、Entry & Exit Points、Layout Specification、States & Variants、Interaction Map、Data Requirements、Events Fired、Transition & Animation、Input Method Completeness Checklist、Screen-Level Accessibility Requirements、Localization Considerations、Acceptance Criteria、Open Questions），其中 Data Requirements 章节明确写有核心架构规则：「本屏幕永远不得直接写入任何系统——所有玩家动作都通过事件（Events）触发（见 Events Fired 章节）。系统更新自己的数据并通知 UI。」（见 ux-spec.md 第 299 行附近）。

三、委派机制：用 Task 工具调度子代理

编排者通过Task 工具把每个团队成员作为子代理派生（spawn），subagent_type决定调用哪个代理：

subagent_type: ux-designer → 用户流程、线框图、可访问性、输入处理 subagent_type: ui-programmer → UI 框架、屏幕、控件、数据绑定 subagent_type: art-director → 视觉风格、布局打磨、Art Bible 一致性 subagent_type: [UI engine specialist] → 引擎专属 UI 模式校验（如 unity-ui-specialist / ue-umg-specialist / godot-specialist） subagent_type: accessibility-specialist → 可访问性合规审计

关键操作要求是：每个子代理的 prompt 中必须提供完整上下文（功能需求、既有 UI 模式、平台目标），并在流水线允许时并行启动独立代理（例如 Phase 4 的评审代理可以同时运行）。这与仓库中代理定义的协作协议一致——例如 .claude/agents/ux-designer.md 明确写着「You are a collaborative consultant, not an autonomous executor. The user makes all creative decisions.」而 .claude/agents/ui-programmer.md 则强调「You are a collaborative implementer, not an autonomous code generator」，其实现前必须先读设计文档、提出架构问题、展示类结构与数据流并获得批准。

四、五阶段流水线详解

Phase 1a：上下文收集（Context Gathering）

在设计任何东西之前，编排者必须读取并综合以下输入：

• design/gdd/game-concept.md— 平台目标与目标受众
• design/player-journey.md— 玩家到达该屏幕时的状态与情境
• 与该功能相关的所有 GDD UI Requirements 章节
• design/ux/interaction-patterns.md— 应复用的既有模式（而不是重新发明）
• design/accessibility-requirements.md— 已承诺的可访问性层级（如 Basic / Enhanced / Full）

缺口处理是硬性要求：如果design/ux/interaction-patterns.md不存在，必须立即向用户表面该缺口，并原样输出提示「interaction-patterns.md does not exist — no existing patterns to reuse.」，随后用AskUserQuestion给出两个选项：

• (a) 先运行/ux-design patterns建立模式库，再继续；
• (b) 在没有模式库的情况下继续——ui-programmer 会把实现中创建的所有模式当作新模式，并在完成时全部写入新建的design/ux/interaction-patterns.md。

技能明确禁止「仅凭功能名称或 GDD 就发明/假设模式」。如果用户选择 (b)，必须显式指示 Phase 3 的 ui-programmer 把所有模式视为新模式并在实现完成后记录到模式库，同时在最终总结报告中注明模式库状态（created / absent / updated）。最后，把所有上下文总结成一份给 ux-designer 的简报：玩家在做什么、需要什么、有哪些约束、哪些既有模式相关。

Phase 1b：UX Spec 撰写（UX Spec Authoring）

调用/ux-design [feature name]技能，或直接委派给 ux-designer，产出design/ux/[feature-name].md，遵循ux-spec.md模板。如果设计的是 HUD，则改用hud-design.md模板。

特殊情况的处理规则：

• HUD 设计：调用/ux-design时传入参数hud（如/ux-design hud）；
• 交互模式库：在项目启动时运行一次/ux-design patterns，之后各阶段引入新模式时持续更新它。

产出物：design/ux/[feature-name].md，所有必需章节均已填写。

这里的底层实现细节可以参考 /ux-design 技能：它根据参数分三种模式——hud（输出design/ux/hud.md）、patterns（输出design/ux/interaction-patterns.md）、其他任意值（如main-menu、inventory，输出design/ux/[argument].md）；无参数时用AskUserQuestion询问要设计什么，并把屏幕名规范化为 kebab-case 文件名（"Main Menu" →main-menu）。它还在 Phase 2 读取游戏概念、玩家旅程、GDD UI Requirements、既有 UX spec、模式库目录、Art Bible、可访问性要求，以及 .claude/docs/technical-preferences.md 中的## Input & Platform章节（输入方式、主输入、手柄支持、触屏支持、目标平台）——如果该章节是未配置的[TO BE CONFIGURED]，只问一次并建议用/setup-engine永久保存。

值得注意的还有Retrofit 模式：如果目标文件已存在，/ux-design会逐节检查内容是「Complete / Empty / Placeholder」，只补全空节，绝不覆盖已有内容；以及逐节撰写循环：Context → Questions → Options → Decision → Draft → Approval → Write，每节批准后立即写入文件并更新production/session-state/active.md——这正是技能文档中「增量写入使任何中断都不丢工作」的机制来源。

Phase 1c：UX Review（质量门）

spec 完成后，调用/ux-review design/ux/[feature-name].md。

门禁（Gate）：在评审结论为 APPROVED 之前不得进入 Phase 2。若结论为 NEEDS REVISION，ux-designer 必须处理被标记的问题并重新评审。用户也可以显式接受 NEEDS REVISION 的风险继续推进，但这必须是有意识的决定——在询问是否继续前，先用AskUserQuestion呈现具体关切。

ux-review 技能 定义了三级评审结论：

• APPROVED— spec 完整、一致、可进入实现；
• NEEDS REVISION— 存在具体缺口，修复后即可交接，无需整体重做；
• MAJOR REVISION NEEDED— 在范围、玩家需求或完整性上存在根本性问题，需要大改。

其评审清单覆盖面极广：完整性检查（14 个必需章节）、玩家需求清晰度、状态完备性（错误态/空态/加载态）、输入方法覆盖（PC 键盘导航、主机手柄 D-pad、焦点顺序）、数据架构（任何数据元素都不得以 "UI" 作为拥有者、实时数据更新频率、null 处理）、可访问性（按层级匹配：Basic 无纯颜色指示、Standard+ 焦点顺序与对比度、Comprehensive+ 屏幕阅读器播报）、GDD 对齐、模式库一致性、本地化（40% 文本膨胀预留）、验收标准质量（性能指标、分辨率指标、QA 无需读其他文档即可验证）。该技能还是只读的——从不编辑或写入文件，只报告结论。

Phase 2：视觉设计（Visual Design）

委派给art-director，要求：

• 阅读完整的 UX spec（流程、线框图、交互模式、可访问性备注），而不是只看线框图图片；
• 从 Art Bible 应用视觉处理：配色、字体排印、间距、动画风格；
• 检查视觉设计是否保留了可访问性合规性：验证颜色对比度，并确认颜色永远不会是状态的唯一指示器（形状、文字或图标必须作为补充）；
• 明确列出从美术管线需要的所有资源：指定尺寸的图标、背景纹理、字体、装饰元素——必须给出精确的尺寸和格式要求；
• 确保与既有已实现 UI 屏幕的一致性；
• 产出：带风格说明和资源清单（asset manifest）的视觉设计规格。

Phase 3：实现（Implementation）

实现开始前，先派生出引擎 UI 专家（从 .claude/docs/technical-preferences.md 的 Engine Specialists → UI Specialist 读取，例如 Unity 的unity-ui-specialist、Unreal 的ue-umg-specialist、Godot 的godot-specialist），让其评审 UX spec 与视觉设计规格，给出引擎专属实现指导：

• 该屏幕应该用哪个引擎 UI 框架？（例如 Unity 的 UI Toolkit vs UGUI、Godot 的 Control 节点 vs CanvasLayer、Unreal 的 UMG vs CommonUI）
• 针对所提议布局或交互模式，有哪些引擎专属陷阱（gotchas）？
• 该引擎推荐的 widget/节点结构是什么？
• 产出：在 ui-programmer 开工前交给他的引擎 UI 实现说明。

如果没有配置引擎，则跳过此步骤（这也是 .claude/docs/technical-preferences.md 中 Engine Specialists 各字段默认为[TO BE CONFIGURED — run /setup-engine]的原因）。

随后委派给ui-programmer，实现必须遵循以下硬性约束：

• 遵循 UX spec 与视觉设计规格实现 UI；
• 使用design/ux/interaction-patterns.md中的模式——不得重新发明已规定的模式；若某模式「几乎匹配但需修改」，记录偏差并标记交由 ux-designer 评审；
• UI 绝不拥有或修改游戏状态——只负责显示；所有玩家动作一律发出事件；
• 所有文本走本地化系统——禁止硬编码玩家可见字符串；
• 同时支持两种输入方式（键盘/鼠标 + 手柄）；
• 按design/accessibility-requirements.md中承诺的层级实现可访问性功能；
• 完成到游戏状态的数据绑定；
• 若实现期间创建了新模式（模式库中没有的），在标记实现完成前把它加入design/ux/interaction-patterns.md；
• 产出：已实现的 UI 功能。

这些约束与 ui-programmer 代理定义 中的「UI Code Principles」完全对应：UI 永不阻塞游戏线程、所有文本走本地化系统、支持键盘/鼠标与手柄、动画可跳过并尊重用户动态偏好、UI 音效通过音频事件系统触发而非直接调用。

Phase 4：并行评审（Review）

并行委派三个评审流：

• ux-designer：验证实现与线框图和交互规格一致；测试仅键盘导航与仅手柄导航；检查可访问性功能是否正常工作；
• art-director：验证与 Art Bible 的视觉一致性；在最小和最大支持分辨率下检查；
• accessibility-specialist：对照 .claude/docs/templates/accessibility-requirements.md 中承诺的可访问性层级验证合规性；任何违规都标记为阻塞项（blockers）。

三个评审流都必须汇报完毕才能进入 Phase 5。

Phase 5：打磨（Polish）

• 处理所有评审反馈；
• 验证动画可跳过并尊重玩家的减少动态效果偏好；
• 确认 UI 音效通过音频事件系统触发（无直接音频调用）；
• 在所有支持的分辨率和宽高比下测试；
• 验证design/ux/interaction-patterns.md是最新的——若该功能实现期间引入了新模式，确认已加入模式库；
• 确认所有 HUD 元素遵守design/ux/hud.md中定义的视觉预算（元素数量、屏幕区域分配、最大不透明度值）。

HUD 视觉预算的具体定义可见 hud-design.md 模板 的「Visual Budget」章节，例如最大同时活动 HUD 元素数、探索模式 HUD 占用屏幕百分比（示例值 12%）、战斗模式（示例值 22%）、中心屏幕区占用上限（示例值 5%）、HUD 文字最小对比度 4.5:1（WCAG AA）、HUD 背景面板最大不透明度（示例值 65%）等——这些数字是硬性上限而非建议，任何会突破上限的元素新增都必须有明确批准并挤占/缩减既有元素。

五、快速参考：何时用哪个技能

六、错误恢复协议：BLOCKED 时的处理

如果任何被派生的代理（通过 Task）返回 BLOCKED、报错或无法完成：

1. 立即表面：在进入依赖阶段前向用户报告「[AgentName]: BLOCKED — [reason]」；
2. 评估依赖：检查被阻塞代理的输出是否为后续阶段所需。如果是，在该依赖点之前不得在无用户输入的情况下继续推进；
3. 提供选项（AskUserQuestion）：
   • 跳过该代理并在最终报告中注明缺口；
   • 缩小范围重试；
   • 停在此处，先解决阻塞；
4. 始终产出部分报告——输出已完成的一切。绝不因为一个代理阻塞而丢弃工作。

常见的阻塞原因及应对：

七、文件写入协议与最终输出

文件写入协议：所有文件写入（UX spec、交互模式库更新、实现文件）都委派给子代理和子技能（/ux-design、ui-programmer），每个都强制执行「May I write to [path]?」协议。本编排技能本身不直接写文件。

最终输出是一份总结报告，覆盖：UX spec 状态、UX review 结论、视觉设计状态、实现状态、可访问性合规性、输入方式支持、交互模式库更新状态、以及任何未决问题。

最终结论有两种：

• Verdict: **COMPLETE**— UI 功能已通过完整流水线交付（UX spec → 视觉 → 实现 → 评审 → 打磨）；
• Verdict: **BLOCKED**— 流水线中止；停止前表面阻塞点及其所在阶段。

后续步骤建议：

• 对最终 spec 运行/ux-review（若尚未批准）；
• 关闭 story 前对 UI 实现运行/code-review（见 .claude/skills/code-review/SKILL.md）；
• 若需要视觉或音频打磨，运行/team-polish（见 .claude/skills/team-polish/SKILL.md）。

八、底层支撑：流水线在仓库中的完整落点

team-ui并非孤立技能，它依赖仓库中一整套已经成型的模板、代理定义与参考文档，理解这些落点有助于你在自己的项目中裁剪或扩展它：

1. 代理定义层（.claude/agents/）

• ux-designer.md：协作式咨询顾问，Question-First 工作流，AskUserQuestion呈现 2-4 个选项并注明推荐，职责覆盖用户流程映射、交互设计、信息架构、新手引导、可访问性标准、反馈系统；明确禁止做视觉风格决策（交 art-director）、写 UI 代码（交 ui-programmer）、设计玩法机制（协调 game-designer）。
• ui-programmer.md：协作式实现者，实现前先读设计文档、提出架构问题、展示类结构与数据流权衡，并遵守「引擎版本安全」规则——建议任何引擎 API 前先查docs/engine-reference/[engine]/VERSION.md的钉定版本。
• art-director.md：视觉身份所有者，负责 Art Bible、风格指南强制、资源规格（分辨率、格式、命名[category]_[name]_[variant]_[size].[ext]）、UI/UX 视觉设计与视觉层级。
• accessibility-specialist.md：按 WCAG 2.1 审计可访问性，产出结构化发现表（Finding / WCAG Criterion / Severity / Recommendation），默认以 WCAG 2.1 Level AA 为合规目标；在四类可访问性（视觉、音频、运动、认知）和输入支持上都有明确标准，例如文字对比度最低 4.5:1、字幕至少 3 档字号、全输入重映射、无强制组合按键等。

2. 引擎参考层（docs/engine-reference/）

每个引擎都有独立的 UI 模块文档，例如 docs/engine-reference/unity/modules/ui.md、docs/engine-reference/unreal/modules/ui.md、docs/engine-reference/godot/modules/ui.md，并配套VERSION.md、breaking-changes.md、deprecated-apis.md、current-best-practices.md——这正是 Phase 3 引擎 UI 专家校验实现模式时的依据来源。Unity 侧还有插件文档如 docs/engine-reference/unity/plugins/addressables.md。

3. 配置层（.claude/docs/technical-preferences.md）

Engine Specialists 章节是流水线的路由中枢：Primary、Language/Code Specialist、Shader Specialist、UI Specialist 等字段默认均为[TO BE CONFIGURED — run /setup-engine]，File Extension Routing 表则按文件扩展名（游戏代码、shader/material、UI/screen 文件）决定派生哪个专家；未配置时回退到 Primary。这就是「未配置引擎则跳过引擎专家步骤」的机制根源，也解释了为什么team-ui技能要求引擎 UI 专家的配置从这里读取。

4. 会话状态层（production/session-state/）

/ux-design技能在骨架创建、每节写入、交接时都会更新production/session-state/active.md（Task、Current section、File、Status、Next），这是 Phase 1b 增量写入与技能中断恢复（compaction / crash / 新会话）的持久化基础。

九、结语：把「流水线」变成你的默认 UI 协作方式

从上下文收集到最终打磨，team-ui的价值不在于「多了一个命令」，而在于它把松散的多代理协作变成了有门禁、有证据、有恢复机制的工程流水线：每个阶段都有明确的输入输出、每个决策点都有用户确认、每次评审都有可引用的清单、每次失败都有部分报告兜底。配合仓库中完整的模板（ux-spec、hud-design、interaction-pattern-library、accessibility-requirements）、代理定义（ux-designer、ui-programmer、art-director、accessibility-specialist）与引擎参考文档，任何规模的团队都可以把「一个 UI 功能描述」稳定地转化为「通过评审、可交付实现的 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