team-combat

团队战斗

**参数检查：**如果未提供战斗功能描述，输出：

"用法：/team-combat [战斗功能描述] [--review full|lean|solo] — 请提供要设计和实现的战斗功能描述（例如：近战招架系统、远程武器散布）。" 然后立即停止，不要生成任何子 Agent，也不要读取任何文件。

使用有效参数调用此技能时，通过结构化流程协调战斗团队。

**决策点：**在每个阶段转换时，使用 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 决定主管关卡的深度，而此流程没有主管关卡： 无论 review_mode 为何，以下阶段都不会生成 CD-、TD-、PR- 或 AD-PHASE-GATE。其阶段关卡是流程自身的决策点（定义于下方的 team.size），参与这些关卡工作的 Agent 是团队成员，而非主管关卡。

automation 决定上方“决策点”说明中所述的行为。关于各模式如何改变流程行为，请参见上方的“决策点”说明和 .claude/docs/automation-modes.md。

workflow 决定阶段 1 设计文档的详略程度，方式与 /design-system 相同： full 包含 ## Summary 和全部 8 个章节；standard 包含 Overview、Detailed Design、Edge Cases、Dependencies 和 Acceptance Criteria，并在机制定义了数值规则时加入 Formulas（战斗机制几乎总是如此）；minimal 以游戏概要作为设计记录，GDD 为可选项——起草上述五个章节，并告知用户在此工作流级别下 GDD 是可选的。 team.size：哪些 Agent 处于活动状态（与 review_mode 的门禁深度和工作流文档正交）。

• individual（默认）：由 gameplay-programmer 运行流水线；仅当功能涉及 AI 工作时才升级至 ai-programmer。其他团队组成中的 Agent 由 gameplay-programmer 咨询，不会单独启动。
• small：运行下方文档所述的完整团队组成流水线。
• studio：完整流水线 + 引擎子专家 + 对抗式审查环节。引擎子专家：主引擎专家的提示词说明，它可以将部分审查工作交给其 tools: 授权中列出的子专家（例如负责能力的 ue-gas-specialist）；在 studio 级别下，由主专家独自回答。对抗式审查环节：告知 Phase 5 的 qa-tester“你的任务不是确认它能正常运行，而是找出它会如何出错”，并在报告中说明该环节已执行。 在 individual 级别下，所需的非核心 Agent 会通过最近的活动核心 Agent 进行处理，并附带说明性备注。“阶段门禁”是指本流水线列出的任何一个以 AskUserQuestion 决策点结束的阶段——包括上方决策点中的转换，或下方流水线中明确写出的 Gate 步骤——与 automation 模式无关。guided 和 autonomous 会改变通过门禁的方式（自动推进，或通过 log_decision 记录），但不会改变它是否属于阶段门禁，因此下方有界例外条件（3）在所有模式下都适用于此处。仅限“阶段门禁”的 Agent 只会在这些节点启动，不会在其他节点启动。此活动集范围规则适用于下方整个流水线：任何阶段提及活动集之外的 Agent 时，都会通过最近的核心 Agent 处理，而不是启动该 Agent。

在 Phase 1 之前公布活动集——绝不能默默缩减。 启动任何 Agent 之前，用一行说明本次运行实际会启动哪些 Agent，以及下方流水线提及但在已确定的 team.size 级别下不会启动哪些 Agent。例如：

活动集（team.size: <已确定的值>）：<上方针对该级别列出的 Agent>。 本次运行不启动：<此流水线提及的其他所有 Agent> — 通过 <最近的活动核心 Agent> 咨询。提高 team.size（或 modes.rigor）可扩大范围。

直接根据上方的 team.size 列表和本文件流水线中提及的 Agent 填写，不要使用示例内容。每个编排器的这两组内容都不相同。

下方流水线看起来是多 Agent 扇出，但在发布时的默认设置下只会启动一两个 Agent——team-release 列出十个，只运行一个；team-narrative 在五个阶段中列出六个，却只运行 writer。这种缩减是正确的： team.size 以严谨程度为先，较窄的默认范围是控制令牌用量的手段。 如果不明确说明，读者就无法区分这是正确缩减的运行，还是已损坏的流水线；而上方“通过最近的核心 Agent 处理，并附带说明性备注”规则会在路由时生效，却不会说明整个运行的整体情况。

