让嗒啦啦永远记住你的项目：记忆文档 + Skill 全流程搭建指南
精华修改于03/10431 浏览开发心得
作者：浠涫
项目：节拍前夜 (Beat Eve) — Roguelike × 节奏 × 回合策略
引擎：TapTap Maker (UrhoX)
代码量：42,000+ 行 Lua / 81 个文件 / 35 篇文档
前言：为什么 AI 总是"失忆"？
用 AI 写游戏，最痛苦的不是它写不出代码，而是——每次新对话，它都不认识你的项目。
你花了多轮对话精心搭建的战斗系统，换个会话就忘了；你告诉它"我的节拍引擎是三状态判定"，下次它又给你写成"按钮 enabled/disabled"；你修了一个 backgroundImage 不继承父级 opacity 的 BUG，没过多久它又犯同样的错。
在节拍前夜开发到 1 周左右的时候，我终于受不了了。我开始建设"记忆文档"体系——让 AI 在每次对话开始时，先读完项目的"前世今生"，再动手写代码。
实践效果
- 重复 BUG 明显减少，从频繁出现降到接近 0
- 新功能开发速度大幅提升（不用每次重新解释架构）
- AI 能主动提醒"上次这么做出过问题"
本文将完整分享记忆文档搭建方法、Skill 配置规则、1 个月迭代踩坑经验，适用于所有长期与 AI 协作的开发项目。
第一章：记忆文档的核心思想
核心理念
把"项目经验"从人脑转移到文件，让 AI 每次开工前先"阅读简历"再上岗。
AI 模型存在上下文窗口限制，每次喂完整代码，即容易失忆，又容易浪费积分。但将核心信息浓缩至几千行文档，即可让 AI 快速"恢复记忆"。
文档体系构成
1. 项目记忆文档（主文档）
2. 专题子文档（按需加载）
3. DALALA(Claude划掉) Skill（自动化读写规则）
闭环工作流
开工前读文档（Skill 自动）→ 干活中写代码/修BUG → 收工后更新文档（Skill 自动）→ 下次开工继续读
第二章：三级文档架构
初期单一大文件易导致文档膨胀、token 消耗过高，最终优化为三级轻量化架构，兼顾信息完整性与读取效率：
Level 1：我的主记忆文档（必读，约 800 行）
- ch1 项目概况：一句话描述 + 技术栈
- ch2 文件结构：81 个文件的一行描述 + 行数
- ch3 核心规则：蓄力公式 / 克制矩阵 / 意图系统
- ch4 游戏流程：标题→地图→战斗→奖励→商店→事件→图鉴
Level 2：架构子文档（按需读取，约 900 行）
- ch5 架构模式：双引擎 Hook / 多流种子 RNG
- ch6 持久化层：云变量 + 本地存档 + F12 备份
- ch7 UI 系统：编辑覆盖层 / 材质编辑 / 主题
- ch8 节奏系统：V2 参数 / NanoVG 自定义 Widget
Level 3：规范子文档（按需读取，约 650 行）
- ch9 已知问题与 TODO
- ch10 开发规范
- ch11 开发历史：完整迭代记录
- ch12 未来路线图：R1-R9 优先级排列
关键设计决策
1. 主文档严格控制在 1000 行以内，超量拆分至子文档；
2. 文件结构索引为核心章节，单文件一行标注文件名+行数+功能，方便 AI 定位；
3. 精准记录核心数值规则，避免 AI 自行编造；
4. 主文档添加导航标记，关联子文档，AI 按需读取。
第三章：文档内容设计原则
经过大量试错，总结 5 条高效文档编写原则：
原则 1：写"是什么"，不写"怎么做"
AI 可自主读代码，无需复述代码逻辑，重点记录设计意图、数值规则、核心定义。
原则 2：记录"教训"，不只是"修复步骤"
不写单一修复操作，记录错误原因、规避方法、潜在风险，防止重复踩坑。
原则 3：用表格记录枚举型信息
克制矩阵、意图映射、屏幕关系等内容，表格形式更易被 AI 解析，清晰度翻倍。
原则 4：标注版本号 + 更新日期
文档顶部标明版本与时间，快速定位过时信息。
原则 5：文件名直观易懂
拒绝冗余命名，一眼识别文档用途，便于管理与调用。
第四章：我的14 个 Skill 详解
记忆文档解决信息存储问题，Claude Skill 实现自动化读写，覆盖开工→理解→设计→编码→验收全流程，共 14 个核心 Skill：
阶段 1：开工
Skill 1：read-memory-docs（记忆文档读取）
- 触发：收到任何新开发任务
- 行为：按规则读取主文档+按需读取子文档
- 效果：AI 携带完整上下文工作，杜绝"失忆"
阶段 2：理解需求
Skill 2：workflow-check（指令明晰度检查）
- 触发：用户给出模糊指令
- 行为：引导补充参数、参照物等关键信息
- 效果：减少返工，一次做对
Skill 3：task-completion-verification（多任务完成验证）
- 触发：用户需求包含 2 个以上独立任务
- 行为：逐项完成并生成验收报告
- 效果：无遗漏执行所有需求
阶段 3：设计
Skill 4：pre-task-reflection（任务前反思）
- 触发：读完记忆文档后
- 行为：预判风险、解析需求、构思方案
- 效果：避免盲目开发，减少错误修改
Skill 5：game-design-principles（游戏设计原理框架）
- 触发：新玩法设计、数值平衡、体验评审
- 行为：调用专业设计理论支撑决策
- 效果：设计逻辑科学化，拒绝拍脑袋
阶段 4：编码
Skill 6：api-guard（API 可用性守卫）
- 触发：编写 Lua 代码、调用引擎 API
- 行为：三层校验，拦截不可用/废弃 API
- 效果：杜绝 API 调用错误
Skill 7：lua-nil-hole-guard（Lua 数组 nil 空洞防护）
- 触发：构建条件元素数组
- 行为：规避 nil 空洞导致的遍历异常
- 效果：保障数组逻辑稳定
Skill 8：materials（材质库指南）
- 触发：添加材质、构建 3D 场景
- 行为：提供预制材质与配置参考
- 效果：快速调用材质资源
Skill 9：nvg-resolution-mode（NanoVG 分辨率模式）
- 触发：编写 UI 渲染代码、DPI 适配
- 行为：引导选择适配模式
- 效果：解决高 DPI 屏幕 UI 异常
Skill 10：asset-library-placement（素材库放置规则）
- 触发：生成图片/音效素材
- 行为：自动归类至指定目录
- 效果：素材统一管理，引擎可识别
阶段 5：验收
Skill 11：dev-acceptance-sop（开发验收 SOP）
- 触发：代码编写完成后自动执行
- 行为：编码→构建→预览→日志→功能五步验收
- 效果：标准化验收，全面排查问题
阶段 6：收工
Skill 12：update-memory-docs（记忆文档自动同步）
- 触发：完成实质性开发工作后
- 行为：更新对应文档、Git 提交、版本递增
- 效果：文档与代码实时同步，永不失效
全局辅助
Skill 13：maker-guide（Maker 协作指南）
- 触发：品质评估、开发规划咨询
- 行为：多维度评估+流程指导
- 效果：全局把控项目开发
Skill 14：skill-creator（Skill 创建指南）
- 触发：创建新 Skill
- 行为：规范编写规则与触发逻辑
- 效果：Skill 体系可灵活扩展
第五章：Skill 之间的协作关系
14 个 Skill 形成联动工作流，核心闭环为读取-执行-更新：
1. 用户发起新任务
2. read-memory-docs 读取项目记忆
3. workflow-check 校验指令清晰度
4. pre-task-reflection 任务预判与设计
5. 编码阶段多 Skill 协同保障代码质量
6. dev-acceptance-sop 标准化验收
7. task-completion-verification 逐项核验
8. update-memory-docs 同步文档并提交
核心闭环：开工读取 + 收工更新，确保文档永远最新。
第六章：搭建步骤（从零开始）
Step 1：创建主记忆文档
项目根目录新建 docs/ 文件夹，创建主文档，写入项目信息、文件索引、核心规则、游戏流程，控制 500-1000 行。
Step 2：AI 生成初稿+人工修正
将代码投喂 AI 生成初稿，人工补充设计意图，修正遗漏信息。
Step 3：配置核心读写 Skill
- 配置 read-memory-docs ：自动读取主文档+按需子文档
- 配置 update-memory-docs ：自动同步文档+Git 提交
Step 4：逐步扩展 Skill
不一次性全量配置，按阶段添加：
- 前期：基础读写闭环
- 中期：质量保障类 Skill
- 后期：流程优化类 Skill & 专项 Skill
Step 5：持续迭代文档
新增/删除文件、更新规则、拆分超量主文档，保持文档轻量化与时效性。
第七章：1 个月快速迭代的经验教训
教训 1：文档过长=浪费token=效率降低
三级架构拆分后，主文档 token 消耗大幅下降，有效提升工作空间。
教训 2：文档格式适配 AI 解析
优先纯文本格式，用缩进、分隔线组织内容，表格用文本对齐，避免复杂 Markdown 嵌套。
教训 3：Skill 触发条件精准定义
触发过宽浪费资源，过窄失去作用，需贴合开发场景精准设置。
教训 4：自动更新是文档生命线
无自动更新会导致文档过时，基于错误信息开发风险极高，必须配置自动同步规则。
教训 5：BUG 经验库 ROI 最高
快速迭代中积累的 BUG 经验，能让 AI 举一反三，是性价比最高的投入。
第八章：我的数据验证——效果到底如何
文档体量
- 主记忆文档：839 行
- 架构子文档：865 行
- 规范子文档：643 行
- BUG 经验库：2463 行 / 49 个 BUG / 56 个模式
- AI 工作流文档：1180 行
- 总计：5990 行
项目体量
- Lua 源代码：42,671 行 / 81 个文件
- 游戏资产：400+ 个
- 开发周期：约 1 个月
核心改善数据
- 重复 BUG：频繁出现 → 接近 0
- 新功能上手：多轮解释 → 1 轮即可
- AI 主动引用历史：从不 → 经常
总结
记忆文档 + Skill 体系的本质：将人的项目理解转化为 AI 可读的知识库，通过自动化规则保证知识库实时更新。
它并非万能方案，但对于快速迭代、代码量较大的项目，是 AI 协作开发的最优解。建议从主记忆文档+读写双 Skill 起步，短时间初始投入，节大量重复沟通成本。