在 MapleStory Worlds (MSW)…

当用户想决定做什么游戏、圈定 MVP、或继续/恢复一个分阶段推进的 MSW 原型时，先走规划流程产出 GDD 与路线图，再交接给实现类技能。

适用场景

解决思路

1. 把‘我想做个这样的游戏’通过引导式会话变成‘做什么 + 在 MSW 里怎么搭’：先产出 GDD/路线图，再分阶段推进（详细 Phase 计划、进度跟踪、计划修订），直到每个里程碑可以进入完整实现。
2. 做目录对齐（catalog grounding）：读 references/genre-catalog.md，把模糊想法映射到 MSW 真实存在的类型/地图类型/机制标签（3 种地图类型、约 180 个机制标签），只用通用游戏知识做规划会得出 MSW 实现不了的设计。
3. 按 build-effort 提示（Low/Medium/High）设定预期而不是拒绝某个类型；首个构建的规模按 build-effort + 范围（地图/内容量）来定，绝不用日历/工期估算（技能不知道用户水平与可投入时间）。
4. 用户野心大（High-effort 类型、系统/地图很多、‘我全都要’）时，把首个构建缩到小的可玩核心（MVP，从该类型的 `MVP:` 提示起步），其余推到后续 Phase 或里程碑路线图，任何类型都适用。
5. 把用户触点限制在 STEP 1（批量提问）和 STEP 3（方向确认）两处，中间不要反复追问。
6. 绝不在写 GDD 之前跳过 STEP 3 方向确认；方向一旦确认就立即产出交付物。
7. 把结果按 references/gdd-template.md 的固定结构写成 markdown，方便实现类技能接手推到 MVP。
8. ‘以后再说’只有一个归属：GDD 只覆盖自己那个里程碑；被砍功能、后续里程碑想法、讨论中冒出的‘总有一天要做’在出现的当下就记进常驻里程碑路线图 Docs/<game>-Roadmap.md（未来里程碑槽位，或时机未知时放 Backlog），绝不留在 GDD 里。
9. 每份交付物完成后主动提议下一步（如‘接下来要不要写 Phase 1 详细计划？’），用户同意就继续、说停就停，这是建议不是推进。
10. 每个用户决策点（STEP 3 方向确认、Phase 交接即现在实现还是写下一 Phase 计划、软 Phase 关卡）都用 agent 的多选 UI（如 Claude Code 的 AskUserQuestion）给结构化可选项，标注推荐项但不强制；没有该 UI 时退化为清晰枚举的文字选项。
11. 启动时先检测计划文件：完整列出 Docs/ 和 Archive/ 目录里的全部内容（注意大写 D/A），再自己从清单里匹配以 -GDD.md / -Phase<N>.md 结尾的文件名；不要用收窄的 glob 或内容搜索（大小写敏感、范围脆弱，漏掉会静默当成‘没有 GDD’），也不要凭记忆。
12. 只有 Docs/ + Archive/ 的清单确实为空，才能判定‘哪里都没有 GDD’。
13. 若存在 Archive/As-built.md 先读它拿当前状态图；若存在 Docs/<game>-Roadmap.md 一并读取跨里程碑方向，绝不把它误当活跃 GDD。
14. 正常情况下只有一个活跃 GDD；若存在多个，先问清楚这次是哪个游戏。
15. resume 门槛：只有 Docs/ 或 Archive/ 里存在计划（<game>-M<n>-GDD.md / <game>-M<n>-Phase<k>.md，或前一个里程碑 + Archive/As-built.md）时，‘继续’/‘下一步做什么’/恢复请求才按 resume 处理；两处都没有时不得当 resume、也不得自动启动 STEP 1 问卷。
16. 不要从工作区文件推断 brownfield（模板自带 .mlua/.model/.ui 示例）；进度一律从 GDD/Phase 文档的 ⬜/🟡/✅ 任务状态判断，不看工作区文件。
17. 分支处理：用户明确要求继续/恢复 → 直接 resume；所有路线图与 Phase 项均为 ⬜ 且是该游戏第一个里程碑（Archive/ 无同 <game> GDD 且当前 GDD 编号为 M1）→ 用可选项提供 ① 继续这个计划 ② 丢弃并规划新游戏，选丢弃时先明确列出将删除的文件（Docs/<game>-M<n>-GDD.md、该游戏的 Docs/<game>-M<n>-Phase<k>.md、以及该游戏的 Docs/<game>-Roadmap.md）再删，然后从 STEP 1 重来。
18. 任何项为 🟡/✅，或全 ⬜ 但存在本游戏的前一个里程碑（Archive/ 有同 <game> GDD，或当前 GDD 编号为 M2+）→ 不要丢弃、也不要在这里规划新游戏；告知用户这个世界已有原型在进行、真正的新游戏必须建在新 world，本技能不能创建 world，让用户建好后在新 world 里运行本技能，然后停止。
19. 状态不明确（Phase 文档缺失或不一致、进度含糊）→ 一律按 🟡/✅ 情况处理：不丢弃、不覆盖。
20. resume 具体步骤：先读现有文档——Docs/<game>-M<n>-GDD.md + 所有存在的 Docs/<game>-M<n>-Phase<k>.md（可能多个并存）+ Docs/<game>-Roadmap.md；不要重跑 STEP 1–4，计划已存在。
21. 重建状态：GDD 的 Stage 行 + 路线图 ⬜/🟡/✅、任何 🟡 Implemented (untested) 项（标记出来让用户重测/确认）、以及最近的 §9 Plan changes。
22. 若恢复的工作会涉及实现或任何清单状态，现在就完整读 references/build-management.md；同时顺手现代化过期的 AI 注释（把旧 GDD/Phase 文档头部早于当前模板的 AI-note 更新为当前模板文字），避免旧文档继续把未来会话引向过时的读取链。
23. 简要复述现状（已完成什么/当前 Phase/还有什么没测/下一步），然后从那里继续。
24. Docs/ 无 GDD 但 Archive/ 有已完成 GDD（+ Archive/As-built.md）→ 确认是否开启下一个里程碑（Docs/<game>-M<n+1>-GDD.md，编号按 STEP 5 取下一个），基于路线图的下一槽位（+ 其 Backlog）与 Archive/As-built.md 规划，而不是默认为全新游戏；写之前先做‘下一个里程碑前先对账’。
25. Phase 文档只在该 Phase 全部 ✅ 时删除（其阶段清理），之后 GDD 路线图即其记录；因此 Docs/ 里正常是当前 Phase 加上停在 ⏳ user-test 边界（仍有 🟡 待用户测试）的早期 Phase，多个共存是合法的；全是 ✅ 的遗留文档才是漏掉清理的信号。
26. 记住 Docs/ 文件是跨会话的唯一事实来源：上次会话的聊天上下文不保留，没写进 GDD/Phase 文档的东西就是丢了。
27. 没有任何 GDD 时，先给工作区分类再决定，这是强制的，即使明确说‘新游戏’也不能跳过检查；已知的模板脚手架项算作‘零进度’（非穷尽清单，如 RectTileData_Henesys、@Logic UIPopup/UIToast、@Component Monster/MonsterAttack/PlayerAttack/PlayerHit、模板怪物 AI FSM 的 StateChaseMonster 等脚本与 StateSet*AI stateset、Global/ 的 ChaseMonster/MoveMonster、DefaultPlayer/WorldConfig/起始地图等）。
28. 工作区 ≈ 只有脚手架项（或更少）→ 视为全新项目，直接进 STEP 1，不做 brownfield 提示。
29. 工作区明显超出脚手架（自定义命名的系统/地图/数据集/脚本）→ 按用户意图决定 brownfield 的推荐力度：继续/‘下一步做什么’意图 → 把 brownfield 作为推荐项；明确的新游戏意图 → 尊重新游戏为默认/推荐，brownfield 只作为最后、不推荐的安全网；明确说‘在我现有作品上继续’ → 直接进勘测。只有用户真的选了才跑 brownfield。
30. 选了 brownfield 后做轻量结构勘测（map/ + RootDesk/MyDesk/：系统·模型·数据集·UI；只看结构不逐行读代码，深入检查是 msw-general 的活），以 ⚠️confirm 呈现‘我看到这些已经建好了，对吗？’，然后播种 Archive/As-built.md，并在现有世界之上规划第一个里程碑（路线图照常随该里程碑 GDD 创建）。
31. 下一个里程碑前先对账：Archive/As-built.md（或旧交接笔记）只是起始提示不是事实——写新 GDD 之前，跑一次与 Brownfield 相同的轻量结构勘测来验证记录（不是从零发现）：检查新里程碑会触及的区域，外加快速扫一遍明显未被跟踪的大系统；若已漂移，先向用户指出并一起对账、更新 Archive/As-built.md，再在其上规划。
32. STEP 1 用批量引导提问补缺口：①类型/参考（什么感觉、有相似游戏吗，不确定就从‘想要哪种乐趣’入手）②核心乐趣/核心循环（一局里重复做什么）③目标·平台（PC/移动、单机/多人）④首个构建范围（快速原型还是更大，大概几张图/多少内容）⑤必须要有/可以砍。约 5 个问题批量问，用户已给的不重复问；用户说‘你决定’就用合理默认值但说明假设。
33. STEP 2 读 references/genre-catalog.md：找最接近的类型；取出该类型的推荐地图类型与核心机制标签；取出 `MVP:` 切片提示（缩下来的首建与 STEP 4 Phase 1 的种子）和 `Growth:` 轴（喂给后续 Phase 与未来里程碑）；按用户想法调整，它们只是提示不是固定规格。
34. STEP 2 继续：读 build-effort 提示（Low/Medium/High）并判断用户野心；若为 High-effort 或用户一次要太多，直说并提议缩水的首建（一张图 · 只做核心循环，从该类型 `MVP:` 起步），保持同样的乐趣，其余进后续 Phase 或里程碑路线图；必要时把机制标签组合成一句话概念。
35. STEP 3 方向确认（绝不跳过）：简要展示匹配的 1–2 个子类型 + 推荐地图类型 ↔ Body（如 RectTile + KinematicbodyComponent）+ build-effort 提示 + 一句话概念；若 High-effort 或范围过大，同时给出缩水的首建（MVP）选项，其余路由到后续 Phase / 里程碑路线图；然后用可选项问‘就按这个方向写 GDD？还是有其他候选 / 要改？’；只有用户确认（或选择）后才进 STEP 4；用户说‘你决定’就锁定推荐并一句话说明所选。
36. 在 STEP 3 钉死地图类型 ↔ Body（见 references/msw-mapping.md）：搞错会在实现时导致‘不动’/ [LEA-3004] 静默失败；它由‘建在已有该类型的地图里’来落实（如按类型分的模板地图），否则由用户在 Maker 里设置，AI 永不自己切换地图类型。
37. STEP 4 按用户确认的方向，用 references/gdd-template.md 的结构写 markdown：一句话概念 / 关键决策表 / 核心循环 / 核心系统 / 系统↔MSW 映射 / Phase 路线图清单 / 本里程碑范围内的决策。
38. 系统↔MSW 映射用 references/msw-mapping.md，把每个系统接到 @Logic/@Component/.model/.ui/dataset（UserDataSet）。
39. 路线图从最小可玩构建（Phase 1，比如‘能动、能打、会碎’）开始分阶段，该类型 `MVP:` 提示就是 Phase 1 的自然种子、`Growth:` 轴提示后续 Phase；用三态跟踪每项：⬜ Not started / 🟡 Implemented (untested) / ✅ Tested（初始全 ⬜）。
40. 路线图清单只放‘可交接原型所必需’的项，且它们都必须达到 ✅；打磨/锦上添花/以后再做在规划时就进里程碑路线图（未来槽位或 Backlog），绝不当清单项、也绝不在 GDD 里另找地方存放。判别标准：去掉它会让完整实现团队拿到更不完整的底子 → 必需（进清单）；生产阶段反正会打磨它 → 里程碑路线图。
41. 数据量大的游戏在路线图里写明‘数据驱动（UserDataSet/CSV 是唯一事实来源）’；早期 Phase 可为速度先硬编码，但值集变大或稳定后按 horizon 规划硬编码→dataset（UserDataSet/CSV）迁移：本里程碑内 → GDD §6 的后续 Phase 任务；超出 → 里程碑路线图条目（§7 只留指针，只写在 GDD 正文里的意图会随 GDD 归档被埋掉）；只在确实需要时（可调值多 · 预期反复平衡 · 内容扩展）才加，几个常量不必。
42. 存 GDD 之前做覆盖检查：§6 的各 Phase 必须共同交付 §1 的一句话概念（M2+ 还要交付被提升的路线图槽位那一行），把那些行声称的每项能力追溯到将实现它的清单项；没有对应项的能力声明就是规划漏洞（未规划的任务不会留下任何 ⬜）。
43. 验证限制不缩小范围：AI 无法单独验证的流程（真多人对战、真机手感、内购）仍要规划成任务，只是最终停在 🟡 待用户测试，绝不因为无法自动验证就悄悄略去；若用户同意排除某项能力，就改写 §1 / 路线图槽位，让文档不再承诺它。
44. 若项目带占位/示例实体，加一项‘完整实现交接前删除它们’的任务，范围是整个项目而不只是所选构建地图：先全量枚举所有地图（完整列 map/），再逐个检查，按检查识别各图的示例（名字随模板变化，不要假定固定名），完成标准是‘每个地图都检查过且干净’；交接时对游戏用不到的模板地图先问用户删还是留（未确认不得删），并且要在清理示例之前决定（别清理一个即将删除的地图）。
45. STEP 5 保存：写到项目根 Docs/ 下，命名 Docs/<game>-M<n>-GDD.md；<game> 是短 ASCII（英文/罗马化）slug，绝不用原始非英文标题（CJK/非 ASCII 文件名会破坏 globbing 和跨平台路径）；<n> 是里程碑号，首个是 M1，后续取 Docs/ + Archive/ 中现有 -M<n>-GDD.md 的最大编号 +1，要解析数字而不是字典序排序（M9 → M10，不是 M2）；文档内容保持用户语言，只有文件名用 ASCII；Phase 文档继承同样的 <game>-M<n>- 前缀。
46. 绝不要保存在 RootDesk/ 下：Maker 的 refresh_workspace 会清理（删除）RootDesk 下的非 MSW 文件（.md 等），实现/试玩期间一次刷新文件就没了；始终放在 RootDesk 之外的项目根 Docs/。
47. 与 M1 GDD 一起创建里程碑路线图 Docs/<game>-Roadmap.md（名字不含 M<n>，每个游戏一份，永久不归档）：按 gdd-template.md 的‘里程碑路线图模板’写一句话愿景 + 发布标准（要满足什么才算可发布，是标准不是功能堆砌）+ 每个里程碑一个槽位（M1 = 指向活跃 GDD；未来 M = 一句话主题 + 分配的功能）+ Backlog；把 STEP 2–3 从首建砍掉的一切（Growth 轴 · 裁剪的功能 · 用户的‘以后’愿望）排进未来槽位或 Backlog；按游戏规模缩放（单里程碑游戏几行，M1 = 发布）；M2+ 不新建，而是更新现有路线图（提升那个槽位）。
48. 基础 GDD 完成后自然先提议：‘接下来写 Phase 1 详细计划吗？’用户同意就直接进 STEP 6；其他可选分支：数值/数据多 → 做数据集设计；界面多 → 用 msw-ui-system 做 UI；想直接开工 → 用 msw-general · msw-scripting 实现；默认推荐流程是‘细化 Phase 1 → 实现’。
49. 应用地图类型：原型必须建在 TileMapMode 已等于所定类型的地图里。用 MapBuilder.read().getTileMapMode() 检查现有地图：若某张地图已匹配（例如项目保留了按地图类型的模板地图）就直接在该地图里构建，无需切换（避免破坏性切换，此捷径只在存在匹配地图/模板时适用）；若无匹配地图（没有按类型模板或从零开始），走标准策略——由用户在 Maker 里切换地图类型（msw-general tile.md），AI 事后用 getTileMapMode() 验证；无论哪种情况 AI 都绝不自己切换地图的 TileMapMode。
50. 若原型要住在 *Template 命名的地图里，规划一个 Phase 1 任务提早把它重命名为贴合游戏的 ASCII 名（在真正开始构建之前）：地图引用（扇区注册 · 传送门 · GetEntityByPath 路径 · 活跃地图）会随 Phase 累积，Phase 1 改名几乎免费、交接时很贵，而且游戏住在 *Template 命名地图里会污染本技能自己依赖的模板/游戏分类；完成标准 = 文件已改名 + 所有引用已更新 + refresh + 入口验证；若某引用在只读配置（Global/）里，那部分由用户在 Maker 操作。
51. 构建前把 Maker 的活跃（打开）地图切到目标地图（用 maker_move_map，AI 可做，这不是被禁止的 TileMapMode 切换），这样实体/瓦片编辑和截图才会落在对的地图上；不要默默跳过。
52. STEP 6（可选）按用户要求为指定 Phase 生成额外的详细计划 markdown（如‘写 Phase 1 详细计划’）：每个任务写 目标 · 所需系统/组件（references/msw-mapping.md）· 数据（UserDataSet）· UI · 完成（验证）标准 · 依赖 · 应参考的技能（预测：技能 + 其 reference 文档）；并在 Phase 文档顶部附近记一份‘本 Phase 应参考的技能’摘要（实现会话会先读它）。
53. STEP 6 同时生成状态清单，每项从 Not started 开始并随工作推进走三态（⬜ Not started / 🟡 Implemented (untested) / ✅ Tested），按 gdd-template.md 的‘Per-phase detailed plan 模板’写，保存为 Docs/<game>-M<n>-Phase<k>.md（同样的 <game>-M<n>- 前缀、项目根 Docs/、RootDesk 之外）。
54. Phase 详细计划也只到‘详细规划’为止；写实际代码（.mlua/.model 等）仍是实现类技能（msw-general/msw-scripting）的活，由它们实现和验证时更新清单状态。
55. 实现期规则走 references/build-management.md：在实现计划任务、更新任何清单状态、完成 Phase 或里程碑、或应用计划修订之前，必须‘本次会话内完整读过’它（纯规划会话不需要）。硬性关卡：如果即将编辑任何 ⬜/🟡/✅ 标记、跑 Phase/里程碑完成流程、或归档/删除计划文档，而本次会话还没完整读过该文件，就先停下读——加载过 SKILL.md 或上个会话读过都不算。
56. 状态只有 ⬜/🟡/✅ 三种，按任务在 Phase 文档里即时更新，绝不攒到最后批量更新、绝不只存在临时工具里、绝不自造标记。
57. Phase 完成与里程碑完成各有强制清理流程（状态镜像进 GDD §6 → As-built → 路线图 → 删除/归档）；没跑流程绝不删 Phase 文档或归档 GDD；完成与否按里程碑声明的愿景衡量而不只是清单——里程碑完成流程以愿景覆盖检查开头，剩余项全在等用户测试的里程碑是 ⏳ user-test pending，绝不叫‘完成’，也不自造标签。
58. 计划变更请求走 build-management.md 里的修订流程；超出当前里程碑的工作直接进里程碑路线图；被有意留桩/阻塞的代码路径在写下的那一刻就要有被跟踪的条目。
59. 守边界：本技能不写实际代码（.mlua/.model/.map/.ui），那是实现类技能的工作——它只规划并跨里程碑管理构建（GDD · 里程碑路线图 · 详细 Phase 计划 · 进度跟踪 · 计划修订）并把代码工作交接出去；已建成并上线的世界的大改/扩展不在范围内；在计划里反映 MSW 平台规则（地图类型↔Body、1 unit = 100px、SpriteRUID 等），但精确实现规则遵循 msw-general 的平台参考。

适用边界 · 注意事项

• 需要写实际实现代码（.mlua/.model/.map/.ui）的场景——那是 msw-general / msw-scripting 等实现类技能的职责，本技能只规划与跟踪。
• 对已经建成、已上线世界的重大改造或扩展（本技能只管新游戏及其后续里程碑，直到可进入完整实现）。
• 没有 MSW（MapleStory Worlds）项目/平台的环境：类型目录、地图类型↔Body、mLua、Maker 工具链等前提都不存在。
• 已发布世界的重大改造或扩展。
• 纯实现而不涉及任何‘做什么/做到哪/下一步’决策的任务。