在使用此工作流之前，请阅读 .codex/docs/codex-runtime.md。遵循当前的用户授权和主机权限。
参数： [path-to-design-doc] [--review full|lean|solo]
在继续之前，从项目根目录执行此配置命令：
bash ".codex/hooks/yaml-helper.sh" resolve_config --keys review_mode,automation,workflow,system_overrides
使用上述命令进行解析——按原样使用；--review 会覆盖 review_mode。--depth 是 1.1 版本之前的同一标志名称：将 --depth <mode> 视为与 --review <mode> 完全相同，并说明一次该标志已被重命名。如果二者都存在，--review 优先，--depth 被忽略——说明这一点。无阻塞 → 默认值参见 .codex/docs/config-resolution.md。
设计评审 是做什么的？
阶段 0：解析参数
完整的检查模式参见 .codex/docs/director-gates.md。各个门定义位于 .codex/docs/director-gates/[gate-id].md —— 生成的代理读取自己的门文件；不要在父会话中读取它。
每次 request_user_input 调用都遵循 .codex/docs/automation-modes.md（协作模式始终询问 · 引导模式仅针对重大事项询问 · 自主模式记录并继续；automation_always_ask 类别始终提示）。
workflow 针对被评审的 GDD——如果阻塞列表中有 <system>，则使用 system_overrides 行中的值，否则使用项目值。验证范围遵循层级：
full—— 所有 8 个部分都经过验证；缺少任何部分都会阻止批准。standard—— 5 个必需部分（概述、详细规则、边缘情况、依赖关系、验收标准）如果缺失则阻止；当系统定义数值规则（比率、曲线、阈值、成本——类别是提示，而不是测试）时，公式部分同样会阻止；玩家幻想和调优旋钮是建议性的（发出警告，绝不阻止），除非workflow_overrides要求它们。minimal—— 不期望有 GDD；如果存在，则建议性地验证 5 个标准部分。
已解析的模式控制本次评审的详细程度：
full：完整评审——所有阶段 + 专家代理委托（阶段 3b）lean：所有阶段，无专家代理——更快，单会话分析solo：仅阶段 1-4，无委托，无阶段 5 下一步提示——当从另一个技能内调用时使用
阶段 1：加载文档
首先进行新鲜度检查——对未更改的文档进行重新评审会花费全部成本并得出相同的结论。 运行：
Bash: bash .codex/scripts/review-receipts.sh check "design/gdd/reviews/[doc-name]-review-log.md" "[target-doc-path]" "design/registry/entities.yaml" ".agents/skills/design-review/SKILL.md"
注册表包含在检查中，因为本次评审会查阅它以获取跨文档事实——一个未更改的 GDD 针对更改过的注册表进行评审可能会得出不同的结论，因此只有当每行都输出 UNCHANGED 时，跳过才是安全的（从未存在过的注册表不会出现在输出中，也不会阻止跳过）。此技能的文件包含在其中，因为更改后的技能会以不同方式进行评审。检查还会比较日志中记录的所有其他文件——相关 GDD、概念或简报以及早期评审中读取的叙事文件——并打印出不再存在的文件的 GONE:。
然后读取最新条目的 Review mode: 行。只有当该评审的模式与当前解析的模式相同或更深（full > lean > solo）并且其工作流相同或更深（full > standard > minimal）时，该评审才涵盖本次运行。没有该行的条目是在该行存在之前编写的，并且不涵盖任何内容。
- 全部为
UNCHANGED并且日志的最新条目带有结论——将其展示出来： "此文档与其上次评审 ([日期]) ([模式] 评审，结论：[结论]) 时的字节相同。" 如果该结论为 APPROVED 并且该评审涵盖本次运行，则通过request_user_input提供：[A] 采用之前的结论（推荐）/[B] 无论如何重新评审——guided模式采用 [A] 并记录；autonomous模式通过log_decision记录并使用之前的结论。如果结论为 APPROVED 但当前要求的评审比记录的评审更深入，则说明—— "那是 [模式] 评审，工作流层级 [层级]；本次运行要求 [模式] 评审，层级 [层级]。" —— 并提供[A] 以 [模式] 重新评审（推荐）/[B] 采用之前的 [模式] 结论；guided和autonomous模式都会重新评审（autonomous模式通过log_decision记录）。如果结论为 NEEDS REVISION 或 MAJOR REVISION NEEDED，则直接说明：自文档评审失败以来，它没有变化——之前的发现仍然有效；下一步是修改文档，而不是重新评审。提供显示日志中之前发现的选项。 - 目标文档和此技能文件为
UNCHANGED，并且只有注册表或另一个已记录跨文档文件为CHANGED、NEW或GONE—— 之前的结论仍然有效，但跨文档事实除外：根据更改后的文件重新验证文档的值并重新发布结论；如果出现冲突或该评审不涵盖本次运行，则升级为完整的重新评审。 - 目标文档或此技能文件为
CHANGED或NEW，或RECEIPT： NONE—— 执行下面的完整评审。不要提供跳过读取或重新分析未更改部分的局部/差异重新评审。 部分范围的重新评审会遗漏完整评审发现的缺陷，而且几乎节省不了什么时间。“自上次评审以来未更改”仅意味着与当时评审的内容字节相同——这并不能说明之前的评审本身是否完整，而且即使指示无论如何都要扫描所有内容，注意力也会集中在标记的更改上。
完整阅读目标设计文档。此步骤需要整个 GDD：根据其标题（使用 Grep 工具：模式 ^#，内容模式）按范围读取，因为大于 40 KB 的整文件读取会被拒绝。阅读 AGENTS.md 以了解项目上下文和标准。
对于跨文档事实，优先使用注册表，而不是同级 GDD。 如果 design/registry/entities.yaml 存在并且列出了此系统的条目，则对其进行 grep——这些是此 GDD 不得与之矛盾的既定事实，它们取代了为重新发现它们而读取同级 GDD 的需要：
Grep pattern="source: design/gdd/[system].md" path="design/registry/entities.yaml" output_mode="content" -A 6
Grep pattern="design/gdd/[system].md" path="design/registry/entities.yaml" output_mode="content" -B 8
第一个命令找到此系统拥有的条目——-A 6 上下文包含它们的 referenced_by: 块。第二个命令找到引用此系统的条目——referenced_by: 是一个块序列（键及其路径在不同的行上），因此使用 -B 8 上下文匹配路径以查看拥有条目，而不是一个 referenced_by.*name 单行（后者永远不会匹配块形式）。
如果 design/registry/entities.yaml 不存在，或者没有列出此系统的任何条目 —— 该文件作为空存根提供，因此这是默认情况，直到 $design-system 填充它 —— 回退到读取目标文档在其“依赖关系”部分中命名的相关 GDD。将读取范围限定为这些 GDD，而不是所有“隐含”的内容。不要通过通配符读取所有 design/gdd/ 内容。
依赖关系图验证： 对于“依赖关系”部分中列出的每个系统，使用 Glob 检查其 GDD 文件是否存在于 design/gdd/ 中。标记任何尚不存在的文件——这些是下游作者将遇到的断开引用。
传说/叙事对齐： 如果 design/gdd/game-concept.md（或者，在 rigor： minimal 级别下，是单页简报 design/game-brief.md）或 design/narrative/ 中的任何文件存在，则读取它们。注意此 GDD 中任何与既定世界规则、基调或设计支柱相矛盾的设计选择。在阶段 3b 中将此上下文传递给 game-designer。
先前评审检查： 检查 design/gdd/reviews/[doc-name]-review-log.md 是否存在。如果存在，读取最近的条目——记下给出了什么结论以及列出了哪些阻塞项。本次会话是一次重新评审；跟踪先前的项目是否已处理。
阶段 2：完成度检查
步骤 2a —— 确定性地收集部分存在性（无需读取文档）：
Bash: bash .codex/scripts/gdd-structure-check.sh [target-doc-path]
它打印一个 PRESENT： 列表，并在适用时打印一个 ABSENT： 列表和一个 PLACEHOLDER： 列表（仅包含 [待设计] 的现有部分：尚未编写，因此将其视为缺失以进行清单检查）。它仅报告存在性，不进行 REQUIRED/ADVISORY 判断——这是步骤 2b 的工作。它已经接受 ## Detailed Design 作为满足 Detailed Rules 要求，因此不要将其标记为缺失。
步骤 2b —— 应用层级。 使用步骤 2a 的列表，根据下面的设计文档标准清单进行评估。根据已解析的工作流层级（阶段 0）将每个部分标记为 REQUIRED 或 ADVISORY。 缺失的 REQUIRED 部分会阻止批准；缺失的 ADVISORY 部分会作为建议提出，但不会阻止。
如果一个部分报告为 PRESENT，但只是空标题，则仍可能评审失败——对结论实际依据的任何部分进行抽查阅读。
- 有“概述”部分（一段摘要）——所有层级均为 REQUIRED
- 有“玩家幻想”部分（预期体验）——
full层级为 REQUIRED；standard层级为 ADVISORY - 有“详细规则”部分（明确的机制）——
full/standard层级为 REQUIRED。GDD 模板将此部分标题命名为## Detailed Design（它包含核心规则/状态/交互子标题）；接受任一标题作为满足此要求——不要将“详细规则”标记为缺失，即使存在## Detailed Design部分。 - 有“公式”部分（所有数学定义均带有变量）——
full层级为 REQUIRED；在standard层级下，只要系统定义了数值规则（比率、曲线、阈值、成本、伤害、掉落权重）即为 REQUIRED，否则为 ADVISORY。系统的Category是一个提示，不是测试——不要仅凭类别标记就清除此项 - 有“边缘情况”部分（处理异常情况）——
full/standard层级为 REQUIRED - 有“依赖关系”部分（列出其他系统）——
full/standard层级为 REQUIRED - 有“调优旋钮”部分（识别可配置的值）——
full层级为 REQUIRED；standard层级下为 ADVISORY，除非workflow_overrides.tuning_knobs要求 - 有“验收标准”部分（可测试的成功条件）——
full/standard层级为 REQUIRED
阶段 3：一致性和可实施性
内部一致性：
- 公式产生的值是否与描述的行为相符？
- 边缘情况是否与主要规则相矛盾？
- 依赖关系是否是双向的（另一个系统是否知道这个系统）？
可实施性：
- 规则是否足够精确，以便程序员无需猜测即可实施？
- 是否存在细节缺失的“模糊”部分？
- 是否考虑了性能影响？
- 每个验收标准是否都可以独立测试？标记每个不可独立测试的验收标准，引用其内容——“感觉平衡”、“工作正常”、“性能良好”不是标准——并提供可衡量的改写。在
full模式下，qa-lead也会检查它们（阶段 3b）；在lean和solo模式下，没有专家运行，因此此主评审检查是唯一的检查。
跨系统一致性：
- 这是否与任何现有机制冲突？
- 这是否会与其他系统产生意外的交互？
- 这是否与游戏既定的基调和支柱一致？
注册表值，无论 GDD 在哪里声明它们。 值在表格、分类条目或变体说明中重新陈述，与在详细规则中一样肯定地与注册表相矛盾，并且按部分阅读使得这些正文易于浏览。列出注册表的条目名称 (grep -E '^ - name：' design/registry/entities.yaml)，然后在整个目标文档中搜索所有它们以及它们携带的数值键一次，不区分大小写，将每个 _ 写为 [_ ]，以便 goblin_scout 也能匹配“Goblin scouts”：
grep -n -i -E 'goblin[_ ]scout|iron[_ ]sword|health|value[_ ]gold' [target-doc-path]
对照注册表检查它打印的每一行，无论它位于哪个部分。为条目提供不同值的行，即使只是一个房间、变体、等级或例外，也与拥有的 GDD 相矛盾：将其列在“实施前所需”下，并附上其行号、本文档中的值和注册表中的值。如果没有注册表条目，则运行相同的搜索，搜索相关 GDD 定义的实体和值。
阶段 3b：对抗性专家评审（仅限 full 模式）
在 lean 或 solo 模式下跳过此阶段。
此阶段在 full 模式下是 MANDATORY 的。 不要跳过它。
在生成任何代理之前，打印此通知：
“完整评审：并行生成专家代理。这通常需要 8-15 分钟。使用
--review lean以获得更快的单会话分析。”
步骤 1 —— 识别 GDD 涉及的所有领域
使用阶段 1 中已加载的 GDD —— 不要重新读取它 —— 识别存在的每个领域。一个 GDD 可以同时涉及多个领域——要彻底。常见信号：
| 如果 GDD 包含... | 生成这些代理 |
|---|---|
| 成本、价格、掉落、奖励、经济 | economy-designer |
| 战斗属性、伤害、生命值、DPS | game-designer、systems-designer |
| AI 行为、寻路、目标选择 | ai-programmer |
| 关卡布局、生成、波次结构 | level-designer |
| 玩家进度、经验值、解锁 | economy-designer、game-designer |
| 用户界面、HUD、菜单、面向玩家的显示 | ux-designer、ui-programmer |
| 对话、任务、故事、传说 | narrative-director |
| 动画、手感、时机、反馈 | gameplay-programmer |
| 多人游戏、同步、复制 | network-programmer |
| 音频提示、音乐触发 | audio-director |
| 性能、绘制调用、内存 | performance-analyst |
| 引擎特定模式或 API | 主要引擎专家（<engine>-specialist，来自 engine.name — Godot→godot-specialist，Unity→unity-specialist，Unreal→unreal-specialist；回退到 ## Engine Specialists 中的主要行 |
…
[因翻译截断]