team-polish

团队打磨

如果未提供参数，则输出用法说明并退出，不启动任何 Agent：

用法：/team-polish [feature or area to polish] [--review full|lean|solo] — 指定要打磨的功能或区域（例如：combat、main menu、inventory system、level-1）。此处不要使用 AskUserQuestion；直接输出说明。

使用参数调用此技能时，通过结构化流程协调打磨团队。

决策节点： 每次阶段转换时，使用 AskUserQuestion 将子 Agent 的方案呈现为可选项。将 Agent 的完整分析写入对话，然后用简洁标签记录决策。在 collaborative 模式下，用户必须批准后才能进入下一阶段。在 guided 模式下，除非某个阶段被阻塞，否则流程会自动推进；在 autonomous 模式下，流程会端到端运行，并通过 log_decision 记录每个阶段的结果。无论处于何种模式，automation_always_ask 类别（is_always_ask_category helper）中的决策都必须提示用户。请参阅 .claude/docs/automation-modes.md。

阶段 0：解析配置

!bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" resolve_config --keys review_mode,automation,team.size,workflow

以上配置已解析 — 按原样使用；--review 会覆盖 review_mode。若未阻止 → 默认值见 .claude/docs/config-resolution.md。

review_mode 决定 director-gate 的深度，而此流水线没有 director gate： 无论 review_mode 取何值，以下阶段都不会生成 CD-、TD-、PR- 或 AD-PHASE-GATE。其阶段门是流水线自身的决策点（定义见下文 team.size），在这些决策点执行工作的 Agent 是团队成员，而非 director gate。

automation 决定上方的 Decision Points 说明。有关各模式如何改变流水线行为，请参阅上方的 Decision Points 说明和 .claude/docs/automation-modes.md。

team.size：哪些 Agent 处于激活状态（与 review_mode 的 gate 深度和工作流文档互不相关）。

• individual（默认）：performance-analyst + technical-artist。通过这两者咨询其他 Agent，而不单独生成。没有程序员处于激活状态，因此本次运行不会实施优化列表中的程序员事项 — 报告会注明该列表已交给 /dev-story（阶段 2）。
• small：+ sound-designer + qa-tester + engine-programmer；如果阶段 1 的跟踪将原因定位到内容创作工具，还会加入 tools-programmer（如文档所述的完整流水线）。
• studio：small 集合，包含 engine-programmer，+ 对抗式审查环节：阶段 5 会告知 qa-tester：“你的工作不是确认它能否正常运行 — 而是找出它会如何失效”，报告会注明已执行此环节。此流水线没有可扩展范围的引擎专家；引擎级工作仍由 engine-programmer 负责。

在 individual 模式下，需要的非核心 Agent 会通过最近的激活核心 Agent 路由，并附带说明性备注。“阶段门”是指此流水线明确列出的任何以 AskUserQuestion 决策点结束的阶段 — 即上方 Decision Points 中的转换，或下文流水线中写明的 Gate 步骤 — 不受 automation 模式影响。 guided 和 autonomous 会改变通过阶段门的方式（自动推进，或使用 log_decision 记录），而不会改变它是否属于阶段门，因此下方有界例外条件 (3) 在所有模式下均适用。仅限于“阶段门”的 Agent 会在这些节点生成，不会在其他节点生成。此激活集范围适用于下方整个流水线：任何阶段提及激活集之外的 Agent 时，都应通过最近的核心 Agent 路由，而不是生成该 Agent。

阶段 1 之前先说明激活集 — 绝不能默默缩减。 生成任何 Agent 之前，用一行说明本次运行实际会生成哪些 Agent，以及下方流水线提及但在解析出的 team.size 下不会生成哪些 Agent。例如：

激活集（team.size：<已解析值>）：<上方针对该规模列出的 Agent>。 本次运行不生成：<此流水线提及的所有其他 Agent> — 通过 <最近的激活核心 Agent> 咨询。提高 team.size（或 modes.rigor）以扩大范围。

直接根据上方的 team.size 列表和本文件流水线中提及的 Agent 填写 — 不要照搬示例。不同编排器的两组内容各不相同。

