map-systems

!bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" resolve_config --keys review_mode,automation,workflow,docs.density,project.stage

上方已解析——按原样使用；--review 会覆盖 review_mode。没有区块 → 默认值见 .claude/docs/config-resolution.md。

映射系统

调用此技能时：

解析参数

两种模式：

• 无参数：/map-systems — 运行完整的分解工作流（阶段 1-5）， 创建或更新系统索引。
• next：/map-systems next — 从索引中选出优先级最高且尚未设计的系统， 并移交给 /design-system（阶段 6）。

完整的检查模式见 .claude/docs/director-gates.md。各项检查门的定义位于 .claude/docs/director-gates/[gate-id].md — 启动的 Agent 会读取自己的检查门文件；父会话不要读取该文件。

每次 AskUserQuestion 调用都遵循 .claude/docs/automation-modes.md （协作模式始终提问 · 引导模式仅对重大事项提问 · 自主模式记录并继续； automation_always_ask 类别始终会提示）。在协作模式下，系统列表、依赖关系、优先级和写入审批会分别提问： 每一步都会等待用户回答后再执行下一步。

docs.density — 控制每个章节的深度，而 workflow 控制哪些章节存在。modes.rigor 会同时设置二者；若只想调整深度，请显式设置 docs.density：terse（默认值，通过 rigor: minimal 设置）= 每个系统一行描述； balanced = 每个系统一段简短说明 + 依赖关系说明（rigor: standard）； thorough = 逐个系统的完整依据 + 关系分析。对你编写的 每个章节都应用此设置。

每个系统的说明文字放在哪里。 templates/systems-index.md 的 Systems Enumeration 是一个列固定的表格，没有描述列，因此在 balanced 和 thorough 模式下，说明文字应放在 ## Overview 中——balanced 模式下每个系统一段简短说明，thorough 模式下另加关系分析—— 以及 ## Dependency Map 的层级说明中。不要给枚举表格添加列——该表格是 .claude/docs/templates/systems-index.md 中的固定约定，其使用方 （/design-system §6 和 §7、/create-epics）都是根据其定义的列编写的。 扩展表格是架构变更，不是格式选择。

使用方实际如何读取表格。 没有任何内容按位置解析此表格。 两个提到 systems-index.md 的脚本 （gdd-structure-check.sh:51、review-scope.sh:40）都在 case 语句中按文件名匹配，不会解析任何列；两个技能则按名称引用 Category 列（design-system:229、:780）。因此，Category 是绝不能重命名或删除的列；表格保持固定约定，是因为每个使用方都是根据模板定义的列集编写的。 在 terse 模式下，表格加上一段 ## Overview 就是全部输出。

workflow（参见 .claude/docs/workflow-modes.md）：

• full / standard — 在 /design-system 之前必须完成（必须先映射系统， 再编写各系统的 GDD）。
• minimal — 无需完成（游戏简介会替代系统索引）。仍可自愿运行。

---

阶段 1：阅读概念（必需背景）

阅读游戏概念及已有的设计文档。这些内容是拆解系统的原始材料。按章节阅读每份文档：使用 Grep 工具（模式 ^#，内容模式）查找所需标题，再用 offset 和 limit 阅读对应范围。

必需：

• 阅读 design/gdd/game-concept.md（在 minimal 模式下，改为阅读 design/game-brief.md）——如果两者都不存在，明确提示并停止：

  "No game concept found. Run /brainstorm first to create one, then come back to decompose it into systems."

可选（如果存在则阅读）：