这与本文件其他位置关于报告跳过的检查项的规则相同：对读者而言，已执行但从未明确说明的约束，与从未执行的约束无法区分。

团队组成

• game-designer — 设计机制，定义公式和边缘情况
• gameplay-programmer — 实现核心游戏玩法代码
• ai-programmer — 为此功能实现 NPC／敌方 AI 行为
• technical-artist — 创建 VFX、着色器效果和视觉反馈
• sound-designer — 定义音频事件、冲击音效和环境战斗音频
• 引擎专家（主专家）— 验证架构和实现模式是否符合该引擎的惯用做法（主专家为 engine.name 对应的 <engine>-specialist：Godot→godot-specialist、Unity→unity-specialist、Unreal→unreal-specialist；如无对应项，则使用 technical-preferences.md 中 ## Engine Specialists 的 Primary 行）
• qa-tester — 编写测试用例并验证实现

如何委派

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

• subagent_type: game-designer — 设计机制、定义公式和边缘情况
• subagent_type: gameplay-programmer — 实现核心玩法代码
• subagent_type: ai-programmer — 实现 NPC／敌人的 AI 行为
• subagent_type: technical-artist — 制作 VFX、着色器效果和视觉反馈
• subagent_type: sound-designer — 定义音频事件、冲击音效和环境音频
• subagent_type: [primary engine specialist] — 验证架构和实现是否符合引擎惯例
• subagent_type: qa-tester — 编写测试用例并验证实现

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

每条 Agent 提示的结尾都必须包含交付约定：“将完整输出写入 [path]——该指定路径即为下方有限例外条款所授予的写入权限，请直接写入，无需另行请求批准。仅返回 (1) 写入的路径，(2) 不超过 5 条的决策摘要，(3) BLOCKED／CONCERNS 项，每项各占一行。不要复述你读取过的文档。”若没有这段约定，Agent 会把它读取的所有内容都回传到本会话中。**实现文件是例外：**编写代码或资源的 Agent 必须先返回拟创建或修改的文件清单；只有在你询问一次并且用户同意后（文件写入协议），交付约定中才能列出这些文件。用户的答复，而非有限例外条款，才是这些写入操作的授权。

将 [path] 替换为实际路径。 每个会产出成果的阶段都必须指定路径；大多数路径由已负责读取它们的技能固定：

阶段／Agent	写入位置	目标路径由以下内容固定
1 game-designer（草稿）	production/combat/[feature]-gdd-draft.md	本技能——你要在 Phase 1 编写最终的 design/gdd/[feature].md
2 gameplay-programmer	docs/architecture/[feature]-sketch.md	见下方说明
2 engine specialist	docs/architecture/[feature]-engine-notes.md	见下方说明
3 gameplay-programmer、ai-programmer、technical-artist	代码根目录和 assets/——由 Phase 3 批准清单列出的文件	不属于有限例外范围：须先询问一次以确定文件清单（文件写入协议）
3 sound-designer	production/combat/[feature]-audio-events.md	本技能
5 qa-tester（测试用例）	production/qa/test-cases/[feature]-cases.md	/team-qa Phase 4
5 qa-tester（缺陷）	production/qa/bugs/BUG-[NNNN].md	/team-qa Phase 5

Phase 6 是口头状态报告，不是成果文件——无需指定路径。

上述每个阶段都刻意指定了具体的目标位置。 下方的错误恢复协议指出，“未写入磁盘的指定成果文件意味着阶段失败”——如果没有指定路径，就无法执行此项检查。