下方流水线看起来是多 Agent 扇出结构，但在随附默认配置下只会有一个或两个 Agent — team-release 提及十个 Agent，但只运行一个；team-narrative 在五个阶段中提及六个 Agent，但只运行 writer。这种缩减是正确的： team.size 以严谨度为先，而默认的窄范围是控制 token 用量的手段。 如果不说明，读者就无法区分正确缩减的运行与损坏的流水线；上文逐 Agent 规定的“通过最近的核心 Agent 路由，并附带说明性备注”规则会在路由时生效，却始终不会说明整个运行的整体形态。

这与本文件其他部分关于报告跳过检查的规则相同：一项已执行但从未明确说明的限制，对于阅读输出的人来说，和从未执行过没有区别。

团队组成

• performance-analyst — 性能分析、内存分析、帧预算和优化清单——不编写游戏代码
• engine-programmer — 实施优化清单中的引擎级项目：渲染管线、内存、资源加载、热点路径（performance-analyst 找出底层根因时调用）
• technical-artist — VFX 润色、着色器优化、视觉质量
• sound-designer — 音频润色、混音、环境音层、反馈音效
• tools-programmer — 内容管线工具验证、编辑器工具稳定性、自动化修复（第 2 阶段，在第 1 阶段追踪到原因与内容创作工具有关时）
• qa-tester — 边缘情况测试、回归测试、长时间浸泡测试

如何委派

使用 Agent 工具将每位团队成员作为子 Agent 启动：

• subagent_type: performance-analyst — 性能分析、内存分析、优化清单
• subagent_type: engine-programmer — 优化清单中的引擎级修复：渲染、内存、资源加载
• subagent_type: technical-artist — VFX 润色、着色器优化、视觉质量
• subagent_type: sound-designer — 音频润色、混音、环境音层
• subagent_type: tools-programmer — 优化清单中的内容管线和编辑器工具修复
• subagent_type: qa-tester — 边缘情况测试、回归测试、长时间浸泡测试

向每个 Agent 提供简要说明——不要倾倒上下文。 只读取一次共享输入，并在说明中内联传递提炼后的内容：只提供每个 Agent 实际需要的行，绝不要提供你已读过的文档路径（拿到路径的 Agent 会重新读取整个文件）。仅当你尚未读过某份文档且只有该 Agent 需要它时，才传递路径。

每条 Agent 提示词都必须以返回约定结尾：“将完整输出写入 [path]——根据下文的有限例外规定，该指定路径即为你获准写入的位置，因此请直接写入，无需另行请求批准。仅返回 (1) 写入的路径，(2) 不超过 5 条的决策摘要，(3)任何 BLOCKED/CONCERNS 项，每项一行。不要复述你读过的文档。”没有此约定时，Agent 会把读到的所有内容都返回到当前会话。**实现文件属于例外：**编写代码或资源的 Agent 应先返回将要创建或修改的文件；只有你询问过文件列表且用户同意后，其返回约定才能列出这些文件（文件写入协议）——用户的答复，而非有限例外，才授权写入这些文件。

用真实路径替换 [path]——此技能的目标目录是 production/polish/。 按 Agent 区分命名，每个 Agent 一个文件：

Agent	写入位置
performance-analyst	production/polish/[area]-report-[date].md
technical-artist	production/polish/[area]-render-notes-[date].md
engine-programmer	production/polish/[area]-engine-fixes-[date].md
tools-programmer	production/polish/[area]-tool-fixes-[date].md
sound-designer	production/polish/[area]-audio-notes-[date].md
qa-tester	production/polish/[area]-verification-[date].md

为什么使用 production/ 而不是 docs/。 这些是单次运行的带日期测量结果，形式与 production/qa/smoke-[date].md 相同——不是像 docs/architecture/ 那样的长期规范。将它们与其他特定时间点的流程产物放在一起，才能进行后续比较。

