team-audio

Team Audio

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

用法：/team-audio [要设计音频的功能或区域] [--review full|lean|solo] — 指定要设计音频的功能或区域（例如：combat、main menu、forest biome、boss encounter）。此处不要使用 AskUserQuestion；直接输出指南。

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

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

Phase 0：解析配置

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

已在上方解析——按原样使用；--review 会覆盖 review_mode。没有阻止项 → 使用 .claude/docs/config-resolution.md 中的默认值。

review_mode 设置 director gate 的深度，而此流程不设 director gate： 无论 review_mode 为何，以下阶段都不会启动 CD-、TD-、PR- 或 AD-PHASE-GATE。其阶段 gate 是流程自身的决策点（定义见下方 team.size），参与这些节点工作的 Agent 是团队成员，而非 director gate。

automation 驱动上方的“决策点”说明。有关各模式如何改变流程行为，请参阅上方的“决策点”说明和 .claude/docs/automation-modes.md。

team.size：哪些 Agent 处于启用状态（与 review_mode 的 gate 深度和工作流文档相互独立）。

• individual（默认）：仅 sound-designer。其他 Agent 由 sound-designer 咨询，不单独启动。
• small：增加 audio-director + technical-artist + gameplay-programmer。
• studio：增加 accessibility-specialist + 主要引擎专家（按文档执行完整流程）。 在 individual 下，需要参与的非核心 Agent 会通过最近的启用核心 Agent 处理，并附带说明性提示。“阶段 gate”指此流程自身列出的、以 AskUserQuestion 决策点结束的任何阶段——即上方“决策点”中所述的转换，或下方流程中列出的 Gate 步骤——无论 automation 模式如何。 guided 和 autonomous 会改变通过 gate 的方式（自动推进，或通过 log_decision 记录），但不会改变它是否属于阶段 gate；因此，下方有界例外条件 (3) 在所有模式下均适用。仅限“阶段 gate”的 Agent 会在这些节点启动，不会在其他节点启动。以下流程中的启用集范围规则始终适用：任何阶段若指定了启用集之外的 Agent，则改由最近的核心 Agent 处理，而不启动该 Agent。

在 Step 1 之前公布启用集——绝不能悄悄省略。 启动任何内容之前，用一行说明本次运行实际会启动哪些 Agent，以及流程下方提及但在解析出的 team.size 下不会启动哪些 Agent。例如：

Active set (team.size: <已解析值>): <上方列出的该规模对应的 Agent。> Not spawned this run: <本流程提及的所有其他 Agent> — 由 <最近的启用核心 Agent> 代为咨询。提高 team.size（或 modes.rigor）以扩大范围。

请直接根据上方的 team.size 列表和此文件自身流程中提及的 Agent 填写，不要照搬示例。每个协调器的两组内容都不相同。 下面的流水线看起来会将任务分发给多个 Agent，但按已发布的默认配置，它实际上只运行一个或两个 Agent——team-release 列出了十个 Agent，但只运行一个；team-narrative 在五个阶段中列出了六个 Agent，但只运行 writer。这种收缩是正确的：team.size 优先保证严谨性，而较窄的默认配置是节省 token 的手段。 如果不说明这一点，读者就无法判断这是正确收缩的运行，还是流水线出了问题；而上文每个 Agent 的“通过最近的核心 Agent 路由，并附上说明性备注”规则会在路由时触发，却从未说明整个运行的整体形态。

这与本文件其他位置对跳过检查的报告遵循同一规则：对阅读输出的人来说，已执行但从未明示的约束，和从未执行的约束没有区别。

1. 读取目标功能或区域的论述（例如 combat、main menu、forest biome、boss encounter）。

2. 收集上下文：

   • 按章节阅读 design/gdd/ 中与该功能相关的设计文档：使用 Grep 工具（匹配模式 ^#，内容模式）查找所需标题，再使用带有 offset 和 limit 的 Read 工具读取相应范围
   • 如果存在音效圣经，阅读 design/audio/sound-bible.md。如果只有 design/gdd/sound-bible.md（早期版本将其放在此处），则阅读该文件，并建议将其移至 design/audio/——在 design/gdd/ 中，GDD 检查会将每个文件都计为系统 GDD。如果两个位置都不存在，请用一行说明：“design/audio/sound-bible.md 中没有音效圣经；音频方向仅从 GDD 开始”，以便在输出中明确显示这一缺失。继续说明这一缺失：在 audio-director 的 Step 1 简报中提及，并在 Next Steps 中建议创建音效圣经。
   • 阅读 assets/audio/ 中现有的音频资源清单
   • 阅读该区域现有的任何音效设计文档

