项目结构¶

GodotMaker 运行完成后，你的游戏文件夹里会有很多文件。大部分由工作流维护，你不需要动它们。这页内容解释每个文件夹和文件是干什么的——让你知道想看某样东西时去哪找，也知道哪些不该乱碰。

my-game/
├── project.godot
├── src/
├── scenes/
├── addons/
├── assets/
├── GDD.md
├── PLAN.md
├── STRUCTURE.md
├── SCENES.md
├── ASSETS.md
├── TOC.md
├── MEMORY.md
├── test/
├── e2e/
├── CLAUDE.md
├── .claude/
├── .godotmaker/
├── .git/
└── .gitignore

游戏本体在哪里¶

这些文件夹里放的是 Godot 实际运行的游戏内容。

project.godot — Godot 项目文件。每个 Godot 项目都有一个；它记录了主场景、显示设置和启用的插件。你可以在 Godot 里打开它，或者在文件管理器里双击它启动编辑器。GodotMaker 会通过 /gm-scaffold 创建这个文件，之后按需更新。正常情况下不需要手动编辑。

src/ — 所有游戏代码。GodotMaker 采用一种叫 ECS（Entity-Component-System，下面有解释）的架构，代码分成两类文件：组件（存数据的小文件，比如 Health 值或者 Position）和系统（处理这些数据的逻辑，比如"把所有有 Position 的东西移动一下"）。AI 负责写和更新这里的所有内容。你可以随意阅读这些文件；自己改也没问题，但如果未来的任务涉及到同一个文件，AI 可能会覆盖你的修改。

scenes/ — Godot 场景文件（.tscn）。场景可以理解成一个"关卡"或者一个"界面"，描述屏幕上显示什么、怎么布局。AI 按照 SCENES.md 里的方案生成场景文件。你可以在 Godot 编辑器里打开查看。

addons/ — GodotMaker 依赖的三个 Godot 插件。gecs 是游戏代码所基于的 ECS 框架；gdUnit4 是单元测试框架（跑单个代码检查）；godot_e2e 是端到端测试框架（运行整个游戏并截图）。这些由 /gm-scaffold 安装，不要手动修改。

assets/ — 游戏用到的图片、音频和字体。GodotMaker 通过 /gm-asset 生成或检查美术素材。如果你想用自己的图替换某张生成的图，把你的文件放到对应的子文件夹里，再运行一次 asset 命令——工作流会检测到新文件并更新素材列表。

设计文档在哪里¶

这些 Markdown 文件是 AI 做决策前会读的"真相来源"。你可以随便读。有些可以自己改；每条说明里会注明改不改合适。

GDD.md（游戏设计文档）— 描述游戏是什么：目标、玩法机制、视觉风格、胜负条件。GodotMaker 会通过 /gm-gdd 协助从你的想法生成它。如果你想调整游戏方向，在下一轮 CLI 运行或手动 GDD 命令前完善这个文件或补充新想法。

PLAN.md — 任务清单。AI 在这里追踪每一个实现任务——做了什么、等待中的是什么、哪些失败了。你可以读它来了解进度。AI 会自动更新；不建议自己手动改。

STRUCTURE.md — 技术架构：存在哪些组件和系统，每个组件持有什么数据，每个系统做什么事。由 /gm-gdd 写成，并由 /gm-build 更新。读这个文件能最清楚地了解游戏代码是怎么组织的。

SCENES.md — 所有场景的说明：每个场景包含什么，其中的游戏对象如何对应到 ECS 实体。由 /gm-gdd 生成，工作流用它作为生成 .tscn 文件的蓝图。

ASSETS.md — 游戏所需全部素材的清单：逻辑名称、文件路径、生成时用的设置。由 /gm-asset 写成并更新。如果你添加了自己的美术文件，工作流会把它们加入这个清单。

TOC.md — 上面所有文档的目录，自动生成。不确定该看哪个文档时，用它快速索引。

MEMORY.md — AI 想在多次会话之间记住的东西：发现的规律、过去的错误、重要的决定。自动写入和更新。如果你想了解 AI 在某次早期会话里为什么做了某个选择，读这个文件很有用。

测试文件在哪里¶

GodotMaker 在生成游戏代码的同时也生成测试，方便尽早发现问题。

test/ — 单元测试。每个测试文件独立检查游戏代码的一小块（比如："移动系统在一帧内把实体移动了正确的距离吗？"）。由 /gm-verify 自动运行。你也可以用 Godot 的无头模式从命令行手动跑。

e2e/ — 端到端测试。这些测试运行完整的游戏，在"玩家体验"层面检查行为是否正确——球真的弹起来了吗？分数加了吗？该结束的时候结束了吗？/gm-evaluate 会编写或运行这些测试。e2e/screenshots/ 子文件夹保存测试运行时截下来的画面。

框架内部文件¶

这些隐藏文件夹完全由 GodotMaker 管理。除非有明确说明，否则不要修改里面的文件。

.claude/ — 存放项目本地的 Agent runtime 文件。这个目录包含 skills、agent 定义、模板、参考资料，以及 godotmaker.yaml 这类主机特定配置。这里的所有内容都由 publish.py 部署，重新发布时会刷新。

.godotmaker/ — 当前项目的运行时状态。关键文件：

version — 这里发布的 GodotMaker 是哪个版本，用来检测是否有可用升级。
current_role — 一个只有一个词的文件，记录当前正在执行哪个角色（build、evaluate 等）。钩子脚本读它来决定 Agent 在这个时刻能写哪些文件、不能写哪些。
stage.jsonl — 每个已完成角色的只追加日志，带时间戳。工作流靠这个知道你上次中断在哪里。
config.yaml — 每个项目的偏好设置，比如图片生成用哪个 AI 模型。你可以编辑这个文件来修改这些偏好。
hooks/ — 执行规则的 Python 钩子脚本（哪些文件可以写、必要输出是否都存在等）。自动管理。
evaluation.json 和 final_report.json — 分别是 /gm-evaluate 和 /gm-finalize 的输出。读它们可以了解 Agent 对当前构建的评估。
gaps/<n>/ — 每次 /gm-fixgap 运行后归档的 GAP.md 文件，留作参考。

版本控制¶

.git/ — Git 仓库。如果项目中还没有，/gm-scaffold 会创建它。工作流会记录改动，所以你始终有历史记录可以查看或回退。你可以用常规的 Git 命令（git log、git diff、git checkout）浏览或恢复早期状态。

.gitignore — 告诉 Git 哪些文件不需要追踪（大的二进制输出、临时状态、本地配置）。自动管理。

如果你只改一个文件¶

CLAUDE.md — 这个文件包含所选 Agent runtime 会读取的项目专属说明。如果你想让 Agent 始终遵守某个约定（比如固定用某套配色方案、永远不加音效、代码注释用特定语言），加到这里，以后会话都会生效。这是真正属于你来自定义的 runtime 指令文件。

其次值得多看看的是 GDD.md——它是描述游戏应该是什么样子的唯一来源。如果游戏偏离了你的想法，在下一轮运行前更新 GDD.md 或补充新想法，是正确的纠正方式。