• 阅读 design/gdd/game-pillars.md——设计支柱会限制优先级和范围
• 阅读 design/gdd/systems-index.md——如果存在，从上次进度继续（更新，不要从头重建）
• 使用 Glob 检查 design/gdd/*.md——查看已存在的系统 GDD

如果系统索引已存在：

• 阅读并向用户说明当前状态
• 使用 AskUserQuestion 提问： "The systems index already exists with [N] systems ([M] designed, [K] not started). What would you like to do?"
  • 选项："Update the index with new systems"、"Design the next undesigned system"、 "Review and revise priorities"

---

阶段 2：系统枚举（协作）

提取并识别游戏所需的所有系统。这是此技能的创意核心——需要人工判断，因为概念文档很少会明确列出所有系统。

步骤 2a：提取明确提及的系统

扫描游戏概念，找出直接提及的系统和机制：

• Core Mechanics 部分（最明确）
• Core Loop 部分（暗示各层循环由哪些系统驱动）
• Technical Considerations 部分（网络、程序生成等）
• MVP Definition 部分（必需功能 = 必需系统）

步骤 2b：识别隐含系统

对于每个明确提及的系统，识别其暗含的隐藏系统。游戏所需的系统总是比概念文档提到的更多。使用以下推断模式：

• “Inventory”暗含：物品数据库、装备栏位、重量／容量规则、 背包 UI、用于存档／读档的物品序列化
• “Combat”暗含：伤害计算、生命值系统、命中检测、状态效果、 敌方 AI、战斗 UI（生命条、伤害数字）、死亡／重生
• “Open world”暗含：流式加载／分块、LOD 系统、快速旅行、地图／小地图、 兴趣点追踪、世界状态持久化
• “Multiplayer”暗含：网络层、大厅／匹配、状态同步、 反作弊、网络 UI（延迟、玩家列表）
• “Crafting”暗含：配方数据库、材料采集、制作 UI、 成功／失败机制、配方发现／学习
• “Dialogue”暗含：对话树系统、对话 UI、选项追踪、NPC 状态管理、本地化接口
• “Progression”暗含：XP 系统、升级机制、技能树、解锁 追踪、进度 UI、进度存档数据

在对话中说明每个隐含系统的必要性（并举例）。

步骤 2c：用户审核

按类别展示枚举结果。对于每个系统，列出：

• 名称
• 类别
• 简要说明（1 句话）
• 它是明确提及的（来自概念），还是隐含的（推断得出）

然后使用 AskUserQuestion 收集反馈：

• “是否遗漏了哪些系统？”
• “是否应合并或拆分其中某些系统？”
• “列表中的系统是否有游戏并不需要的？”

在 collaborative 模式下——反复迭代，直到用户认可枚举结果。 在 guided 模式下——询问一次，根据答复处理后继续；不要循环询问。 在 autonomous 模式下——不要提问。通过 log_decision 记录枚举结果及推断出的系统，然后继续。

---

阶段 3：依赖关系映射（协作）

确定每个系统依赖哪些系统。如果某系统必须在另一系统先存在的前提下才能运行，则称它“依赖”另一系统。

步骤 3a：梳理依赖关系

为每个系统列出其依赖项。使用以下依赖关系判断依据：

• 输入/输出依赖关系：系统 A 生成系统 B 所需的数据
• 结构依赖关系：系统 A 提供系统 B 所接入的框架
• UI 依赖关系：每个游戏玩法系统都有对应的 UI 系统依赖于它（但 UI 的设计晚于游戏玩法系统）

步骤 3b：按依赖顺序排序

将系统排列为以下层级：

1. 基础层：没有依赖项的系统（最先设计和构建）
2. 核心层：仅依赖基础层系统的系统
3. 功能层：依赖核心层系统的系统
4. 呈现层：包装游戏玩法系统的 UI 和反馈系统
5. 完善层：元系统、教程、分析、无障碍功能

步骤 3c：检测循环依赖

检查依赖关系图中是否存在循环。如果存在：

• 向用户指出这些循环
• 提出解决方案（接口抽象、同时设计、通过定义双方之间的契约打破循环）

步骤 3d：向用户展示

以分层列表的形式展示依赖关系图。指出：

• 所有循环依赖
• 所有“瓶颈”系统（许多其他系统依赖它们，因此风险较高）
• 所有没有依赖方的系统（叶节点——风险较低，可以较晚设计）

使用 AskUserQuestion 提问：“这个依赖顺序看起来正确吗？是否有遗漏或应该移除的依赖关系？”

审查模式检查——在启动 TD-SYSTEM-BOUNDARY 前应用：

• solo → 跳过。注明：“已跳过 TD-SYSTEM-BOUNDARY——Solo 模式。”继续分配优先级。
• lean → 跳过（不是 PHASE-GATE）。注明：“已跳过 TD-SYSTEM-BOUNDARY——Lean 模式。”继续分配优先级。
• full → 按常规启动。

依赖关系映射获批后，在继续分配优先级之前，通过 Agent 启动 technical-director，并使用关卡 TD-SYSTEM-BOUNDARY（.claude/docs/director-gates/td-system-boundary.md）。

传入：依赖关系图（每个系统 → 其依赖项）、层级分配、瓶颈系统，以及任何循环依赖及其建议的解决方案。

展示评估结果。如果结果为 REJECT，则与用户一起修订系统边界，展示修订后的依赖关系图，然后再继续分配优先级。如果结果为 CONCERNS，则在系统索引中就地注明并继续。如果结果为 NOT ASSESSED [missing input]，则该结果不等于 APPROVE：说明缺少什么，然后补充所需内容并重新运行该关卡；或者在索引草稿中注明 TD-SYSTEM-BOUNDARY: NOT ASSESSED — [input] 后继续。

---

第 4 阶段：分配优先级（协作）

根据每个系统所需的里程碑，为其分配优先级层级。

步骤 4a：根据概念自动分配

使用以下判断依据进行初步分配：

• MVP：概念中“Required for MVP”部分提到的系统，以及它们在基础层中的依赖项
• Vertical Slice：在一个区域内构成完整体验所需的系统
• Alpha：其余所有游戏玩法系统
• Full Vision：完善、元功能和锦上添花的系统

步骤 4b：用户审核

以表格形式展示优先级分配。针对每个层级，说明系统为何被划分到该层级。

使用 AskUserQuestion 提问：“这些优先级分配符合你的愿景吗？哪些系统应该提高或降低优先级？”

在对话中解释理由：“我将 [system] 列入 MVP，因为核心循环需要它——没有 [system]，30 秒循环就无法运作。”

如何表述理由——这决定你说什么，而不是要写什么列。两个表格都没有 Why 列：系统枚举表的列为 # / Name / Category / Priority / Status / Design Doc / Depends On，建议设计顺序表的列为 Order / System / Priority / Layer / Agent(s) / Est. Effort。理由应在上文的对话中说明；对于用户在会话结束后仍应看到的内容，则应写在索引的 ## Overview 段落中。不要为此另加一列。

将技术必要性与玩家体验方面的理由结合起来。当系统会直接影响玩家的感受时，单纯的技术理由——“伤害系统需要伤害计算”——是不够的。好的理由会同时说明这两方面，并指出它服务于哪个支柱：

• “这是核心循环的必要组成部分——没有它，玩家的主要选择就不会产生任何后果（支柱 [N]：[支柱名称]）”
• “这里确立了 [system] 的独特性——此处的属性定义让它与[同类系统]的感觉不同”
• “这是后续所有经济决策的基础——玩家必须先理解成本，建立在其上的选择才有意义”

请根据本项目填写方括号中的内容。 方括号中的占位内容不是装饰。从其他游戏的示例中照搬理由，会沿用那个游戏的术语，而非本项目的术语。

审核模式检查——在启动 PR-SCOPE 前执行：

• solo → 跳过。注明：“已跳过 PR-SCOPE——Solo 模式。”继续步骤 4c。
• lean → 跳过（不是 PHASE-GATE）。注明：“已跳过 PR-SCOPE——Lean 模式。”继续步骤 4c。
• full → 按常规启动。

优先级获得批准后、编写索引前，通过 Agent 启动 producer，并使用关卡 PR-SCOPE（.claude/docs/director-gates/pr-scope.md）。

从索引中传递该关卡所需字段：完整愿景范围（索引中的每个系统）、MVP 定义（MVP 层级中的系统）、范围层级（每个里程碑层级的系统数量及估算实施量——系统数量 × 平均复杂度）、将项目声明的时间线作为时间线估算，以及团队规模。

展示评估结果。PR-SCOPE 的评估结果为 REALISTIC / OPTIMISTIC / UNREALISTIC。 如果结果为 UNREALISTIC，在编写索引前，提出调整优先级层级分配。 如果结果为 OPTIMISTIC，展示制作人建议的调整，并询问用户是否要在编写索引前将其应用到各层级；如果用户拒绝，则记录这些建议并继续。如果结果为 NOT ASSESSED [missing input]——通常是缺少团队规模或时间线——则这不代表 REALISTIC：指出缺少什么，然后补充信息并重新运行关卡；或者继续，并在索引草稿中注明 PR-SCOPE: NOT ASSESSED — [input]。

步骤 4c：确定设计顺序

结合依赖关系排序和优先级层级，得出最终设计顺序：

1. 首先是 MVP Foundation 系统
2. 其次是 MVP Core 系统
3. 然后是 MVP Feature 系统
4. 接着是 Vertical Slice Foundation/Core 系统
5. ……依此类推

团队应按此顺序编写 GDD。

---

阶段 5：创建系统索引（编写）

步骤 5a：起草文档

使用 .claude/docs/templates/systems-index.md 中的模板，填入阶段 2-4 的所有数据，完成系统索引：

• 填写枚举表
• 填写依赖关系图
• 填写建议设计顺序
• 填写高风险系统
• 填写进度跟踪表（除非 GDD 已存在，否则所有系统的状态初始均为“未开始”）

步骤 5b：审批

展示文档摘要：

• 各类别的系统总数
• MVP 系统数量
• 设计顺序中的前 3 个系统
• 任何高风险项

当 automation: collaborative 时——询问：“我可以将系统索引写入 design/gdd/systems-index.md 吗？”等待批准。只有在对方回复“可以”后才写入文件。

当 automation: guided 时——新建索引也要询问“我可以写入……吗？”，因为 .claude/docs/automation-modes.md 规定 guided 模式对新文件要询问“我可以写入吗？”。如果索引已存在，则展示上述摘要，指出目标路径（design/gdd/systems-index.md），并直接写入更新，无需等待明确的“可以”。之后说明写入了什么。

审查模式检查——启动 CD-SYSTEMS 前执行：

• solo → 跳过。注明：“已跳过 CD-SYSTEMS——Solo 模式。”继续步骤 5c。
• lean → 跳过（这不是 PHASE-GATE）。注明：“已跳过 CD-SYSTEMS——Lean 模式。”继续步骤 5c。
• full → 按正常流程启动。

写入系统索引后，通过 Agent 启动 creative-director，使用关卡 CD-SYSTEMS（.claude/docs/director-gates/cd-systems.md）。

提供：系统索引路径；游戏支柱与核心幻想——来自 design/gdd/game-concept.md，或者在 minimal 模式下提供 design/game-brief.md 中的构想和“他们的感受”一行，该文件没有游戏支柱；每个优先级层级的分配（MVP / Vertical Slice / Alpha / Full Vision）；以及依赖关系图中的高风险系统和瓶颈系统。

展示评估结果。如果结果为 REJECT，则在开始编写 GDD 前与用户一起修改系统集合。如果结果为 CONCERNS，则展示相关问题，并使用 AskUserQuestion 提供选项：修改系统集合 / 接受——将问题记录到索引中 / 进一步讨论。选择修改时，与用户一起重新处理受影响的系统，并在重写索引前再次询问。选择接受时——选项名称已明确说明要进行的编辑，因此选择该选项即为询问——将这些问题记录到系统索引中，作为 > **Creative Director Note**，紧接在 ## Priority Tiers 表格下方，并注明每个问题适用的层级——例如 > **Creative Director Note** (MVP): …。templates/systems-index.md 中的 Priority Tiers 是定义表格，而不是每个层级各自对应一个章节，因此不存在可写入的“层级章节顶部”——不要指示撰写者写在那里。如果结果为 NOT ASSESSED [缺少输入]，则不属于 APPROVE（.claude/docs/director-gates.md）：说明缺少什么，然后补充该内容并重新运行关卡，或者先询问是否要在同一位置记录 > **Creative Director Note**: CD-SYSTEMS NOT ASSESSED — [input]。

步骤 5c：更新会话状态

写入后，如果 production/session-state/active.md 不存在，则创建该文件，然后更新以下内容：

• 任务：系统拆解
• 状态：已创建系统索引
• 文件：design/gdd/systems-index.md
• 下一步：设计各个系统的 GDD

结论：完成——系统索引已写入 design/gdd/systems-index.md。 如果用户拒绝：结论：受阻——用户未批准写入。

---

阶段 6：设计各个系统（移交给 /design-system）

满足以下条件时进入此阶段：

• 创建索引后，用户表示“可以”开始设计系统
• 用户调用 /map-systems [system-name]
• 用户调用 /map-systems next

步骤 6a：选择系统

• 如果用户提供了系统名称，则在系统索引中查找该系统
• 如果使用了 next，则按设计顺序选择优先级最高且尚未设计的系统
• 如果用户刚完成索引，则询问： “现在要开始设计各个系统吗？设计顺序中的第一个系统是 [name]。或者您希望先到此为止，以后再继续吗？”

使用 AskUserQuestion 询问：“现在开始设计 [system-name]，选择其他系统，还是到此为止？”

步骤 6b：移交给 /design-system

选定系统后，调用 /design-system [system-name] 技能。

/design-system 技能负责完整的 GDD 编写流程：

• 从游戏概念、系统索引和依赖 GDD 中收集上下文
• 立即创建文件骨架
• 按顺序逐一讲解全部 8 个必需章节（协作、循序渐进）
• 交叉引用现有文档，避免矛盾
• 将任务分派给领域专家 Agent
• 每个章节获批后立即写入文件
• 完成后运行 /design-review
• 更新系统索引

不要在此处重复 /design-system 工作流。 此技能负责系统索引；/design-system 负责各个系统的 GDD。

步骤 6c：继续或停止

/design-system 完成后，使用 AskUserQuestion：

• “继续处理下一个系统（[下一个系统名称]）？”
• “选择其他系统？”
• “本次会话到此为止？”

如需继续，返回步骤 6a。

---

第 7 阶段：提出后续步骤

创建系统索引后（或完成部分系统设计后），使用 AskUserQuestion 提出后续操作：

• “系统索引已写入。接下来要做什么？”
  • [A] 开始设计 GDD — 运行 /design-system [first-system-in-order]
  • [B] 运行 /gate-check systems-design — 概念 → 系统设计阶段门；仅当 project.stage 仍为 Concept 时提供此选项
  • [C] 运行 /gate-check technical-setup — 系统设计 → 技术设置阶段门；待 MVP 系统都有 GDD 后运行
  • [D] 本次会话到此为止

值得了解的阶段门检查选项（[C]）：/gate-check technical-setup 会检查系统设计阶段所需的产物是否存在，并在你确定架构前运行阶段门总监。CD-SYSTEMS 和 TD-SYSTEM-BOUNDARY 是此技能自己的阶段门——它们会在此处以 full 审查模式运行，而不是在 /gate-check 中运行。

每完成一个 GDD 后：

• “在新会话中运行 /design-review design/gdd/[system].md，以验证质量”
• “所有 MVP GDD 完成后运行 /gate-check technical-setup”

---

协作流程

适用于 collaborative 模式（默认模式）。 关于 guided 和 autonomous 模式，请参阅 .claude/docs/automation-modes.md——以下规则说明的是协作模式的要求，并非通用行为。

此技能在每个阶段都遵循协作设计原则：

1. 提问 -> 提供选项 -> 做出决定 -> 起草 -> 批准，每一步都如此
2. 在每个决策点使用 AskUserQuestion（说明 -> 记录模式）：
   • 阶段 2：“有遗漏的系统吗？要合并还是拆分？”
   • 阶段 3：“依赖项的排序是否正确？”
   • 阶段 4：“优先级是否符合你的设想？”
   • 阶段 5：“可以写入系统索引吗？”
   • 阶段 6：“开始设计、选择其他系统，还是停止？”随后移交给 /design-system
3. 每次写入文件前都要询问“可以写入 [filepath] 吗？”
4. 增量写入：每设计完一个系统，就更新系统索引
5. 移交：各个 GDD 的编写由 /design-system 负责，该技能会处理章节的增量写入、交叉引用、设计审查和索引更新
6. 更新会话状态：每个里程碑（创建索引、完成系统设计、更改优先级）后，将更新写入 production/session-state/active.md

绝不在未经审查的情况下自动生成完整系统列表并写入文件。 绝不在未获得用户确认的情况下开始设计系统。 始终展示系统枚举、依赖项和优先级，供用户验证。

上下文窗口注意事项

如果上下文用量在任何时候达到或超过 70%，请追加以下提示：

上下文即将达到上限（≥70%）。 系统索引已保存至 design/gdd/systems-index.md。请开启新的 Claude Code 会话以继续 设计各个 GDD——运行 /map-systems next，从上次的位置继续。

推荐的后续步骤

• 运行 /design-system [first-system-in-order]，编写第一个 GDD（按索引中的设计顺序）
• 运行 /map-systems next，自动选择优先级最高且尚未设计的系统
• 每编写完一个 GDD 后，在新会话中运行 /design-review design/gdd/[system].md
• 编写并审查完所有 MVP GDD 后，运行 /gate-check technical-setup