写出好用的AI提示词

写在最前

上一节课你做完了一件不写代码的活儿：把"完整弹珠肉鸽"切成一刀能验收的 MVP。这一节课要解决的就是这件事：怎么让 AI 每次对话都"记得/熟悉"你的项目。

💡 为什么单独拿一节课讲这个？ 因为这是"vibe coding"和"工程化用 AI"的分水岭。Vibe coding（Andrej Karpathy 2025 年 2 月在 X 上提出的词）是"凭感觉聊几句让 AI 写代码"，做小 demo 很爽；但一旦工程到 1k 行以上，AI 开始忘事、改坏旧逻辑、给变量乱起名——核心原因是它没有持久上下文。"圣经"就是你给 AI 造的外置记忆。"对话会消失，文件才是 AI 团队的记忆"。

一、先讲清楚"游戏圣经"是什么，不是什么

"圣经"（Bible）这个词在游戏行业有它的固定含义。新手很容易把它和 GDD（Game Design Document）混着用，但它们指向的东西不一样：

文档	它在回答什么问题	谁会读	长什么样
GDD （设计文档）	"这个游戏整体怎么设计？"	设计师 / 制作人 / 投资人	完整长文档，含市场定位、玩法体验、剧情、商业模式
Game Bible （游戏圣经）	"这个项目架构是怎样的，游戏世界里什么是不能违反的？"	团队所有人（程序、美术、写手、AI）	碎片化、可索引，像一本 wiki，每条都是"事实声明"

📚 业界共识参考：暴雪首席编剧 Christie Golden 在多次 GDC 公开演讲里把 Bible 描述成"the source of truth for everyone touching the IP"——"任何接触 IP 的人都从这里取真值"。Riot Games 的 Lore Bible 长达数百页，但每条 entry 都是独立可检索的小段落，不是一篇连续散文。

对小型独立游戏，这套思路要瘦身但不能丢。对 AI 来说，Bible 的关键属性是三个：

可索引：AI 不需要每次读全本，按需取一两段。
声明式：写"是什么"、不写"怎么实现"。例子 ✅"球击中钉子，钉子消失，得 10 分"；❌"在 _on_body_entered 里调用 queue_free() 然后 score += 10"——后者是代码，不是 Bible。
可追溯：每条事实有出处（设计决策的日期 / 版本号），改了能查到。

⚠️ 新手最常踩的坑：把 Bible 写成"自然语言版本的代码注释"。一旦你开始在 Bible 里写函数名和变量名，它就变成了第二份会过期的代码——AI 改完代码忘记同步，Bible 立刻失真。Bible 只描述世界规则，不描述实现细节。

📌 游戏引擎例外：上面说的"不写函数名和变量名"，有一个有价值的例外——引擎类型本身。写"发射器是 Area2D，碰撞形状是 CircleShape2D（半径 20px）"是可以的，因为这是 Godot 4 的技术事实，不会因为你改业务逻辑而过期。真正要避免的是"在 _on_body_entered 里调用 queue_free()"这类和实现绑定的细节。

判断标准：这条信息如果业务逻辑变了，它还成立吗？成立就能写，不成立就不写。

二、为什么 AI 写复杂工程必须有 Bible

新手在 AI 里跑一个原型很快，但一到第 3、第 4 个功能就开始翻车。常见症状你大概率已经见过：

你让 AI 加"全屏弹"道具，它顺手把发射器的逻辑改了，破坏了你 03 课定下的"按住左键持续发射"。
上次会话里 AI 说"分数上限 9999"，这次会话它说"分数无上限"。是因为 AI 没有跨会话记忆。

三、模块化 Bible：怎么切，AI 才不会读得吐血

新手写 Bible 第一反应是"写一个长 md 文档"，10 屏滚下去。这是错的——不是因为长不好，是因为 AI 每次都得读全文，token 花得快、命中率低，还容易在文档内部产生冲突。

正确做法是按"耦合边界"切文件。一个模块改了，只有它的文件被读 / 被写，别的纹丝不动。例如：弹珠肉鸽的 Bible 文件分层

