diff --git a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/skills/tdd.md b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/skills/tdd.md index c081aab31..b2b6e6c50 100644 --- a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/skills/tdd.md +++ b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/skills/tdd.md @@ -97,737 +97,18 @@ GDD 喂的（系统文档交接节就是订单）；程序侧的加载与验证 -## A1 概念层分册（game-gdd-concept） +## A1 概念层分册（简介） ---- -name: game-gdd-concept -description: 写游戏策划案（GDD）概念层时使用。把一句话游戏想法写成一份 - "一次写对、之后不动"的立项概念文档——它是后续所有设计争议的仲裁依据。 - 任何游戏类型通用。配套：templates/concept-design.md、templates/analysis.md（全局一份）、 - exemplars/stardew-concept.md、exemplars/stardew-analysis.md（全局一份）。 ---- +本分册说明概念设计的目标、边界、核心张力、分析记录和交接要求。完整内容请阅读 `resources/skills/concept.md`；概念设计模板请阅读 `resources/templates/concept-design.md`。 -# 概念层写法（策划 agent · 概念层分册） +## A2 顶层设计分册（简介） -> 本文件是概念层唯一承载写作流程的教学件。 -> 模板与例子文件保持纯净：不含任何步骤、检验提示与标记。 +本分册说明顶层循环、资源流、节奏、取舍、范围和验证标准。完整内容请阅读 `resources/skills/top_design.md`；顶层设计模板请阅读 `resources/templates/top-design.md`。 -## 一、这一层的判断立场 -你是资深游戏策划，看过上千份概念案，清楚绝大多数死在"什么都说、什么都不尖"。 -在这个层里你相信： -- 概念的成败在取舍，不在丰富：一句话里卖点只许有一个。 -- 你写的是裁判文档：后续每一层的设计争议，都要能回到这里找到仲裁。 -- 具体压倒抽象："压力很大"是废字，"每开一扇门都在烧自己的命"才是概念。 -- 用户没说过的话不当他说过：宁可标"待确认"，不替人拍板。 -- 发现自己在堆形容词 = 概念没想清楚：停笔回去问，别用空话盖过去。 -- 概念层是"一次写对、之后不动"的层（实作中它的返工率远低于架构与 - 系统层），所以判断力要前置堆足，不要指望后面回来改。 +## A3 系统架构分册（简介） -## 二、动笔前 -1. 拿到用户真实回答过的定调信息（参照对象、题材偏好、压力档位）。 - 没有 → 先问一个定调问题，禁止自问自答充当用户。 -2. 读 exemplars/stardew-concept.md 做质量锚（模仿密度，不抄内容）， - 然后往 templates/concept-design.md 里填。 -3. 零参照时在文档头注明"零参照"。 +本分册说明系统职责、依赖、数据归属、MVP 闭环、目录映射和架构校验。完整内容请阅读 `resources/skills/architecture.md`；架构模板请阅读 `resources/templates/architecture.md`。 -## 三、九节总览：写什么、为什么、怎么咬合 +## A4 系统文档分册（简介） -概念文档回答四个问题： -**这是什么（1~5）→ 它不是什么（6）→ 它靠什么让人一直玩（7）→ -它管到哪、交出什么（8~9）。** - -第 1 节是全案的压缩态，第 9 节是全案的判断态重述，首尾呼应； -中间各节从"设计锚点"这个枢纽长出来，争议又都回头接受它的仲裁。 - -| # | 节 | 是什么 | 为什么写 | 和谁咬合 | -|---|---|---|---|---| -| 1 | 一句话概念 | 全案压缩成一句：品类+融合+唯一卖点 | 概念的第一命运是被转述；这句立不住，后面写得再好都救不回来 | 9 是它的重述；2 是它的展开 | -| 2 | 定调与设计锚点 | 定调记录（参照/滑杆/T 原则，调性真源）+ 六个仲裁位：幻想/体验/动机/循环/跑偏/非目标 | 概念层把调定死：后续所有开放问题先回定调记录级联（约八成可就地定），级联不掉的才上决策卡；概念文档的核心职能是当裁判 | **全文档枢纽**：3~6 由它长出；7 由它的循环与动机抽出；定调记录被顶层及以下所有层引用 | -| 3 | 玩家身份与基调 | 玩家在虚构里是谁 + 情绪温度与红线 | 幻想需要一张脸和一种温度，否则是空话；基调边界句防调性漂移 | 身份 = 幻想的具象化；基调 = 目标体验的情绪面 | -| 4 | 风格与世界观 | 支撑玩法的世界规则 + 叙事载体 | 世界观是给玩法供氧的背景板，不是设定集 | 服务 3 的身份与基调；世界规则支撑 2 的核心循环成立 | -| 5 | 目标玩家与情境 | 为谁、什么场景、门槛多高 | 同一设计对不同人是不同游戏；受众映射防止"谁都适合=谁都不适合" | 反面校验 2 的目标体验；情境（一局多久）给 7 的循环定参数 | -| 6 | 不是什么 | 负面定位表：不是 X，因为 Y | 正面定义写多必然发散；负面定位用"误会方向+封死原因"收边界，比光秃的非目标锋利一档 | 2 的非目标与跑偏风险的表化展开；与 5 的防串味声明呼应 | -| 7 | 核心张力 | 玩家持续面对的两难，两端各有代价 | 长期游玩的根本动力；没有张力，再丰富的内容玩几次就腻 | **向下接口**：每条张力必须在顶层变成取舍表里的具体决策 | -| 8 | 边界与约束 | 本层只定什么、什么留给后面 + 规模回流 | 防止概念层越层写数值和系统（越层是下游返工之源）；给写作画线 | 保护 2 的纯度；告诉顶层"你们的地盘从哪开始" | -| 9 | 概念定稿 | "核心不是 __ 而是 __"重述 + 给顶层的硬约束 | 收口重锤：写完九节重述一遍，检验整份文档有没有写散；把承诺变成对下的契约 | 回环呼应 1；把 8 的交接具体化成 2~4 条硬约束 | - -咬合一图： - -``` - 1 一句话概念（压缩态） - ↓ 展开 - 2 设计锚点（枢纽 · 仲裁位）◄── 所有节的争议回来找它 - ├→ 3 身份基调 ──→ 4 风格世界观（给玩法供氧） - ├→ 5 目标玩家（反面校验）──→ 6 不是什么（负面收边） - └→ 7 核心张力（动力结构）──→ 【交给顶层】取舍表 - 8 边界与约束（画线：本层到此为止） - ↓ 回环 - 9 概念定稿（判断态重述 + 交接契约） -``` - -记住三个接口：**对内**锚点仲裁一切；**对下**张力变取舍表、定稿变硬约束； -**对上**边界画线防止越层。九节不是清单，是一台咬合的机器。 - -## 四、怎么写（模板参考结构，建议按此组织） -（本节是带写法要领的教学版；实际填写的纯净模板在 templates/concept-design.md） - -### 1. 一句话概念 -《__》是一款 __（品类与融合）：玩家通过 __，把 __ 逐步 __。 -→ 45~90 字，卖点唯一。检验：删掉那个卖点句子依然成立，说明没写对。 - -### 2. 定调与设计锚点（先定调，再立仲裁位） -**定调记录**（全项目调性真源，此节定死）： -- 参照选择：以 __ 为主、__ 学 __（参照即定调，选完调性随之而来）。 -- 调性滑杆：压力感/战斗比重/管理深度/叙事比重/节奏，各一档。 -- 调性锚 T 原则：3~7 条逐条具名（如"T2 不劝退——凡惩罚类问题默认取最轻档"）。 - 检验：每条 T 都能当一句 IF-THEN 用——"凡__类问题默认__"；写不出口径的 T 是空话。 - → 下游每个开放问题先来这里级联批量起草，级联不了的才升级提问。 -**设计锚点（六项，争议时的仲裁原则，全部具名）** -- 核心幻想：一句描述 + 一句玩家念头（引号写出玩家脑中的自言自语）。 - 检验：念头句写不出来 = 幻想没立住，回去重想，不要用描述糊弄。 -- 目标体验：何时感到什么。 -- 玩家动机：短期 __；长期 __。 -- 核心循环：__ → __ → __ → __ → 回到 __（箭头式）。 -- 跑偏风险：本项目可能的真实偏航，不放万金油。 -- 非目标：一行带过，详表见第 6 节。 - -### 3. 玩家身份与基调 -- 玩家身份：玩家在虚构里是谁 + 本项目的核心节奏，一口气说清。 -- 情绪基调：正面定调 + 边界句——"可以 __，不可以 __"。 - -### 4. 风格与世界观 -世界观为 __（玩法）服务；叙事通过 __（载体）展开。禁编年史、种族志。 - -### 5. 目标玩家与情境（受众映射三件套） -- 与谁的受众重合；吸收了谁的什么需求；**为什么不会变成它**（防串味声明， - 参照越多越必须有这句）。 -- 情境与门槛：单人/多人；一局多久；需要理解 __，不应要求 __。 - -### 6. 不是什么（负面定位表） -| 不是 | 因为 | -→ 每行原因要封死一条具体误会方向（例：不是武器店经营｜武器主要拿去 - 战斗，不是卖给顾客）。从锚点的非目标与跑偏风险长出来，通常 4~6 行。 - -### 7. 核心张力 -- __ 有限，但 __。 -- __ vs __（两端的代价各是什么）。 -→ 每条两端都必须有代价，只有一端的"假张力"删掉。这些是顶层取舍表的 - 种子，后面要逐条对应。 - -### 8. 边界与约束 -- 概念边界放首位：本层只定幻想、用户、基调与排除方向；具体数值、 - 系统清单、MVP 内容留给顶层及以后。 -- 规模与回流：单人可维护；所有系统回流核心循环。 -- 参照声明：学组织方式，不复制角色/文本/美术/数值。 - -### 9. 概念定稿（收口重锤） -这个游戏的核心不是 __，而是： -> （一句话重述核心承诺） -交给下一层的约束：__ 必须 __（2~4 条，顶层必须围绕它们展开）。 - -某节对本项目没意义 → 写一行"略，因为 __"，不硬凑。 - -## 五、分析文档（全局一份，按层分节） - -**全局唯一一份《分析.md》**（项目根），本层不另设分析文件（2026-09-06 收敛： -原每层一份 analysis 合并为全局一份——论证按发生层归节，决定登记表全项目 -只此一张，跨层引用只查这里）。模板与例子：资源 `templates/analysis.md`、 -`exemplars/stardew-analysis.md`。状态池（灵感池/代决/待原型等活队列）在决策台账， -不放分析文档——本文件只放已决论证与登记。 - -- 条目格式：`## 问题：<一句话>` ＋ 状态（agent_proposal / user_confirmed / - superseded，登记 D-__）＋ 广度分析（牵动面＋候选 ≥2）＋ 深度分析 - （逐候选利弊依据，必须引 T 原则/锚点/张力编号，写不出依据的偏好不进分析） - ＋ 综合判断（建议取 __ 因为 __；推翻条件：__）。 -- 分诊三条件全满足才进：① 影响项目方向或边界；② ≥2 合理候选；③ 一时定不了。 - 不满足的：就地小权衡直接进登记表一行，不写条目。 -- 本层标准两问：① 什么是本项目不可替代的核心承诺；② 什么内容扩张会稀释它。 -- 数量纪律：概念期问题通常 ≤3；开始堆第 4 问时先怀疑概念层没想清楚，重读定调记录而不是继续开新争议。 -- user_confirmed 后三件事：结论一句话迁入 design.md 对应节（留修订痕迹）； - 登记表加行（编号全项目连续，跨层引用写 D-__）；本条目改状态记 D 号保留不删。 - 推翻时新增行挂旧行编号，旧行不删。 - - -## 六、写完自查（参考，不是闸门） -- 卖点唯一吗？念头句立得住吗？ -- 随便挑一个后续设计问题，锚点六项之一能当裁判吗？ -- "不是什么"表封死了最可能的误会方向吗？ -- 张力每条都两端有代价吗？ - -## 七、红线（只有三条） -1. 不冒充用户决定：用户没说的方向标"待确认"，正文不写死。 -2. 不越层：出现具体数值、按键、界面即删。 -3. 不凑数：写不满就说明缺什么，禁止万金油句填充。 - - - - -## A2 顶层设计分册（game-gdd-top-design） - ---- -name: game-gdd-top-design -description: 写游戏策划案（GDD）顶层设计时使用。在概念层定稿之后， - 回答"玩家为什么一直玩"——把概念变成可玩的时间结构（循环/资源/取舍/节奏）， - 并向架构层交付系统范围。配套：templates/top-design.md、templates/analysis.md（全局一份）、 - exemplars/stardew-top-design.md、exemplars/stardew-analysis.md（全局一份）。 ---- - -# 顶层设计写法（策划 agent · 顶层设计分册） - -> 本文件是顶层设计唯一承载写作流程的教学件。 -> 模板与例子文件保持纯净：不含任何步骤、检验提示与标记。 - -## 一、这一层的判断立场 -你是资深游戏策划，正在写全 GDD 最重要的一份文档——概念说"凭什么成立"， -顶层说"好玩在哪"。核心循环无趣，后面写再多系统也救不回来。在这个层里你相信： -- 循环优先：先把大循环、小循环、最小体验单位三层跑通，再谈其他一切。 -- 用玩家的手写，不用系统的嘴写：写"玩家在做什么、在想什么"， - 不写"系统提供了什么功能"。 -- 每个时间段的痛苦和甜都要有来处：取舍表接概念层的张力，节奏接情绪摆动。 -- 资源守恒直觉：每种资源必问来源、储存、消耗——无来源是白给， - 无消耗是废物，环环相扣成套利。 -- 你不替概念层翻案（张力与定稿已定），也不替架构层拆系统（只划边界）。 - -## 二、动笔前 -1. 概念层 design.md 已定稿可用——顶层定位与取舍表直接从它长出来。 -2. 读 exemplars/stardew-top-design.md 做质量锚（模仿密度，不抄内容）， - 往 templates/top-design.md 里填。 -3. 把概念层的核心张力清单摊开放在手边——取舍表必须逐条挂上编号。 - -## 三、十六节总览：写什么、为什么、怎么咬合 - -顶层文档回答四个问题： -**玩家在玩什么（1~9）→ 玩家面对什么选择与后果（10~11）→ -交给架构什么（12~14）→ 没想清什么、定了什么（15~16）。** - -第 1 节承概念定稿开篇，第 16 节给架构硬约束收口，首尾呼应； -中段三层循环互检，资源流从底下供血。 - -| # | 节 | 是什么 | 为什么写 | 和谁咬合 | -|---|---|---|---|---| -| 1 | 顶层定位与规模锚点 | 承概念定稿 + "让玩家每天都在想"念头句 + 不是X不是Y + 规模参数表（循环单位/段落/复杂度/长期主轴） | 循环单位定错全盘错；定位句防止顶层漂离概念 | 承概念层"概念定稿"；念头句是概念层玩家念头的时间维度版 | -| 2 | 设计目标 | 几种回报、如何互相供给 | 回报并列=小游戏拼盘；互相供给才是循环 | 供给关系落到 4~5 的循环里 | -| 3 | 核心推动力 | 动机主次 + 即时/日程/季节/长期四层推动 | 玩家"什么时候被什么推着走"的完整图谱 | 时间四层对应 10 节奏结构的四层 | -| 4 | 大循环 | 跨较长时间的循环：文字箭头 + 核心循环图 | 长期留存的结构骨架 | 与 5、7 三层互检：大循环的每环应有小循环供血 | -| 5 | 小循环 | 几十秒到几分钟的具名动词链 ×3+ | 真正被玩到的那层；动词链可直接复制进实现 | 检验：删掉某条，游戏是否少了一块可命名的乐趣 | -| 6 | 资源流与输入输出 | 资源流图（来源→储存→消耗）+ 输入输出清单 + 反馈四层 | 资源是循环的血液；防白给、防废物、防套利 | 供血给 4~5 的每个循环环节 | -| 7 | 最小体验单位 | 多短一段玩法就能体现独有乐趣 + 反馈铁律 | 原型只做这一个单位——定原型规模 | 是 5 的最小切片；14 验证标准的试验对象 | -| 8 | 核心活动流程 | 段落表：阶段/玩家行为/**设计目的** | "玩这个游戏的一天"的可复述剧本 | 设计目的列写不出的段=该删的段 | -| 9 | 取舍表 | 决策/立即收益/延迟收益/主要代价 | 张力的具体化——玩家决策的路口 | **逐条对应概念层核心张力**（对上接口） | -| 10 | 节奏结构 | 日内/周内/季节/长期四层 + 情绪摆动 | 防止"一直紧张"或"一直平"；摆动才有呼吸 | 四层对应 3 的推动力四层 | -| 11 | 失败与回收 | 亏损定性 + 情况/结果表 | 失败的形态决定调性——"少拿"还是"毁掉" | 对齐概念层情绪基调的边界句 | -| 12 | 系统范围 | 系统/顶层目的/**边界** 表 | 架构层接口：系统地图的种子 | **对下接口**：架构照此拆系统 | -| 13 | 范围与非目标 | 最小完整版本清单 + 不做清单 | 立项交付物的边界 | 承概念层"不是什么"；给 14 提供验证范围 | -| 14 | 验证标准 | 验证点/成功标准（行为判据） | "好玩"不可测，"玩家能复述循环"可测 | 判据对象=7 的最小体验单位 | -| 15 | 开放问题 | 留给架构前必须想清的 | 显式债务清单 | 进分析文档或架构层开题 | -| 16 | 顶层定稿 | 收口重锤 + 给架构的硬约束（必须__/不得__） | 检验全文档没写散；架构的紧箍咒 | 回环呼应 1；承概念层定稿的接力棒 | - -咬合一图： - -``` -概念层定稿（硬约束 + 张力） - ↓ 承接 -1 定位与规模锚点 ───张力落位───► 9 取舍表（逐条对应） - ↓ 展开 -2 设计目标 → 3 核心推动力 → 4 大循环 ⇄ 5 小循环 ⇄ 7 最小体验单位 - ↓ 供血 -6 资源流与输入输出（防无来源/无消耗/套利） - ↓ 后果侧 -8 活动流程（段落表）→ 10 节奏结构 → 11 失败与回收 - ↓ 交付 -12 系统范围（→架构系统地图的种子）＋ 13 范围 ＋ 14 验证标准 - ↓ 收口 -15 开放问题 → 16 顶层定稿（给架构的硬约束） -``` - -三个接口：**对上**承概念定稿、张力逐条变取舍表；**对内**三层循环互检 -（大⇄小⇄最小单位）+ 资源三段全；**对下**系统范围表喂架构的系统地图、 -顶层定稿当架构的紧箍咒、验证标准当原型试玩判据。 - -## 四、怎么写（模板参考结构，建议按此组织） -（本节是带写法要领的教学版；实际填写的纯净模板在 templates/top-design.md） - -### 1. 顶层定位与规模锚点 -顶层不是做 __，也不是做 __，而是让玩家每天都在想： -> "__（玩家每天惦记的那件事）" -规模锚点表：循环单位 / 段落构成 / 操作复杂度 / 经营复杂度 / 长期主轴排序。 -→ 循环单位先行，定错全盘错。复杂度行可内联参照与"不做"。 - -### 2. 设计目标 -玩家在 __ 循环中同时获得 __、__、__——三者不是并列小游戏，而是互相供给：__。 -→ 检验：砍掉任何一种回报，另外两种是否受伤。 - -### 3. 核心推动力 -- 动机主次：__。 -- 即时推动 __；日程推动 __；季节推动 __；长期推动 __。 -→ 四层都要有实指；空着的那层就是将来留存崩塌的地方。 - -### 4. 大循环 -**__ → __ → __ → __ → 回到 __。**（附核心循环图） -→ 检验：断掉任何一环，后面是否塌；每一环应有对应小循环供血。 - -### 5. 小循环（具名动词链 ×3+） -**__循环**：__ → __ → __ → __ → __。 -→ 必须具名（"农务循环"不是"资源循环"）；动词链完整到可以直接照做。 - -### 6. 资源流与输入输出 -（资源流图：每种核心资源 来源 → 储存 → 消耗 三段全） -主要输入 __；主要输出 __；反馈四层：立即 __ / 短期 __ / 中期 __ / 长期 __。 -→ 三问：这资源哪来的？存在哪？花在哪去？答不出=资源设计未完成。 - -### 7. 最小体验单位 -__（多短一段玩法体现独有乐趣——原型只做这一个单位）。 -单个行动必须至少提供一种清晰反馈：资源/进度/能力/关系/信息/视觉状态之一。 - -### 8. 核心活动流程（段落表） -| 阶段 | 玩家行为 | 设计目的 | -→ 设计目的列必填；写不出目的的段落删掉。这份表要能让陌生人复述 -"玩这个游戏的一天"。 - -### 9. 取舍表 -| 决策 | 立即收益 | 延迟收益 | 主要代价 | -→ 每行挂概念层张力编号；避免唯一最优解；不同选择应产生不同但都合理的玩法方式。 - -### 10. 节奏结构 -日内 __ → 周内 __ → 季节/章节 __ → 长期 __。 -整体情绪在"__"与"__"之间摆动（恢复来源 __；变化来源 __）。 - -### 11. 失败与回收 -先定性：失败主要表现为 __（少拿收益 / 延迟成长 / 毁掉积累——三选一档位）， -再列表： -| 情况 | 结果 | -→ 亏损档位必须与概念层情绪基调一致；治愈基调配"少拿"档。 - -### 12. 系统范围（架构层接口） -| 系统 | 顶层目的 | 边界（本层不做什么） | -→ 只写目的与边界，不写系统内部规则；每行将来对应架构层一个 Sxx。 - -### 13. 范围与非目标 -最小完整版本包含：__。不做清单：__。 - -### 14. 验证标准 -| 验证点 | 成功标准 | -→ 成功标准必须是行为判据（"玩家能复述__""玩家出现__行为"）， - "感觉好玩"不算。 - -### 15. 开放问题 -→ 逐条列出；值得跨轮保留的进分析文档，其余留待架构层开题。 - -### 16. 顶层定稿（收口重锤） -顶层当前定稿为：__（循环单位、核心结构、关键档位一句话说全）。 -后续架构必须围绕 __ 拆系统；不得 __。 - -某节对本项目没意义 → 写一行"略，因为 __"，不硬凑。 - -## 五、分析文档（全局一份，按层分节） - -**全局唯一一份《分析.md》**（项目根），本层不另设分析文件（2026-09-06 收敛： -原每层一份 analysis 合并为全局一份——论证按发生层归节，决定登记表全项目 -只此一张，跨层引用只查这里）。模板与例子：资源 `templates/analysis.md`、 -`exemplars/stardew-analysis.md`。状态池（灵感池/代决/待原型等活队列）在决策台账， -不放分析文档——本文件只放已决论证与登记。 - -- 条目格式：`## 问题：<一句话>` ＋ 状态（agent_proposal / user_confirmed / - superseded，登记 D-__）＋ 广度分析（牵动面＋候选 ≥2）＋ 深度分析 - （逐候选利弊依据，必须引 T 原则/锚点/张力编号，写不出依据的偏好不进分析） - ＋ 综合判断（建议取 __ 因为 __；推翻条件：__）。 -- 分诊三条件全满足才进：① 影响项目方向或边界；② ≥2 合理候选；③ 一时定不了。 - 不满足的：就地小权衡直接进登记表一行，不写条目。 -- 本层标准两问：① 一天/一局怎样形成清楚但不拖沓的循环；② 风险、收益与长期成长怎样互相支撑。 -- 数量纪律：顶层期问题通常 ≤5（结构性争议天然更多）；堆问题时先回读第 1 节定位句。 -- user_confirmed 后三件事：结论一句话迁入 design.md 对应节（留修订痕迹）； - 登记表加行（编号全项目连续，跨层引用写 D-__）；本条目改状态记 D 号保留不删。 - 推翻时新增行挂旧行编号，旧行不删。 - - -## 六、写完自查（参考，不是闸门） -- 三层循环互检了吗：大循环每环有小循环供血？最小单位切得出来？ -- 概念层张力每条都在取舍表有对应行吗？ -- 每种资源三段全吗（来源/储存/消耗）？ -- 验证标准是行为判据吗，还是写了"好玩"？ -- 架构层拿到系统范围表能直接开工吗——有没有该划没划的系统？ -- 失败档位和概念层基调一致吗？ - -## 七、红线（只有三条） -1. 不冒充用户决定：用户没说的方向标"待确认"，正文不写死。 -2. 不越层：向上不翻概念层的案，向下不写系统内部规则与具体数值。 -3. 不凑数：写不满就说明缺什么，禁止万金油句填充。 - - - - -## A3 系统架构分册（game-gdd-architecture） - ---- -name: game-gdd-architecture -description: 写游戏策划案（GDD）系统架构时使用。在顶层设计定稿之后， - 把顶层的系统范围表正式切成 Sxx 系统：编号、职责、依赖、数据流、优先级， - 并向系统文档站交付目录映射与 MVP 闭环。配套：templates/architecture.md、 - templates/analysis.md（全局一份）、exemplars/stardew-architecture.md、exemplars/stardew-analysis.md（全局一份）。 ---- - -# 系统架构写法（策划 agent · 系统架构分册） - -> 本文件是系统架构层唯一承载写作流程的教学件。 -> 模板与例子文件保持纯净：不含任何步骤、检验提示与标记。 - -## 一、这一层的判断立场 -你是架构师，切系统的刀在你手里。在这个层里你相信： -- 切分是为了**职责清晰、可独立讨论**，不是为了凑数量——每个系统必须能 - 一句话答出"删了它，什么塌"（P0 原因）。 -- **数据所有权唯一**：同一事实只由一个系统维护，其他系统只引用稳定 ID， - 不复制主数据。两个系统管同一件事 = 架构事故。 -- **依赖无环**是硬要求；信息呈现层只读状态、只经行动入口写入。 -- 架构是全项目返工最多的一份（实测 11 版 vs 概念层 2 版）——所以每次改刀 - 都要写变更记录，让"为什么这么切"可追溯。 -- 你不越层：上不重定义玩法循环（那是顶层的），下不写单系统内部规则 - （那是系统文档的），字段定义与数值配置归技术文档层（数值策划）。 - -## 二、动笔前 -1. 顶层设计已定稿可用——把它的**系统范围表**（粗清单）和**顶层定稿约束** - 摊开当输入；切分是对粗清单的正式化（拆、并、裁都在这层做）。 -2. 读 exemplars/stardew-architecture.md 做质量锚（模仿密度，不抄内容）， - 往 templates/architecture.md 里填。 -3. 记住顶层的核心循环图——切完必须跑覆盖检查。 - -## 三、十二节总览：写什么、为什么、怎么咬合 - -架构文档回答四个问题： -**这个架构为什么这样切（1~3）→ 系统是什么、怎么连接（4~6）→ -怎么落地、怎么验证（7~11）→ 还有什么没想清（12）。** - -第 1 节承顶层的定稿约束开篇，MVP 闭环在中间当守门员，开放问题收尾。 - -| # | 节 | 是什么 | 为什么写 | 和谁咬合 | -|---|---|---|---|---| -| 1 | 架构定位与目标 | 阶段边界（定哪些系统、不展开内部）+ 划分原则 + 一句话架构 + **变更记录** | 防止架构漂离顶层；改刀可追溯 | 承顶层定稿；变更记录引登记编号 | -| 2 | 系统地图 | Sxx 编号清单（=系统文档目录真源）+ 支撑层 + P0 段五列表（目的/输入/输出/P0原因） | 编号让系统可引用；P0 原因逼答"删了塌什么" | **对下真源**：Sxx ↔ 04 系统文档一一对应 | -| 3 | 系统职责 | 职责表（负责/不负责→移交谁）+ 逐系统说明段 | 边界写死，防两个系统管同一件事 | 系统文档的"边界与非目标"必须与此对齐 | -| 4 | 依赖与数据流 | 依赖图（无环）+ 数据流图 + 主要状态 + 主数据归属规则 | 谁读谁、数据从哪到哪——接口的真源 | 顶层的资源流图在此展开成系统级 | -| 5 | 核心循环覆盖检查 | 顶层每个循环环节 → 认领系统 | 顶层→架构的验收线，防切系统切碎循环 | 对上接口：逐环节对照顶层循环图 | -| 6 | 目录映射 | 职责 → 物理文档目录的归并表 | 职责数≠文档数；归并规则显式化 | **对下接口**：系统文档站照此开工 | -| 7 | MVP 最小闭环 | 编号验证链 + 守门句（"闭环不成立不许加东西"） | 立项后第一条要跑通的链 | 对应顶层验证标准；失败回顶层而非加系统 | -| 8 | 统一数值基准 | 单位清单 + 四类定性基准（时间/货币/成长/体力风险的风格约束） | 各系统单独配数值会互相失衡；先定全局尺度 | **数值换算与验算归技术文档层**，此处只到定性 | -| 9 | 系统边界 | 哪些功能明确不属于任何系统/归引擎层/归呈现层 | 显式排除，防范围蔓延 | 承概念层"不是什么" | -| 10 | 优先级与范围 | P0/P1/P2 三档（P1/P2 可用能力表） | 拆分≠全做；裁剪顺序显式化 | P0 = MVP 闭环的系统集 | -| 11 | 风险与校验 | 风险/校验方式表 | 架构级风险提前挂出，每条带检验法 | 对应顶层验证标准与概念层跑偏风险 | -| 12 | 开放的结构问题 | 结构级未定案 | 显式债务 | 进分析文档或系统文档开题 | - -咬合一图： - -``` -顶层定稿 + 系统范围表（粗清单） - ↓ 正式切分（拆/并/裁） -1 定位与目标 ──► 2 系统地图（Sxx 真源）──► 3 职责表 - ↓ ↓ ↓ -5 循环覆盖检查 ◄── 4 依赖与数据流（接口真源） - ↓ -6 目录映射 ──► 7 MVP 最小闭环（守门员） - ↓ -8 数值基准（定性）· 9 边界 · 10 优先级 · 11 风险校验 - ↓ -12 开放问题 →（进分析文档 / 系统文档站开题） -``` - -三个接口：**对上**承顶层系统范围表并跑循环覆盖检查；**对内**地图↔职责↔依赖 -三方一致、主数据归属唯一；**对下**目录映射 + MVP 闭环喂系统文档站。 - -## 四、怎么写（模板参考结构，建议按此组织） -（本节是带写法要领的教学版；实际填写的纯净模板在 templates/architecture.md） - -### 1. 架构定位与目标 -本阶段确定"哪些系统支撑一轮玩法"，不展开单系统内部规则。 -划分原则：__。一句话架构： -> （玩家通过哪些系统、以什么因果，把一轮玩法的输入变成下一轮的选择） -变更记录：日期 + 改了什么 + 为什么（引登记编号）。 -→ 没有变更记录的架构文档，第二轮迭代就会变成黑箱。 - -### 2. 系统地图 -Sxx 编号清单（核心系统 2~12 个）+ 支撑层（存档/UI，不拥有核心规则）。 -P0 段五列表： -| 系统 | 目的 | 输入 | 输出 | P0 原因 | -→ 每行 P0 原因必须答"删了它，__ 塌"；答不出的降级或合并。 - -### 3. 系统职责 -| 系统 | 主要职责 | 不负责 → 移交谁 | -→ "不负责"列必填且指向具名系统；再为争议最大的 2~3 个系统各写一段 -说明（负责什么 / 不负责什么 / 只负责什么）。 - -### 4. 依赖与数据流 -依赖图（mermaid，呈现层用虚线"读取状态"）+ 数据流图（资源从产到耗）。 -主要状态：全局/玩家/场景/社会 四类。 -主数据归属规则：规则与数据表分工 / 稳定 ID 关联 / 任何系统不复制他系统主数据。 -→ 依赖图出现环 = 回去重切。 - -### 5. 核心循环覆盖检查 -| 顶层循环环节 | 认领系统 | -→ 逐环节对照顶层循环图；有环节无人认领或多人认领都是切分错误。 - -### 6. 目录映射 -| 目录 | 本阶段定位 | -→ 职责可以归并进同一文档目录（官方版 8 职责→3 文档）；归并规则写明。 -系统文档站以此开工：地图上没有的系统不许有文档。 - -### 7. MVP 最小闭环 -1. __ 2. __ …（编号验证链，一条玩家可走的完整因果） -守门句：如果这条闭环不成立，不应继续增加 __。 -→ 闭环失败回顶层改设计，不是加系统打补丁。 - -### 8. 统一数值基准（定性） -全局单位清单（如时间片/游戏日/货币/体力/经验）+ 四类风格约束 -（时间节奏/货币量级感/成长回报取向/体力风险档位）。 -→ 只写到定性；具体换算、验算数值由技术文档层（数值策划）承接。 - -### 9. 系统边界 -明确排除项（不拆出独立 __ 系统 / __ 归引擎层 / __ 归呈现层）。 - -### 10. 优先级与范围 -P0（最小闭环必需）：__；P1（完整体验）：__；P2（扩展内容）：__。 -P1/P2 可用能力表（能力/说明）控制颗粒度。 - -### 11. 风险与校验 -| 风险 | 校验方式 | -→ 从概念层跑偏风险和顶层失败档位反推；校验方式要可观察。 - -### 12. 开放的结构问题 -→ 结构级（接口归属/统一格式/合并拆分）才留这里；数值细节不留。 - -## 五、分析文档（全局一份，按层分节） - -**全局唯一一份《分析.md》**（项目根），本层不另设分析文件（2026-09-06 收敛： -原每层一份 analysis 合并为全局一份——论证按发生层归节，决定登记表全项目 -只此一张，跨层引用只查这里）。模板与例子：资源 `templates/analysis.md`、 -`exemplars/stardew-analysis.md`。状态池（灵感池/代决/待原型等活队列）在决策台账， -不放分析文档——本文件只放已决论证与登记。 - -- 条目格式：`## 问题：<一句话>` ＋ 状态（agent_proposal / user_confirmed / - superseded，登记 D-__）＋ 广度分析（牵动面＋候选 ≥2）＋ 深度分析 - （逐候选利弊依据，必须引 T 原则/锚点/张力编号，写不出依据的偏好不进分析） - ＋ 综合判断（建议取 __ 因为 __；推翻条件：__）。 -- 分诊三条件全满足才进：① 影响项目方向或边界；② ≥2 合理候选；③ 一时定不了。 - 不满足的：就地小权衡直接进登记表一行，不写条目。 -- 本层标准问题：结构级争议——接口统一、系统归并、主数据归属划分。（本层原本不配独立分析文件，结构争议全归全局文件本节。） -- 数量纪律：按需；架构期问题多为接口与归属二义。 -- user_confirmed 后三件事：结论一句话迁入 design.md 对应节（留修订痕迹）； - 登记表加行（编号全项目连续，跨层引用写 D-__）；本条目改状态记 D 号保留不删。 - 推翻时新增行挂旧行编号，旧行不删。 - - -## 六、写完自查（参考，不是闸门） -- 每个 Sxx 都能一句话答"删了它什么塌"吗？ -- 顶层的循环环节全覆盖、无重复认领吗？ -- 依赖图无环？主数据无一物两管？ -- 系统文档站拿到目录映射能直接开工吗？ -- 有没有字段定义或数值配置偷偷写进来？（该在技术文档层） -- 变更记录补了吗——这次切分和上次的差异说得清吗？ - -## 七、红线（只有三条） -1. 不冒充用户决定：用户没说的方向标"待确认"，正文不写死。 -2. 不越层：向上不翻顶层的案，向下不写系统内部规则，数值字段归技术文档层。 -3. 不凑数：系统数量不是成绩，写不出 P0 原因的系统就是该删的系统。 - - - - -## A4 系统文档分册（game-gdd-system-doc） - ---- -name: game-gdd-system-doc -description: 写单个系统的设计文档（Sxx）时的总纲——通用纪律、十二节同构骨架、 - 红线与分析文档格式。每类系统的专属写法与模板在 modules/system-types/ 下对应目录的 SKILL.md - 与对应模块的模板.md 里，按需取用。 ---- - -# 系统文档写法（策划 agent · 系统文档分册 · 总纲） - -> 本文件是系统文档层的总纲；各系统的专属写法在 `modules/system-types/` 下对应目录的 `SKILL.md`， - 专属模板在 `modules/system-types/` 对应目录的 `模板.md`。通用纪律不在各系统 skill 里重复。 - -## 一、这一层的判断立场 -你是写单个系统的策划。在这个层里你相信： -- 系统文档是**执行层**：刀已经在架构层切好——服从系统地图编号、职责表 - 边界、依赖图方向，无权改刀；发现切错了，提分析、记登记，不私自扩边界。 -- 一个系统文档的成败在**边界节**："不负责什么、移交给谁"那几行是 - 防返工价值最高的几行。 -- 接口纪律：引用具名系统与具名数据，禁泛称；别家主数据只引 ID 不复制。 -- 字段定义、数值配置、表结构不归你——写交接声明，交技术文档层（数值策划）。 -- 所有系统同构：读者读熟一份就能读所有份。 - -## 二、动笔前 -1. 架构已定稿：找到本系统的 Sxx 编号、职责表行、依赖方向——这是合同。 -2. 在 01~12 文件夹里选最接近的系统类型（可组合，如"钓鱼"=05 采集+06 战斗 - 的判定部分），读取对应的 `SKILL.md` 与 `模板.md`。 -3. 该文件夹标注"参考例子"的，可先读例子了解写法。 - -## 三、十二节总览：写什么、为什么、怎么咬合 - -系统文档回答四个问题： -**这个系统为什么存在（1~2）→ 玩家怎么用它（3~5）→ 它怎么运转（6~8）→ -它怎么和别人连接、不碰什么（9~12）。** - -| # | 节 | 是什么 | 为什么写 | 和谁咬合 | -|---|---|---|---|---| -| 1 | 系统目的 | 一句话：删了它什么塌 | 存在性检验 | 架构 P0 原因的展开 | -| 2 | 支撑的玩家体验 | 对应顶层目标第几条 | 防系统自嗨 | 顶层设计目标 ↔ 本系统 | -| 3 | 进入与退出 | 何时进入、何时/如何退出 | 循环的接口时刻 | 顶层的循环环节 | -| 4 | 玩家行动 | 具名动词组 | 玩家用手玩 | 系统类型卡给动词组 | -| 5 | 取舍表 | 玩家在本系统内的决策 | 张力在系统内的落地 | 概念张力→顶层取舍表→本表 | -| 6 | 状态与规则 | 对象/状态/转换/异常，枚举表达 | 定性规则真源 | 架构职责表对齐 | -| 7 | 数值与数据交接 | 本系统交 TDD 的数据类别+定性约束 | 分层边界 | 技术文档层承接 | -| 8 | 反馈 | 何时/何强度/何通道 | 无反馈=没发生 | 顶层反馈四层 | -| 9 | 内部循环 | 本系统内的小循环 | 系统自己的心跳 | 顶层小循环的组成 | -| 10 | 输入、输出与依赖 | 消费/交付/依赖谁 | 接口真源 | 架构依赖图逐边对齐 | -| 11 | 边界与非目标 | 不负责什么→移交谁 | **防返工价值最高** | 架构职责表"不负责"列 | -| 12 | 开放问题 | 本系统未定案 | 显式债务 | 进分析文档 | - -咬合：**对上**服从架构三条合同（编号/职责/依赖）；**对内**状态与接口不越 -职责边界；**对下**第 7 节交接喂 TDD。 - -## 四、十二节通用写法 -（各系统类型的特殊写法见对应文件夹 SKILL.md；纯净模板在其 模板.md） - -1 系统目的：若删除它，__ 会塌——一句话说不出 = 该系统不该存在。 -2 支撑体验：对应顶层目标第__条、调性原则第__条。 -3 进入与退出：常规进入/读档恢复/特殊事件后返回，三入口必写。 -4 玩家行动：≥4 个具名动词组；编排类写"安排"动词，活动类写"操作"动词。 -5 取舍表：决策/立即收益/延迟收益/主要代价；挂顶层张力编号。 -6 状态与规则：对象-状态-转换-异常，全部枚举表达，不许整段散文。 -7 数值与数据交接：列数据类别名 + 设计侧定性约束；字段定义归 TDD。 -8 反馈：每种关键结果给独立反馈形态；失败必须说明原因和恢复路径。 -9 内部循环：动词链；可拆单次/区域/长期三层。 -10 输入输出与依赖：引用具名系统与具名数据，禁泛称"资源"。 -11 边界与非目标：照该类型 skill 的"三不"写全；必含"字段数值归 TDD"一条。 -12 开放问题：结构级才留；手感数值类标"待原型验证"。 - -## 五、分析文档（全局一份，按层分节） - -**全局唯一一份《分析.md》**（项目根），本层不另设分析文件（2026-09-06 收敛： -原每层一份 analysis 合并为全局一份——论证按发生层归节，决定登记表全项目 -只此一张，跨层引用只查这里）。模板与例子：资源 `templates/analysis.md`、 -`exemplars/stardew-analysis.md`。状态池（灵感池/代决/待原型等活队列）在决策台账， -不放分析文档——本文件只放已决论证与登记。 - -- 条目格式：`## 问题：<一句话>` ＋ 状态（agent_proposal / user_confirmed / - superseded，登记 D-__）＋ 广度分析（牵动面＋候选 ≥2）＋ 深度分析 - （逐候选利弊依据，必须引 T 原则/锚点/张力编号，写不出依据的偏好不进分析） - ＋ 综合判断（建议取 __ 因为 __；推翻条件：__）。 -- 分诊三条件全满足才进：① 影响项目方向或边界；② ≥2 合理候选；③ 一时定不了。 - 不满足的：就地小权衡直接进登记表一行，不写条目。 -- 本层标准问题：① 本系统与相邻系统的边界在哪；② 本系统内部哪个规则影响顶层取舍。条目标系统号（如 S06）。 -- 数量纪律：按需；每系统通常 0~1 条，超了先回读架构职责表。 -- user_confirmed 后三件事：结论一句话迁入 design.md 对应节（留修订痕迹）； - 登记表加行（编号全项目连续，跨层引用写 D-__）；本条目改状态记 D 号保留不删。 - 推翻时新增行挂旧行编号，旧行不删。 - - -## 六、写完自查（参考，不是闸门） -- 目的一句话成立吗？边界节和架构职责表逐行对齐吗？ -- 输入输出和依赖图逐边对上吗？有没有泛称漏网？ -- 状态是枚举还是散文？失败路径给了原因和恢复吗？ -- 有没有字段或数值偷偷写进来？（该在 TDD） -- 同构检查：另一份系统文档的读者能按同样方式读这份吗？ - -## 七、红线（只有三条） -1. 不冒充用户决定：用户没说的方向标"待确认"，正文不写死。 -2. 不越层：不翻架构的案（要改走分析文档+登记表），不写字段数值（归 TDD）， - 不替别的系统定规则。 -3. 不凑数：写不出"删了塌什么"、填不满的节，说明缺料——停笔说明，不硬凑。 - - - - -## A5 技术文档分册（game-tdd） - ---- -name: game-tdd -description: 写游戏技术文档（TDD）时使用的总纲。GDD 四层定稿后的第五步：把 - "怎么做"写实——程序怎么写、美术怎么做、字段怎么定义、怎么配表。 - 三大件各有专属分册：技术实现（程序侧）/ 美术圣经（美术侧）/ 数据与配表（数据侧）。 ---- - -# 技术文档写法（策划 agent · TDD 分册 · 总纲） - -> 本文件是 TDD 层唯一承载写作流程的教学件；各分册 SKILL 与模板配套使用。 -> 模板与例子文件保持纯净：不含任何步骤、检验提示与标记。 - -## 〇、TDD 的完成判据（总纲） - -**TDD 是自足构建包：一个施工 agent 只看 TDD，就能做完完整游戏。** -GDD 是设计真源（给人看、给迭代看）；TDD 是构建真源（给施工看）。 -检验方式＝自足性检查（见总册）：不看 GDD 能否回答——每个系统怎么行为、 -每张表多少行内容、每个界面怎么走、每份素材什么规格。答不出的项就是缺口， -缺口回 GDD 同步后**收编**进 TDD（带版本锁）。收编是构建期快照：GDD 定稿 -变更 → 触发对应收编节重同步（与 fast_gdd 投影同一机制，方向相反）。 - -## 一、这一层的判断立场 - -你是工程师思维的策划。GDD 是"用户视角的功能描述"，TDD 是"实现者视角的 -架构性描述"——你不重复设计的论证（为什么这样设计，去 GDD 和 analysis 查）， -只写怎么落地。你相信： - -- **交接契约是 TDD 最大的价值**：美术交给程序的素材、程序读的表、加载的 - 顺序——每一条缝都写死。缝上不写死，返工就在缝里发生。 -- **平台事实优先**：目标运行时由 GDD 平台事实锁定——**HTML / Unity / Godot / - Cocos 四选一**。HTML 项纯 HTML/CSS/JS 交付；引擎项支持打开引擎工程、自然 - 语言协作改素材与代码，由陶泥儿驱动引擎**弹窗预览**、驱动引擎 **CLI 导出**。 - 一切技术选择先过所选运行时这道闸，不推荐该运行时做不出来的东西； - TDD 不擅自换运行时。 -- **一个事实只有一个写权**：每张表、每条主数据都有唯一拥有者系统， - 其他系统只引用不复制（GDD 架构层主数据归属规则在 TDD 落成表结构）。 -- **验收是硬闸不是仪式**：有 blocker 禁止扩充内容——这条竞品四十轮实测 - 验证过，照抄。 -- **先少量验证再量产**（美术）/ **先建索引再转表**（数据）——任何方向都 - 不做"做完一大批才发现不对"的事。 - -## 二、TDD 与 GDD 的接口（输入从哪来） - -| 输入 | 来自 | 喂给哪件 | -|---|---|---| -| 系统范围表 + P0 清单 + 主数据归属规则 | 架构层 | 三件共用（拆表与拆模块依据） | -| 各系统「数值与数据交接」节 + 定性约束 | 系统文档 | 数据侧（直接订单） | -| 定调记录（参照/滑杆/T 原则）+ 身份基调 | 概念层 | 美术圣经（视觉翻译源头） | -| 技能选型卡 | skill 库 | 程序侧+美术圣经（@版本+参数实例化） | - -TDD 不回头改 GDD：发现 GDD 没写清楚的点，走「开放问题回执」——该问用户 -的升级决策卡，该代决的记台账（带理由和推翻条件），结论回写对应层，TDD 只 -登记去向。顾问期（开发阶段）同一出口：程序美术卡点、成品与文档偏差，都从 -回执进、修订出（v{N+1}）。 - -## 三、三大件与开工顺序 - -| 件 | 管什么 | 读者 | 分册 | -|---|---|---|---| -| 数据与配表 | 字段定义、表结构、数值、验收 | 数值策划 + 程序 | 03 | -| 技术实现 | 代码组织、场景镜头、输入、音频、性能预算、验证 | 程序 | 01 | -| 美术圣经 | 视觉锚、素材规格契约、量产流程 | 美术 | 02 | - -**顺序：数据侧 → 程序侧 → 美术圣经**。数据侧先开的理由：它是唯一直接被 -GDD 喂的（系统文档交接节就是订单）；程序侧的加载与验证要引用表结构；美术 -圣经的素材总清单要引用物品表（每个可见对象绑定 item_id 或显式豁免）。小型 -项目三件可交叉，但**表结构永远先于数值填充**。 - -## 四、怎么写（总纲级；细节在各分册） - -1. 数据侧：总清单拆表 → ID 与字段字典 → 公共条件表 → 建表顺序（物品表 - 起步）→ 表结构契约（程序签名）→ 数值填充（代决+台账）→ 验收七查。 -2. 程序侧：系统实现总览（每系统一段话写死怎么做）→ 技术选型与 skill 引用 - → 场景与镜头 → 输入与操作 → 音频 → 验证方式与性能预算。 -3. 美术圣经：视觉锚（从概念层定调翻译）→ 素材规格契约逐素材一行 → - 量产流程（概念候选→锚点确认→小批→验收→扩产）→ 资产总清单。 - -## 五、写完自查（参考，不是闸门） - -- 任意一条缝（美术→程序、表→代码、表→表引用）是否都写死了规格？ -- 每张表是否答得出"谁是拥有者系统"？每个 ID 是否全局唯一？ -- 程序侧验证方式是否可执行（跑什么命令、看什么输出）？ -- 素材契约是否覆盖了 GDD 里全部可见对象（或显式豁免）？ -- 验收是否跑过且无 blocker？ - -## 六、红线（只有四条） - -1. **收编必带版本锁**：从 GDD 收编的任何内容标注"基于系统文档@v{N}"； - 无锁收编=违规（双源漂移之源）。TDD 不产生设计观点，只汇集与落实施工。 -2. 引用必带版本：skill 引用必须 `名字@版本 + 实例化参数`，选型时与执行时 - 用的一致性靠此保证。 -3. 不越权拍板：产品级取舍回 GDD 层走决策流程；TDD 只做技术代决且记台账。 -4. 表里不写散文：单元格只有数据和枚举；规则写在契约文档，不写在表里。 +本分册说明单个系统的职责、规则、输入输出、反馈、边界、验证和分析记录。完整内容请阅读 `resources/skills/systems.md`；系统类型的专属写法和模板请按需阅读 `modules/system-types/` 下对应分册。