如何委派

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

• subagent_type: audio-director — 声音标识、情绪基调、音频风格
• subagent_type: sound-designer — 音效规格、音频事件、混音组
• subagent_type: accessibility-specialist — 关键音频的视觉替代方案和字幕、听觉敏感度
• subagent_type: technical-artist — 音频中间件、总线结构、内存预算
• subagent_type: [primary engine specialist] — 验证该引擎的音频集成模式
• subagent_type: gameplay-programmer — 音频管理器、游戏玩法触发器、自适应音乐

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

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

将 [path] 替换为真实路径。 工作产物放在 production/audio/[feature]/ 下，其中 [feature] 是参数转换成的 slug： 全部小写，空格 → 连字符（boss encounter → boss-encounter），并且与“保存到”步骤使用的 slug 相同。每位 Agent 写入一个文件，避免并行步骤共用同一文件：

步骤 / Agent	写入位置
1 audio-director	production/audio/[feature]/direction.md
2 sound-designer	production/audio/[feature]/sfx-spec.md
2 accessibility-specialist	production/audio/[feature]/accessibility.md
3 technical-artist	production/audio/[feature]/integration-plan.md
3 engine specialist	production/audio/[feature]/engine-notes.md
4 gameplay-programmer	代码根目录和引擎的测试根目录——由一次实现请求列出的文件（文件写入协议），不属于有限例外范围

这些都是工作草稿；最终留存记录是你据此编写的音频设计文档。

为何这不违反协作协议。 CLAUDE.md 要求 Agent 在执行 Write/Edit 前询问“可以将此内容写入 [filepath] 吗？”。在此启动的子 Agent 会直接写入，不会先询问；这是有意设置的有限例外，并非疏忽——与此前对 consistency-check 追加写入 active.md 所作的授权相同。只有同时满足以下三项时，例外才适用：（1）路径由你在提示中指定，因此用户在批准该阶段时已批准目标位置；（2）这是 production/、docs/ 或 tests/ 下的新产物，绝不修改现有源文件或配置；（3）生成该产物的阶段本身受 AskUserQuestion 门控，未获批准不得推进工作流。除此之外，Agent 必须先询问。不要通过逐个询问子 Agent 来“修正”这一点——每阶段都逐个提示 Agent 会让编排器无法使用，因此才需要这个例外。

3. 按顺序编排音频团队：

第 1 步：音频方向（audio-director）

启动 audio-director Agent，以便：

• 定义此功能/区域的声音特征
• 指定情绪基调和音频风格
• 确定音乐方向（自适应层、分轨、过渡）
• 定义音频优先级和混音目标
• 制定自适应音频规则（战斗强度、探索、紧张感）

第 2 步：声音设计和音频无障碍（并行）

启动 sound-designer Agent，以便：

• 为每个音频事件创建详细的音效规格
• 定义声音类别（环境音、UI、游戏玩法、音乐、对话）
• 指定每种声音的参数（音量范围、音高变化、衰减）
• 规划包含触发条件的音频事件列表
• 定义混音组和闪避规则

同时启动 accessibility-specialist Agent，以便：

• 找出承载关键游戏玩法信息的音频事件（受到伤害、附近有敌人、目标完成），并要求为听障玩家提供视觉替代
• 指定字幕要求：哪些音频事件需要字幕、文本格式、屏幕显示时长
• 检查是否有任何游戏状态仅通过音频传达（所有状态都必须有视觉替代）
• 检查音频事件列表中是否有可能令听觉敏感玩家感到不适的事件（高频警报、突发的大音量事件）
• 输出：整合到音频事件规格中的音频无障碍要求列表

缺少视觉提示或字幕的关键游戏玩法音频事件，在报告中标记为 BLOCKING，而非建议项。除非用户在第 2 步决策节点解决该问题或明确接受，否则不会开始第 3 步。该决策节点会提供修复选项（视觉提示、字幕或触觉替代）以及停止选项；已接受的问题会列入摘要的待解决问题中。

第 3 步：技术实现（并行）

启动 technical-artist Agent，以便：

• 设计音频中间件集成（Wwise/FMOD/native）
• 定义音频总线结构和路由
• 指定各平台音频资源的内存预算
• 规划流式加载与预加载资源策略
• 设计任何音频响应视觉效果

同时启动主要引擎专家（从 engine.name 推导出 <engine>-specialist——Godot→godot-specialist、Unity→unity-specialist、Unreal→unreal-specialist；若无，则使用 .claude/docs/technical-preferences.md 中 ## Engine Specialists 的 Primary 行），以验证集成方案：