💡 为什么用数字前缀？ 不是强迫症，是为了让 AI 一眼看到读取顺序。04 放物理还是经济，取决于你的游戏——弹珠类游戏的"物理手感"是核心可调参数，所以单独成文；数值经济同样重要但可以合并进 03_rules.md 的"可调数值清单"，不必单独一个文件。按耦合边界切，而不是套模板。

每个文件的"骨架模板"

为了让 AI 快速定位，每个文件都用同一个骨架。以 02_entities.md 为例：

                      02_entities.md · 骨架模板
                      
                    
# 02 · Entities（实体）
      > 状态：MVP / 最后更新：2026-06-12 / 关联决策：DEC-008

      ## 球（Ball）
      - 是什么：玩家发射的物理实体，受重力和碰撞影响。
      - 数量上限：单局 n 颗（来自 03_rules.md#球数）。
      - 关键属性：质量、弹性、半径、初速度——具体数值在 03_rules.md。
      - 能与什么交互：钉子（消失+得分）、边框（反弹）、
        地板（消失，不计分）。
      - 不能做什么：不能穿墙、不能与其他球碰撞（已在 DEC-003 拍板）。

      ## 钉子（Peg） …
      ## 发射器（Launcher） …

注意三件事：

"是什么"在最前。
数值不写死，写"在哪个文件里"，避免两处写两遍出现矛盾。
"不能做什么"显式列，要不 AI 最容易加它没被禁止但你也不想要的能力。

另一方案：轻量 Bible 架构（SPEC / MODULES / EXPERIENCE）

如果你的项目体量比较小——比如一个 Game Jam 作品、一个原型 Demo、或者一个一两周就能跑通玩法的小品级项目——上一节的"模块化 Bible"可能反而显得过重：文档拆得越细，维护它本身就越费时间，AI 一次能读进上下文的也就那么多页。

这里给一个更轻的备选架构。核心思路只有一句话：

Bible 不是大而全的文档库，它服务于 AI 的稳定执行。 它存在的唯一目的，是让 AI 每次接到任务时，都能用最短的上下文复现"上次为什么这么做、这次不要再踩什么坑"。

所以一份合格的轻量 Bible，只需要写清楚五件事：

目标：这个项目/这个模块要解决什么问题，成功的样子是什么。
规则：哪些是硬约束、不可违背的设计原则（数值上限、操作手感、美术基调…）。
边界：哪些事情不做、哪些方案已经被否决过、为什么。
决策：关键的设计选择和它的理由（一句话即可，重在留痕）。
测试结果：跑过的验证、玩家/自测反馈、AI 实现后的实际表现。

围绕这五件事，可以用三份文档承载，简称 SPEC / MODULES / EXPERIENCE：

1. SPEC.md ——「规格约束」

回答：这个游戏是什么、不是什么。写给 AI 看的硬性规格：玩法定义、核心循环、关键数值范围、平台与性能预算、必须遵守的禁区。一切"AI 不能擅自改"的东西都放在这里。

建议字段：

One-liner（一句话说清楚游戏是什么）
核心循环（30~60 秒的玩家行为闭环）
关键参数 / 数值边界（带上限和下限，给 AI 留出可调区间）
明确不做的事（Non-goals）

2. MODULES.md ——「系统分工」

回答：项目里有哪些模块，它们各自负责什么、如何对外暴露能力。这是 AI 落代码时最需要的一张图。每个模块只要回答三件事就够：

字段	说明
职责	这个模块只做什么，一句话
输入 / 输出	接收什么数据、对外提供什么接口或事件
依赖	调用了哪些其他模块，不调用哪些（避免循环依赖）

模块之间的协作关系，能用一张简单的依赖图或者 mermaid 流程图说明就够了，不要写成架构白皮书。

3. EXPERIENCE.md ——「体验目标」

回答：玩家应该感觉到什么，以及我们怎么知道做到了。这一份是给"调味道"用的，也是 AI 最容易跑偏的地方。建议包含：

核心体验关键词（3~5 个形容词，例如「紧张 / 干脆 / 微荒诞」）
关键时刻（First 30s、Boss 战、失败回合的情绪曲线）
反例 / 已经否决的体验方向（明确告诉 AI"不要做成 XX 那样"）
测试记录：每次玩测/自测后回填一两句结论，作为下一轮迭代的输入

