把设计文档（GDD）交付给程序员前…

在一份设计文档交给程序员实现之前，按项目 workflow 档位与 review 模式对单个 GDD 做审查，输出缺失章节、依赖断链、阻塞项、专家分歧、范围信号与最终结论。

适用场景

解决思路

1. 解析参数与配置：用 `--review` 覆盖 `review_mode`；按 `workflow` 档位（full/standard/minimal）确定校验范围；按模式确定深度——`full` 跑全部阶段并做专家委派（Phase 3b），`lean` 跑全部阶段但不派专家（更快、单会话），`solo` 只跑 Phase 1-4、不委派也不给下一步提示（供其他技能内部调用）。
2. 评审前先做 freshness check：运行 `bash .claude/scripts/review-receipts.sh check "design/gdd/reviews/[doc-name]-review-log.md" "[target-doc-path]" "design/registry/entities.yaml"`；只有列出的每一行都读到 UNCHANGED（registry 不存在就不出现、也不阻塞跳过）才可安全跳过。
3. 全部 UNCHANGED 且日志最新条目带结论时：直接复述旧结论，例如「本文档与 [日期] 的上次评审逐字节一致（结论：[verdict]）」；若旧结论是 APPROVED，用 `AskUserQuestion` 给 `[A] 沿用旧结论（推荐）` / `[B] 仍然重新评审`（guided 模式直接走 [A]，autonomous 模式用 `log_decision` 记录并采用旧结论）；若旧结论是 NEEDS REVISION 或 MAJOR REVISION NEEDED，明确指出文档自上次未通过后没有任何改动、旧发现原样成立、下一步是修订文档而不是重评审，并提出可展示日志中的旧 findings。
4. 若只有 registry 那一行是 CHANGED（文档本身 UNCHANGED）：保留原结论，但重新核对文档中来自 registry 的跨文档事实值，按新 registry 重新给出结论；只有发现冲突才升级为完整重评审。
5. 若目标文档是 CHANGED / NEW / RECEIPT: NONE：执行下面的完整评审；不要提供跳过未改章节的部分式/delta 重评审——实测三种独立做法都只抓到完整评审所发现 6 个真实缺陷中的 2 个，且最仔细的版本比完整评审还更贵。
6. 完整读取目标设计文档，并读取 CLAUDE.md 以了解项目上下文与标准。
7. 跨文档事实优先查 registry 而不是兄弟 GDD：若 `design/registry/entities.yaml` 存在且列出本系统条目，用两次 Grep——pattern="source: design/gdd/[system].md" 配 `-A 6`（找本系统拥有的条目，上下文含其 `referenced_by:` 块），以及 pattern="design/gdd/[system].md" 配 `-B 8`（找引用本系统的条目；`referenced_by:` 是块序列，键与路径分行，不能用 `referenced_by.*name` 单行匹配，否则永远匹配不上）。
8. 若 registry 不存在或没有本系统条目（这是 `/design-system` 填充前的默认状态）：回退读取目标文档 Dependencies 章节点名的相关 GDD，读取范围就限定在那些文档，不要「顺带」扩读，也不要 glob 读取整个 `design/gdd/`。
9. 依赖图校验：对 Dependencies 中列出的每个系统用 Glob 检查其 GDD 文件是否存在于 `design/gdd/`，把不存在项标为断链（下游作者会直接踩到）。
10. 世界观/叙事对齐：若 `design/gdd/game-concept.md` 或 `design/narrative/` 下任何文件存在就读取，记下本 GDD 中与既定世界规则、语气、设计支柱矛盾的机制选择，并把这份上下文传给 Phase 3b 的 `game-designer`。
11. 历史评审检查：若 `design/gdd/reviews/[doc-name]-review-log.md` 存在，读最新条目，记下结论与所列阻塞项；本次作为重评审，跟踪这些项是否已被处理。
12. Phase 2a 用确定性脚本收集章节存在性（不读文档）：运行 `bash .claude/scripts/gdd-structure-check.sh [target-doc-path]`，它输出 `PRESENT:` 列表以及在适用时输出 `ABSENT:` 列表；它只报存在性、不做 REQUIRED/ADVISORY 判断，并且已把 `## Detailed Design` 视为满足 `Detailed Rules`，不要因此误报缺失。
13. Phase 2b 按已解析的 workflow 档位给每个章节标 REQUIRED 或 ADVISORY：缺失 REQUIRED 阻塞批准，缺失 ADVISORY 只作为建议呈现、不阻塞；判定为 PRESENT 的章节若只是空标题仍可能不通过，结论所依赖的章节要抽查。检查清单：Overview（一段式摘要）所有档位 REQUIRED；Player Fantasy（预期感受）full 必需、standard 为建议；Detailed Rules（无歧义机制）full/standard 必需（标题为 `## Detailed Design` 也接受）；Formulas（含变量的全部数学）full 必需，standard 下只要系统定义数值规则（速率、曲线、阈值、成本、伤害、掉落权重）就必需、否则为建议——Category 只是提示不是判据；Edge Cases full/standard 必需；Dependencies full/standard 必需；Tuning Knobs（可配置值）full 必需、standard 为建议（除非 `workflow_overrides.tuning_knobs`）；Acceptance Criteria full/standard 必需。
14. 内部一致性检查：公式产出的数值是否与描述的行为相符；边界情况是否与主规则矛盾；依赖是否双向（对方系统是否知道本系统）。
15. 可实现性检查：规则是否精确到程序员无需猜测即可实现；是否存在细节缺失的「挥手」段落；是否考虑了性能影响。
16. 跨系统一致性检查：是否与既有机制冲突；是否会产生意外交互；是否符合游戏既定语气与设计支柱。
17. Phase 3b 仅在 full 模式执行且在 full 模式强制不可跳过（lean/solo 跳过）：派发 agent 前先打印通知——「Full review: spawning specialist agents in parallel. This typically takes 8–15 minutes. Use `--review lean` for faster single-session analysis.」。
18. 用 Phase 1 已加载的 GDD（不要重读）识别它触及的所有领域，按信号表选专家：成本/价格/掉落/奖励/经济→`economy-designer`；战斗数值/伤害/生命/DPS→`game-designer`+`systems-designer`；AI 行为/寻路/选目标→`ai-programmer`；关卡布局/刷怪/波次结构→`level-designer`；玩家成长/XP/解锁→`economy-designer`+`game-designer`；UI/HUD/菜单/玩家可见展示→`ux-designer`+`ui-programmer`；对话/任务/剧情/设定→`narrative-director`；动画/手感/时序/juice→`gameplay-programmer`；多人/同步/复制→`network-programmer`；音效线索/音乐触发→`audio-director`；性能/draw call/内存→`performance-analyst`；引擎特定模式或 API→引擎专家（由 `engine.name` 决定：Godot→`godot-specialist`、Unity→`unity-specialist`、Unreal→`unreal-specialist`，回退到 `technical-preferences.md` 中 `## Engine Specialists` 的 Primary 行）；验收标准/测试覆盖→`qa-lead`；数据 schema/资源结构→`systems-designer`；任何玩法系统→`game-designer`（始终）。
19. 并行派发所有相关专家：`Agent` 在这里启动的是拥有独立上下文窗口的子会话，不是任务追踪；不要内部模拟专家视角、不要自己代替领域专家推理，必须真正发出 `Agent` 调用，并一次性同时发出，不要一个一个来。
20. 对每个专家使用对抗式提示词：给出 [system] 的 GDD 与主评审目前的结构性发现；说明其任务不是验证设计而是找问题；要求从本领域专业角度挑战设计选择，指出错误、欠明确、易出问题或完全缺失之处；要求具体且批判，与主评审不一致是受欢迎的。
21. 追加各 agent 的专属要求：`game-designer` 以本 GDD Section B 的 Player Fantasy 为锚，判断设计是否真能兑现该幻想、玩家是否会感到预期体验，标出为可实施性牺牲既定感受的规则；`systems-designer` 对每个公式代入边界值（最小与最大合理输入），报告输出是否退化——负值、除零、无穷或极端下无意义；`qa-lead` 逐条审查验收标准，标出不可独立测试的（如「feels balanced」「works correctly」「performs well」），并对不合格者给出具体改写建议。
22. 所有专家返回后，启动 `creative-director` 作为资深评审：提供 GDD、全部专家发现以及彼此分歧，请其综合出最重要的问题、说明是否同意专家、给出对该设计的整体结论；其综合即为 Phase 4 的最终结论。
23. 若专家彼此之间或与 `creative-director` 意见不一致，不要私自取舍，必须在 Phase 4 明确呈现分歧让用户裁决；每条发现都标注来源，如 `[game-designer]`、`[economy-designer]`、`[creative-director]`。
24. Phase 4 按固定模板输出：`## Design Review: [Document Title]`，含 Specialists consulted、Re-review（是/否 + 上次结论与日期）、Completeness、Dependency Graph（每个依赖标 ✓ 存在 / ✗ NOT FOUND）、Required Before Implementation（仅阻塞项，编号 + 来源标注）、Recommended Revisions、Specialist Disagreements（两边都呈现）、Nice-to-Have、Senior Verdict、Scope Signal、Verdict。
25. Completeness 的 N 不要硬编码为 8：full 档 8 个必需、standard 档 5 个（系统定义数值规则时再加 Formulas）、minimal 档 0 个；报成「standard 项目 5/8，缺 Player Fantasy、Formulas、Tuning Knobs」会让读者学会忽略评审。
26. Completeness 只列本档位 REQUIRED 且确实缺失的章节；ADVISORY 缺口单独标注为「advisory at `standard`」，不要当作缺失列出。
27. Scope Signal 依据依赖数量、公式数量、触及系统数、是否需要新 ADR 估算：`S`=单系统、无公式、无新 ADR、<3 个依赖；`M`=中等复杂度、1-2 个公式、3-6 个依赖；`L`=多系统集成、3+ 个公式、可能需要新 ADR；`XL`=跨领域关注点、5+ 依赖、可能多个新 ADR；并明确标注为「Rough scope signal: M（producer should verify before sprint planning）」。
28. Verdict 取值为 APPROVED / NEEDS REVISION / MAJOR REVISION NEEDED / NOT ASSESSED：当评审无法真正执行（目标文档缺失、不可读、被审章节为空，或其所依赖文档缺失导致标准无法适用）时用 `NOT ASSESSED`，并点名缺少什么、由哪个技能产出；不要默认 APPROVED，因为它会被下游当作签核；`NOT ASSESSED` 在任何汇总中优先于 `APPROVED`，但不优先于两个修订类结论（已知问题比未知问题更可行动）。
29. Phase 4 是只读的，本阶段不写任何文件。
30. Phase 5 所有收尾交互一律用 `AskUserQuestion`，不要用纯文本；协作模式下总是询问，guided 模式只问关键节点，autonomous 模式记录后用 `log_decision` 继续；`automation_always_ask` 类目始终弹问。
31. 结论为 APPROVED（首轮、无需修订）时：跳过单独的「下一步做什么」组件，直接进入 systems-index + review-log 组件，再进入最终收尾组件。
32. 结论为 NEEDS REVISION / MAJOR REVISION NEEDED 时先给选项：`[A] Revise the GDD now — address blocking items together` / `[B] Stop here — revise in a separate session` / `[C] Accept as-is and move on（仅在全部项都是建议级时）`。
33. 用户选 [A] 立即修订时：逐条处理所有阻塞项，只有在无法从 GDD 与既有文档自行判断时才询问设计决策；把所有设计决策问题汇入一个多标签 `AskUserQuestion` 一次性问完，不要每个阻塞项都打断一次。
34. 修订完成后给出汇总表（阻塞项 → 已应用的修复），并用 `AskUserQuestion` 展示修订后收尾组件：提示语「Revisions complete — [N] blockers resolved. What next?」；若上下文使用超过约 50%，加上「(Recommended: /clear before re-review — this session has used X% context. A full re-review runs 5 agents and needs clean context.)」；选项为 `[A] 新会话重评审（/clear 后运行 /design-review [doc-path]）` / `[B] 接受修订并标记 Approved（更新 systems index，跳过重评审）` / `[C] 进入下一个系统 /design-system [next-system]（设计顺序第 #N 个）` / `[D] 到此为止`。协作与 guided 模式下绝不以纯文本结束修订流程；autonomous 模式下总结结果并用 `log_decision` 记录。
35. APPROVED 路径下的追踪记录用单个 `multiSelect: true` 的 `AskUserQuestion` 批量处理：把 systems-index.md 中 [system] 状态更新为 'Approved'；向 `design/gdd/reviews/[doc-name]-review-log.md` 追加批准条目。两项都要在显示最终收尾组件之前执行完毕。
36. NEEDS REVISION / MAJOR REVISION NEEDED 时改用分开的组件：先问是否把 `design/gdd/systems-index.md` 中 [system] 标为 In Review / Approved（`[A] Yes — update it` / `[B] No — leave it as-is`）；再问是否把本次评审摘要追加到 `design/gdd/reviews/[doc-name]-review-log.md`（`[A] Yes — append to review log` / `[B] No — skip`）。
37. 追加条目按此格式写：`## Review — [YYYY-MM-DD] — Verdict: [APPROVED / NEEDS REVISION / MAJOR REVISION NEEDED]`，随后 Scope signal、Specialists、`Blocking items: [count] | Recommended: [count]`、Summary（2-3 句 core findings）、`Prior verdict resolved: [Yes / No / First review]`、Findings（每条一行、按所在章节命名，无发现写 `- none`，并用 `[BLOCKING]` / `[RECOMMENDED]` 标注），最后附上运行 `bash .claude/scripts/review-receipts.sh hash "[target-doc-path]"`（registry 文件存在时再加 `"design/registry/entities.yaml"`）的输出。
38. hash 行无论结论如何都要写：它是下次 Phase 1 判断「逐字节相同重评审」的凭据，也是唯一真正安全的跳过形式（输入可证同一，而非「相信上次已经审够了」）；一个未改动却曾评审失败过的文档，正是跳过冗余重评审收益最大的场景（旧 findings 原样成立）。
39. 最终收尾组件（所有文件写入完成后必给）：先读 `design/gdd/systems-index.md` 找出其他 Status 为 In Review 或 NEEDS REVISION 的系统；统计 `design/gdd/` 下 .md 文件数（排除 game-concept.md、systems-index.md）判断是否值得提供 `/review-all-gdds`（≥2 个 GDD）；找出设计顺序中下一个 Status: Not Started 的系统；据此动态生成只包含真正可能的下一步选项：`[_] 对另一个 GDD 运行 /design-review — [system name] is still [In Review / NEEDS REVISION]`（还有待评审 GDD 时）、`[_] 运行 /consistency-check — 校验本 GDD 的值不与既有 GDD 冲突`（存在 ≥1 个其他 GDD 时总是包含）、`[_] 运行 /review-all-gdds — 跨全部已设计系统的整体设计理论评审`（≥2 个 GDD 时）、`[_] 运行 /design-system [next-system] — 设计顺序中的下一个`（总是包含，写出实际系统名）、`[_] Stop here`；只给被包含的选项按 A、B、C… 编号，并把最推进流水线的选项标为 `(recommended)`。
40. 协作与 guided 模式下，文件写入后绝不以纯文本结束，必须给出最终收尾组件；autonomous 模式下打印下一步并用 `log_decision` 记录。

适用边界 · 注意事项

• 不适用于对逐字节未变文档的重复评审（应复用旧结论或先修订文档），也不要用只覆盖改动章节的 delta/部分式重评审——实测缺陷命中率大幅下降且成本可能更高。
• 不适用于目标文档缺失/不可读/为空，或其所依赖文档缺失导致评审标准无法适用的情况——此时应返回 NOT ASSESSED 并指出缺失项与产出该文档的技能，而不是给出 APPROVED。
• 不替代跨全部系统的整体设计评审（/review-all-gdds）或数值一致性检查（/consistency-check）；lean/solo 模式下也拿不到各领域专家的对抗式发现。