上述 [path] 约定有一个前提：路径必须由你指定，因此这里必须给出具体目标位置，否则每次运行都会临时决定一个位置。与目标位置由使用方固定的 /team-qa 和 /team-narrative 不同，此处在代码库中没有读取方，是经过有意选择的。 目前还没有任何内容读取 production/polish/——报告时请说明这一点，让用户知道这份报告只是记录，而不是后续门禁的输入。 为什么这不会违反协作协议。 CLAUDE.md 要求 Agent 在执行 Write/Edit 前询问“我可以将此内容写入 [filepath] 吗？”。此处启动的子 Agent 会直接写入，不会询问；这是有意设定且范围有限的例外，并非疏忽——这与之前允许 consistency-check 追加内容到 active.md 的做法相同。只有同时满足以下三个条件时，例外才适用：（1）路径由你在提示词中指定，因此用户在批准此阶段时也批准了目标位置；（2）这是 production/、docs/ 或 tests/ 下的新产物，绝不修改现有源文件或配置；（3）产出该内容的阶段本身受 AskUserQuestion 控制，必须先征求用户意见才能进入下一阶段。以上三项之外，Agent 都必须询问。不要通过让每个子 Agent 都询问来“修复”此问题——每个阶段的每个 Agent 都单独发送提示词会让编排器无法使用，因此才需要这个例外。

在工作流允许的情况下，并行启动互不依赖的 Agent（例如，阶段 3 和 4 可以同时运行）。

工作流

阶段 1：评估

委派给 performance-analyst：

• 使用 /perf-profile 对目标功能／区域进行性能分析
• 找出性能瓶颈和超出帧预算的情况
• 测量内存用量并检查是否存在泄漏
• 根据目标硬件规格进行基准测试
• 输出：性能报告，并附上按优先级排列的优化清单——每项需列出变更内容、预期预算收益及负责人（渲染侧变更由 technical-artist 负责；引擎系统和热点路径由 engine-programmer 负责；内容创作工具由 tools-programmer 负责；其他情况由负责该系统的程序员负责）

阶段 2：优化

performance-analyst 不编写游戏代码（其 Agent 文件规定其职责为“提出建议并分配任务”），因此阶段 2 由活跃组中的负责人落实阶段 1 的清单：

• engine-programmer——仅当阶段 1 确认根本原因属于引擎层级（渲染管线、资源加载、内存分配器、核心循环中的热点路径）时启动：落实相关项目、缓解分配压力，并验证游戏行为未发生变化。输出：引擎层级修复，以及修复前后的指标和分析器验证结果
• tools-programmer——仅当阶段 1 将原因追溯到内容创作工具时启动：修复该工具。输出：工具修复及修复前后的指标
• technical-artist——渲染侧项目（绘制调用、过度绘制、粒子、着色器、LOD）纳入其阶段 3 的任务说明

阶段 2 至 4 中的每个实施 Agent 都必须先返回其将创建或修改的文件，然后你需针对阶段 2 至 4 的全部文件一次性征求许可，再进行任何编辑（文件写入协议）。

负责人不在活跃组中的项目不会在本次运行中实施。 当 team.size: individual 时，所有程序员负责的项目都属于这种情况，因为没有程序员处于活跃状态；无论组规模如何，还包括由此工作流未指定的程序员负责的项目（例如，由 gameplay-programmer 负责的游戏脚本热点）。报告会在“交由 /dev-story 处理的优化清单：production/polish/[area]-report-[date].md”下列出这些项目及其负责人。 若其针对的指标超出预算，该问题将在阶段 6 继续作为已知问题保留。

阶段 3：视觉润色（与阶段 2 并行）

委派给 technical-artist：

• 检查 VFX 的质量，以及其与美术圣经的一致性
• 优化粒子系统和着色器效果
• 适当添加屏幕震动、摄像机效果和视觉表现力
• 确保效果在较低设置下也能平稳降级
• 输出：润色后的视觉效果

阶段 4：音频润色（与阶段 2 并行）

委派给 sound-designer：

• 检查音频事件是否完整（是否有操作缺少声音反馈？）
• 检查音频混音音量——相对于混音整体，任何声音都不能过响或过轻
• 添加营造氛围的环境音层
• 验证音频的空间定位播放是否正常
• 输出：音频润色清单和混音说明

阶段 5：强化测试

委派给 qa-tester：

• 测试所有边界情况：边界条件、快速输入、异常序列
• 长时间稳定性测试：长时间运行该功能，检查是否出现性能退化
• 压力测试：最多实体数、最坏情况
• 回归测试：验证润色更改未破坏现有功能——逐项检查阶段 2–4 的每项更改（按名称），包括引擎级修复
• 在最低规格硬件上测试（如有）
• 输出：测试结果以及任何遗留问题

阶段 6：签核