怎么用：一个最小工作流

立项时，先把 SPEC.md 一句话版本写出来，在 5 行内说清楚，是项目能不能跑通的第一道闸。
开始做模块时再补 MODULES.md，每加一个模块补一段，不预先写空模块。
每次玩测/AI 产出后，把"新决策"和"新边界"回灌到对应文档——Bible 是越用越厚，不是一次性写完的。
给 AI 下任务时，按需挑选：调玩法 → 带 SPEC + EXPERIENCE；写代码 → 带 SPEC + MODULES；做调优 → 带 EXPERIENCE + 最近一次测试记录。

什么时候该升级回"模块化 Bible"

当出现下面任一信号时，就说明轻量架构开始扛不住了，建议升级到上一节的完整模块化 Bible：

模块数超过 ~8 个，或者 MODULES.md 已经超过两屏。
团队里出现第二位开发者，需要并行修改不同模块。
同一个文件里开始出现互相冲突的规则（说明该拆分了）。
AI 频繁"忘记"上一次的决策，说明信息密度已经超过单文档能承载的上下文。

简而言之：小项目用 SPEC / MODULES / EXPERIENCE 起步，跑到觉得"挤"的那一刻，再升级。

四、_index.md：让 AI 学会"按需读"

这是整个系统的关键文件，长这样：

_index.md 不变量清单 — 图 3 · _index.md"不变量"清单

五、提示词技巧：让 AI 在每次对话开头先读 Bible

写好 Bible，下一步是让 AI 真的读它。新手最常见的错误是在对话里贴一大段 Bible 原文——又长又乱，token 消耗大。更好的做法是用一段固定的"上下文前置语"（Context Prelude），每次新会话开头粘进去：

Prompt · 上下文前置语（Context Prelude）

你正在协助开发一个 2D 弹珠肉鸽 Godot 4 项目。
      项目的 Bible 目录在：docs/bible/（或你实际放的路径）

      开始任务时：
      1. 先读 docs/bible/_index.md，理解不变量清单和模块速查表。
      2. 根据我接下来描述的任务，匹配速查表，只读相关的 1–2 个模块文件。
      3. 如果任务跨越 3 个以上模块，先停下来跟我确认范围，不要直接动手。
      4. 任何改动若可能违反不变量清单，直接拒绝并说明原因。
      5. 输出代码时，遵循 docs/bible/08_naming.md 的命名约定，
         参数用 @export 暴露。

      任务：
      {在这里写本次要做的事}

三次对话法

即便有 Bible，AI 第一次产出仍然可能跑偏（尤其是涉及多模块的任务）。新手常犯的错是直接重写 prompt 再试一次——但你扔掉的也包括 AI 已经读到的对的部分。正确做法是"三次对话法"：

轮次	你的输入	AI 的产出	你的动作
第 1 轮	上下文前置语 + 任务	完整方案 / 代码	不接受，先看哪里和 Bible 冲突
第 2 轮	"停下，先告诉我你认为这个任务涉及哪几个模块、哪条不变量"	AI 自陈理解	校对它的理解，纠正错的部分
第 3 轮	"理解正确，按你刚才说的方案实施"	修正后的代码	这一份才是要落地的

第 2 轮是关键：它强制 AI 把"理解"和"实现"分离。

🎯 一定要让 AI 解释一遍它要做什么，比让你解释一遍它该做什么，便宜得多。前者是它的工作，后者是你的时间。

六、让 AI 自动维护 Bible：写一份"回写指令"

到这里你可能在担心：Bible 写完了，谁来更新它？你不会更新——你忙着写代码。AI 也不会自己更新——除非你让它做。把这件事固化成一段 prompt，存成 prompts/update_bible.md：

Prompt · update_bible.md（回写指令）