• 提议的音频中间件集成是否符合该引擎的惯用方式？（例如，Godot 的内置 AudioStreamPlayer 与 FMOD、Unity 的 Audio Mixer 与 Wwise、Unreal 的 MetaSounds 与 FMOD）
• 是否应采用任何特定于引擎的音频节点/组件模式？
• 固定的引擎版本中是否存在会影响集成计划的已知音频系统变更？
• 输出：引擎音频集成说明，与 technical-artist 的计划合并

如果未配置引擎，则跳过专家 Agent 的启动。在本次运行的输出中记录 Engine validation: NOT ASSESSED — no engine configured (`engine.name` unset in `project.yaml`)。 若跳过检查时不作任何说明，就无法区分检查通过和从未征询引擎指导；读者无法得知并未进行引擎验证。

第 4 步：代码集成（gameplay-programmer）

启动 gameplay-programmer Agent，以便：

• 实现音频管理器系统，或审查现有系统
• 将音频事件接入游戏玩法触发器
• 实现自适应音乐系统（如有指定）
• 设置音频遮挡／混响区域
• 为音频事件触发器编写单元测试

4. 汇总音频设计文档，整合所有团队成员的输出。

5. 保存到 design/audio/audio-[feature].md — 但要先询问。 design/ 不属于有界写入例外所涵盖的三个目录（production/、docs/、tests/），因此，若将此路径交给子 Agent，子 Agent 必须先询问。不要通过扩大例外范围来解决此问题。应遵循 team-level使用的相同模式：**你**已经掌握每个子 Agent 的输出，因此由你自行汇总文档，并通过AskUserQuestion直接询问：“我可以将音频设计写入design/audio/audio-[feature].md吗？”获得批准后再写入。如果design/audio/` 不存在，写入文件时会创建该目录。

   注意：如果跳过了引擎验证（未配置引擎），判定结果必须说明这一点，不能只写 COMPLETE：

   判定：COMPLETE — 未评估引擎验证（[原因]） — 音频设计文档已生成；引擎专家尚未审查集成计划。

如果流程因依赖项未解决而停止（例如，关键无障碍问题或用户未解决的 GDD 缺失）：

判定：BLOCKED — [原因]

6. 输出摘要，包括：音频事件数量、预估资源数量、实施任务，以及团队成员之间尚未解决的问题。

判定：COMPLETE — 音频设计文档已生成，团队流程已完成。

文件写入协议

每个 Agent 的产物（SFX 规格、集成计划）由产出该产物的子 Agent 写入，并遵循上文“为何这不违反协作协议”中记录的有界例外 — 路径由你指定，产物是 production/、docs/ 或 tests/ 下的新文件，且该阶段由 AskUserQuestion 控制。在这些范围内，子 Agent 无须逐次询问写入权限；超出范围则必须询问。实施文件 — gameplay-programmer 编写的音频集成代码，以及代码根目录或 assets/ 下的任何内容 — 不在这些范围内：Agent 会返回计划创建或更改的文件清单，你只需针对整组文件询问一次，获得批准后它才会写入。唯一例外是最终汇总的音频设计文档：协调者已掌握所有输入，因此由协调者自行汇总，并在其自己的“我可以写入……吗？”提示后写入 design/audio/audio-[feature].md（见上文“保存到”步骤）。

后续步骤

• 在开始实施前，与 audio-director 一起审查音频设计文档。
• 设计获批后，使用 /dev-story 实施音频管理器和事件系统。
• 创建音频资源后，运行 /asset-audit，以验证命名和格式是否符合要求。
• 如果没有声音圣经，请在下一轮音频制作前创建一份：让 audio-director Agent 根据 .claude/docs/templates/sound-bible.md 起草 design/audio/sound-bible.md，并以本次运行的第 1 步方向为起点（在 design/ 下写入前会先询问）。

错误恢复协议

首先，验证产物。 如果返回约定指定了路径，请先检查该路径是否存在，再将阶段视为完成——指定的产物未写入磁盘，即表示阶段失败，无论回复读起来多么流畅。 Agent 可能耗费整个阶段，却只返回一段看似合理的开场白，实际上什么也没写；这既不属于 BLOCKED，也不是错误或“无法完成”，因此下方的触发条件永远不会触发。请通过指出未满足的约定来恢复任务；上下文通常仍然保留。

如果任何生成的 Agent 返回 BLOCKED、出错或无法完成：立即报告，不要越过其阻塞的依赖，并始终提供部分报告。 被跳过的 Agent 所负责的部分应保留为明确标示的缺口——绝不要自行补充内容。完整流程：.claude/docs/error-recovery-protocol.md。

常见阻碍：

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