两个 docs/architecture/ 条目属于具体判断，并非惯例。 该目录存放 ADR（adr-NNNN-*.md）；草案是 ADR 的前置材料，而非 ADR 本身，且仓库中没有任何内容会读取这两个文件。汇报时请说明这一点，以便明确草案只是记录，而不是后续关卡的输入。 为什么这不会违反 Collaboration Protocol。 CLAUDE.md 要求 Agent 在执行 Write/Edit 前询问“可以将内容写入 [filepath] 吗？”。在此处启动的子 Agent 会直接写入，不会先询问；这是有意设置且范围明确的例外，并非疏忽——这与允许 consistency-check 追加内容到 active.md 时采用的例外相同。只有以下三项条件全部满足时，例外才适用：（1）路径由你在提示词中指定，因此用户批准该阶段时也就批准了写入目标；（2）这是 production/、docs/ 或 tests/ 下的新产物，绝不是对现有源文件或配置文件的编辑；（3）产出该内容的阶段本身设有门控，在工作流推进前会通过 AskUserQuestion 征求确认。三项条件之外，Agent 必须先询问。不要通过逐个询问子 Agent 来“修复”此问题——每个 Agent 在每个阶段都要收到一个提示，会让协调器变得无法使用；这正是设置该例外的原因。

只要工作流允许，就并行启动互不依赖的 Agent（例如，Phase 3 的 Agent 可以同时运行）。

工作流

Phase 1：设计

委派给 game-designer：

• 根据 .claude/docs/templates/game-design-document.md，为 design/gdd/[feature].md 创建或更新设计文档，包含 ## Summary 和 workflow（Phase 0）要求的章节——在 full 模式下，还需包含机制概述、玩家幻想、详细规则、含变量定义的公式、边缘情况、依赖项、含安全范围的调优参数，以及验收标准
• 输出：完成的设计文档草稿，写入 production/combat/[feature]-gdd-draft.md

design/ 不在上述有界写入例外的范围内，因此由 game-designer 起草，而由你写入 GDD——/team-level 和 /team-narrative 采用的模式。在 Phase 1 的决策节点，展示草稿并通过 AskUserQuestion 询问：“可以将设计文档写入 design/gdd/[feature].md 吗？”获得批准后再写入；在得到答复前，不得在 design/ 下写入任何内容。

Phase 2：架构

委派给 gameplay-programmer（若涉及 AI，则同时委派给 ai-programmer）：

• 审阅设计文档，按章节阅读：使用 Grep 工具（pattern ^#，content mode）查找所需标题，再通过 offset 和 limit 使用 Read 读取对应范围
• 设计代码架构：类结构、接口、数据流
• 找出现有系统的集成点
• 输出：包含文件列表和接口定义的架构草图

然后启动主要引擎专家，验证拟议的架构：

• 类／节点／组件结构是否符合指定引擎的惯用做法？（例如，Godot 节点层级、Unity MonoBehaviour 与 DOTS、Unreal Actor／Component 设计）
• 是否应使用引擎原生系统，而不是自定义实现？
• 拟议的 API 是否已弃用，或在指定引擎版本中发生变化？
• 输出：引擎架构说明——在 Phase 3 开始前将其纳入架构

如果未配置引擎，则跳过专家启动。**在本次运行的输出中记录 Engine validation: NOT ASSESSED — no engine configured (`engine.name` unset in `project.yaml`)。**跳过检查却不作说明，无法与检查通过区分。

使用 AskUserQuestion：

• 提示：“架构草图已完成。请批准后继续并行实施。”
• 选项：
  • [A] 继续——启动实施 Agent（gameplay-programmer、ai-programmer、technical-artist、sound-designer）
  • [B] 先修改架构——我会说明需要更改的内容
  • [C] 暂停于此——我稍后继续

仅当用户选择 [A] 时才启动实施 Agent。（在 guided／autonomous 模式下，此架构门控属于常规阶段转换——除非架构草图返回 BLOCKED，否则继续实施；在 autonomous 模式下通过 log_decision 记录该决定。该门控不属于发布关键决策，也不会造成不可逆影响，因此遵循标准工作流规则。）

阶段 3：实现（尽可能并行）

并行委派：

• gameplay-programmer：实现核心战斗机制代码
• ai-programmer：实现 AI 行为（如果该功能涉及 NPC 反应）
• technical-artist：制作 VFX 和着色器效果
• sound-designer：定义音频事件列表和混音说明，草拟到 production/combat/[feature]-audio-events.md