• 收集团队所有成员的结果
• 对照预算比较性能指标
• 报告：可发布 / 未评估 / 需要更多工作
• 列出每个遗留问题及其严重程度（S1–S4）、有测量结果时的差距（例如：“9 ms，对照 6 ms 的预算，超出 3 ms”）和建议；如果是回归问题，还需注明被破坏的行为以及导致问题的润色更改

未评估的优先级高于可发布，低于需要更多工作。 已知问题——指标超出预算、回归问题尚未解决——无论其他项目是否检查过，都意味着需要更多工作。否则，只要范围内有任何部分未能检查，结果就是未评估，绝不能标为可发布；报告必须列出每个缺口：

• 指标没有已确定的预算。performance.target_framerate、 performance.frame_budget_ms、performance.draw_call_limit 和 performance.memory_ceiling_mb 均无默认值，/perf-profile 会将未设置的预算报告为未评估——因为没有进行比较，所以不能认为符合预算。
• 某个阶段未执行：处于阻塞状态、被跳过，或其 Agent 不在活动集内。 当 team.size: individual 时，只有通过活动 Agent 才会征询 sound-designer 的音频润色和 qa-tester 的强化测试，不会实际执行；阶段 2 的程序员事项则交由 /dev-story，而不是在此处实现。

错误恢复协议

首先，验证产物。 如果返回契约指定了路径，在认定阶段已完成前，先检查该路径是否存在——指定的产物若未写入磁盘，该阶段就算失败，无论回复写得多么流畅。 Agent 可能耗尽整个阶段，却只返回看似合理的前言，实际什么都没写；这既不是阻塞状态，也不是错误或“无法完成”，因此下方的触发条件永远不会生效。请明确指出未满足的契约并恢复执行；上下文通常仍然可用。

如果任何已启动的 Agent 返回阻塞状态、出错或无法完成：立即说明情况，不要越过受其阻塞的依赖继续执行，并始终生成部分报告。 被跳过的 Agent 对应部分应保留为明确列出的缺口，绝不能自行补写内容。完整流程见：.claude/docs/error-recovery-protocol.md。

常见阻塞情况：

• 缺少输入文件（未找到故事文件、缺少 GDD）→ 转交给负责创建该文件的技能
• ADR 状态为 Proposed → 不要实现；待其确定后，使用 /architecture-decision accept ADR-NNNN 接受
• 范围过大 → 通过 /create-stories 拆分为两个故事
• ADR 与故事中的指示冲突 → 明确指出冲突，不要自行猜测

文件写入协议

所有文件写入（性能报告、测试结果、证据文档）均委派给通过 Agent 启动的子 Agent。这些写入遵循上文“为何这不违反协作协议”一节中记载的有限例外——路径由你指定，产物是在 production/、docs/ 或 tests/ 下新建的文件，且该阶段受 AskUserQuestion 控制。在这些界限内，子 Agent 无需针对每次写入单独询问；超出界限时则必须先询问。阶段 2–4 的优化和润色更改会编辑现有代码、着色器、音频或资产，因此不属于这些例外范围：每个负责实现的 Agent 都要返回其将创建或更改的文件，然后你针对阶段 2–4 的全部文件一次性询问（“我可以让 [agents] 更改这 [N] 个文件吗？”），只有在得到肯定答复后，各 Agent 才能开始编辑——针对整个文件集合询问一次，而不是每个阶段各询问一次。此协调器不会直接写入文件。

输出

一份摘要报告，涵盖：优化前后的性能指标、视觉润色的改动、音频润色的改动、测试结果、交给 /dev-story 的优化清单，以及发布就绪评估。

后续步骤

• 如果结果为 READY FOR RELEASE：运行 /release-checklist，进行最终发布前验证。
• 如果结果为 NEEDS MORE WORK：在 /sprint-plan update 中安排剩余问题（对于 workflow: minimal，由于没有冲刺，请将它们添加到简报的构建顺序中），修复后重新运行 /team-polish。
• 如果结果为 NOT ASSESSED：补充缺失内容——在 project.yaml（/settings）中提交尚未设置的 performance.* 预算，或运行尚未执行的阶段（增大 team.size）——然后重新运行 /team-polish。不得将该领域视为已达到发布就绪状态。
• 如果报告向 /dev-story 提交了优化清单：在那里实现这些条目，然后重新运行 /team-polish 以衡量效果。
• 在移交发布之前，运行 /gate-check，获取正式的阶段门禁评估结果。