为什么这么设计¶

GodotMaker 是有自己主张的工具。这篇文章解释这些主张背后的理由，让你理解其中的权衡，自己判断这个工具是否适合你的情况。

为什么是 9 条命令，而不是一键完成¶

最直接的替代方案是一条命令：描述你的游戏，去干别的，回来就是一个做好的项目。听起来很诱人，但实际上会碰到几个根本性的问题。

上下文窗口是有限的。 AI 会话有一个最大"工作内存"容量。一个完整的游戏——设计、代码、测试、截图、评审意见——轻轻松松就能超出这个上限。上下文满了之后，AI 开始丢掉早先的信息，导致漂移：后面的决策和早先的矛盾，早先的需求被遗忘。

长会话会积累假设。 早期做的每个决定，都隐性地影响后续所有决定。在一次漫长的运行里，早期的错误会被烘焙进后面的所有东西。拆成独立的命令，就让每一步都能从零出发，只带它真正需要的文档。

你始终在回路里。 每条命令之间，你可以查看产出、问问题、编辑文档、调整方向。一个跑偏的 /gm-gdd 可以在构建开始前就纠正，而不是等 40 分钟代码生成完才发现问题。

每个角色有自己的权限边界。 评估者不能碰游戏代码，构建步骤不能声称已获批准。这些约束只有在每个角色都是独立会话、拥有各自的允许操作集时才能成立。

为什么用 hook，而不是相信 AI¶

Hook 是一些小型 Python 脚本，Claude Code 会在特定事件时自动运行它们——文件即将被写入、会话即将结束、会话正在启动。它们强制执行 AI 无法绕过的规则，哪怕 AI 本来没有恶意。

替代方案——依赖 prompt 里的指令——并不可靠。会话足够长，情况足够复杂，即使一个出发点良好的 AI 也会偏离指令。告诉 AI "评估时不要写游戏代码"，远远弱于用一个脚本把写操作物理阻断并返回报错。

Hook 还很容易审计。你可以打开 hooks/check_file_permissions.py，直接读到什么被允许、什么不被允许——50 行简单直白的 Python，没有任何歧义，不存在"AI 说它会这么做"的问题。规则写在代码里。

Hook 强制执行的一些关键规则：

在评估者角色里不能写游戏代码。
没有完成 /gm-gdd 就不能开始 /gm-build。
自上次构建以来没有运行过 /gm-evaluate 就不能开始 /gm-fixgap。
Worker 运行了但 Verifier 和 Reviewer 还没跑，/gm-build 会话就不能结束。
太短或缺少必填章节的 Worker 报告会被直接拒绝。

这些规则的存在，是因为经验表明 AI 在压力下有时会走捷径——在没跑测试的情况下宣布成功，在上下文快满的时候跳过 Reviewer，交一份一行的报告。Hook 会把这些情况全部拦住。

为什么 `/gm-build` 里要用子 Agent¶

/gm-build 不直接写代码，而是派遣 Worker（执行者）——每个 Worker 专注地实现一个游戏系统，完成后汇报。这个设计有三个好处。

并行工作。 处理不重叠文件的 Worker 可以同时运行，分别在独立的 git worktree（可以理解为共享同一个仓库的独立工作目录）里工作。并行构建 MovementSystem 和 HealthSystem 大约只需要顺序执行一半的时间，而且每个系统有自己的文件，根本不会冲突。

每个 Worker 的视野很窄。 每个 Worker 只看到自己的任务简报和需要的文件，不会有完整的 PLAN.md 或几周的构建历史在它的上下文里。这让每个 Worker 的会话保持短小、专注、不容易漂移。

专项评审。 Worker 完成一批任务后，Verifier（验证者）运行构建和测试（机械正确性），然后 Reviewer（评审者）针对领域特有的陷阱进行检查——Godot 的物理约束、UI 布局规则、动画注意事项。这些是独立的 Agent，拥有各自专门调校过的 prompt。让一个 Agent 同时扮演三个角色，每个角色都会做得更差。

完成检查 hook 强制执行完整的循环。只有 Worker 跑完是不够的——Verifier 和 Reviewer 也必须跑，否则构建会话无法结束。

为什么专门选 ECS¶

核心原因是可预期性。当 AI 写的代码遵循 ECS 约定，每个系统都在 src/systems/，每个组件都在 src/components/，每个系统读取一组确定的组件。评审者检查物理代码时，知道去哪里找。Worker 添加新功能时，知道要遵循哪个模式。

ECS 也天然适合专项评审。GodotMaker 有八种评审者类型：物理、动画、UI、瓦片地图、导航、着色器、音频、粒子。每种评审者都了解自己领域的约定和常见错误。ECS 结构让 PhysicsSystem 路由到物理评审者、UISystem 路由到 UI 评审者变得很简单，它们不需要先理解整个代码库。

关于 ECS 以及它在生成项目里的呈现方式，参见 ecs-in-plain-english.md。

我们刻意不做的事¶

没有隐藏的后台循环。 GodotMaker 在你离开的时候什么都不会运行。没有任何构建、测试或提交在后台悄悄进行。每一步都在你输入命令时开始，命令完成后停下。你随时都清楚项目处于哪个阶段。

没有自动推进。 /gm-build 结束不会自动触发 /gm-verify，下一条命令由你来输入。这是刻意为之——让你在继续之前有机会看看刚生成了什么。

不能跳过接受确认。 /gm-finalize 需要 /gm-accept 记录的接受决定。评估者通过还不够——你这个人类还是要亲自确认。你的游戏，你说了算。