你刚刚完成了一项功能改动。在我接受合并之前，请按以下流程同步 Bible：

      1. 列出本次改动实际触及的模块（与最初规划比较，是否有偏差？）。
      2. 对每个被触及的模块文件：
         - 找出"事实层面"发生变化的条目（新增 / 修改 / 删除）。
         - 用 diff 风格的 markdown 给我看修改前后。
         - 不要重写整个文件，只动需要动的段落。
      3. 在 99_decisions.md 末尾追加一条决策记录，包含：
         - 决策编号（递增，格式"决策 #N"或"DEC-N"，保持全项目一致）
         - 日期
         - 决策内容（一句话）
         - 理由（为什么需要做这个决定）
         - 影响（对哪些文件/模块产生了影响）
      4. 如果本次改动引入了新的变量名、节点名或信号名，
         检查是否符合 08_naming.md。如有冲突，停止流程并告诉我，
         不要悄悄修改命名约定。
      5. 如果本次改动违反了任何"不变量"，停止流程并告诉我，
         不要悄悄修改不变量。
      6. 输出更新后的 _index.md（如果有新模块或速查表需要补行）。

      不要修改代码本身，本步骤只更新 Bible。
      等我确认 Bible 更新无误后再继续。

每次让 AI 完成一个 P0/P1 功能后，第二条消息就是这个 prompt。这把"代码改动"和"文档同步"做成了强制的两步流水线——AI 跳过任一步，你都看得见。

💡 关于"不变量保护"那一条：这是从软件工程里契约式编程（Design by Contract，Bertrand Meyer 提出）搬过来的思路——不变量（invariant）是任何状态变化都不能破坏的属性。把它显式写进 Bible，AI 改代码时就能用它做自我审查。这一招在 Cursor 用户社区里被反复推荐，关键词搜 "invariants in cursorrules" 能看到一堆讨论。

关于实际使用 bible 和回写的演示，会在后续教程中的具体场景里展示。

附：目录结构与关键模板

                      目录结构 · docs/bible/
                      
                    
YourProject/
      └── docs/bible/          # 也可放在项目根目录 bible/，路径全项目一致即可
          ├── _index.md              # 索引：速查表 + 不变量清单
          ├── 00_world.md            # 世界观 / 主题 / 美术调性（白盒阶段也要写）
          ├── 01_core_loop.md        # 核心循环
          ├── 02_entities.md         # 实体定义
          ├── 03_rules.md            # 规则（胜负判定、数值边界）
          ├── 04_physics.md          # 物理参数（弹性、冲量、场景尺寸）
          ├── 05_ui_hud.md           # UI / HUD 描述
          ├── 06_audio.md            # 音效分层（总线、事件名清单）
          ├── 07_file_layout.md      # 工程目录结构与放置约定
          └── 99_decisions.md        # 决策日志（仅追加）

_index.md 参考内容：

_index.md · 参考内容

# Bible Index
      > 每次开始新对话前，先读这个文件；
      > 按任务匹配后只读对应的 1–2 个模块文件。

      ## 任何修改都不能违反（不变量）
      1. 核心循环必须保留：瞄准 → 蓄力 → 发射 → 看球弹 → 球落底部
         → 资源变化 → 想再来一发。
      2. 所有可调数值必须集中：核心数字永远在 03_rules.md 和 data 目录的
         配置文件，禁止散落在脚本硬编码。
      3. 音效调用统一走 AudioManager：禁止在游戏脚本里直接操作
         AudioStreamPlayer。
      4. 命名遵循 08_naming.md：AI 新增变量/节点/信号时必须先查命名约定，
         不得自造格式。

      ## 速查表：你要改什么，读哪个文件
      | 你要改什么           | 读哪个文件                  | 一句话提示 |
      | 加新实体（道具、敌人）| 02_entities.md, 08_naming.md | 必须先看命名约定 |
      | 调数值（资源、参数）  | 03_rules.md                | 数字改动同步写入配置文件 |
      | 调物理手感           | 04_physics.md              | 数值见 data/balance_config.json |
      | 改 UI / HUD 显示     | 05_ui_hud.md               | 只讨论"显示什么"，不讨论坐标 |
      | 改音效 / 加音效事件   | 06_audio.md                | 事件名改动同步 data/audio_config.json |
      | 加新脚本 / 调目录     | 07_file_layout.md, 08_naming.md | 改完同步更新本索引 |
      | 任何命名问题         | 08_naming.md               | 节点/变量/信号/枚举的命名规则 |
      | 决定一件大事         | 99_decisions.md（追加）     | 格式：决策 #N / 日期 / 内容 / 理由 / 影响 |