代码、VFX 和着色器工作不属于有限写入例外：这些 Agent 都要先返回将要创建或修改的文件，然后你一次性询问整个文件集，并且只有得到肯定答复后才让它们写入（文件写入协议）。

阶段 4：集成

• 将游戏玩法代码、AI、VFX 和音频串联起来
• 确保所有调节参数都已公开并由数据驱动
• 验证该功能能否与现有战斗系统协同工作

关卡：使用 AskUserQuestion 呈现集成结果并确认，然后再进入阶段 5。

阶段 5：验证

委派给 qa-tester：

• 根据验收标准编写测试用例
• 测试设计中记录的所有边缘情况
• 验证性能影响在预算范围内
• 为发现的任何问题提交 Bug 报告

阶段 6：签核

• 汇总所有团队成员的结果
• 报告功能状态：COMPLETE / NEEDS WORK / BLOCKED
• 列出所有未解决的问题及其负责人

错误恢复协议

首先，验证产物。 如果返回约定指定了路径，在判定阶段完成前先检查 该路径是否存在——指定的产物若未写入磁盘，该阶段就算失败，不论回复读起来 多么流畅。 Agent 可能耗费整个阶段，却只返回看似合理的开场说明，实际什么都没写； 这既不是 BLOCKED，也不是错误，更不是“无法完成”，因此下面的触发条件永远不会生效。 恢复该任务时要明确指出未满足的约定；上下文通常仍然保留。

如果任何已启动的 Agent 返回 BLOCKED、报错或无法完成：立即说明情况，不要越过它阻塞的依赖继续推进，并且务必提供部分报告。 被跳过的 Agent 对应的部分应保留为明确的缺口——绝不要自行补充内容。完整流程：.claude/docs/error-recovery-protocol.md。

常见阻塞因素：

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

文件写入协议

所有文件写入（设计草稿、实现文件、测试用例）都通过 Agent 启动的子 Agent 委派，并遵循以下两条规则：

• 草稿、构思和 QA 产物——路径表中位于 production/、docs/ 或 tests/ 下的目标路径——遵循上文 “为什么这不违反协作协议”中所述的有限例外：路径由你指定，产物是新建的， 且该阶段受 AskUserQuestion 控制。子 Agent 无需针对每次写入单独征求许可即可写入。
• 实现文件——阶段 3 的代码、VFX 和着色器文件，以及阶段 4 的任何集成编辑，位于代码根目录和 assets/ 下——不属于该例外，正如 Agent 自身的文件中所述。每个负责实现的 Agent 都要先返回将要创建或修改的文件，并为每个文件附上一行摘要；一次性询问整个文件集（“我可以让 [agents] 写入这 [N] 个文件吗？”），并且只有得到肯定答复后才让它们写入。对现有文件的任何编辑都必须列入该清单，绝不能由阶段 3 前的关卡默认为已获批准。

唯一例外是设计文档：编排者在阶段 1 获得自己的“我可以写入……吗？”提示确认后，根据 game-designer 的草稿自行编写 design/gdd/[feature].md。除此之外，不写入任何其他文件。

输出

涵盖以下内容的摘要报告：设计完成状态、各团队成员的实现状态、测试结果和未解决的问题。

结论：COMPLETE — 战斗功能已完成设计、实现和验证。

如果跳过引擎验证（阶段 2，未配置引擎），结论会明确说明这一点 — 绝不会只写 COMPLETE：

结论：COMPLETE — engine validation NOT ASSESSED ([reason]) — 战斗功能已完成设计、实现和验证；引擎专家从未审查架构。

结论：NEEDS WORK — 所有阶段均已运行，但阶段 5 验证仍有未解决的失败或错误；报告会逐项列出并注明负责人。

结论：BLOCKED — 一个或多个阶段无法完成，或某个 Agent 被跳过（.claude/docs/error-recovery-protocol.md 第 5 步）；已生成部分报告，并列出未解决的事项。

后续步骤

• 在关闭故事前，对已实现的战斗代码运行 /code-review。
• 运行 /balance-check，验证战斗公式和调优值。
• 如果需要打磨 VFX、音频或性能，请运行 /team-polish。