你的记忆文档如何设计？踩坑后，我是这么做的……

解决什么问题AI 对话没有持久记忆。每次新会话，AI 从零开始，忘记项目架构、踩过的坑、约定的规则。项目越大，"重复犯错"和"上下文丢失"越严重。核心思路：把 AI 的记忆外化成文档，用规则约束 AI 每次开工必读、收工必写。

你的项目/

├── docs/

│   ├── MEMORY.md              ← L1 主文档（AI 每次必读）

│   ├── BUG-EXPERIENCE.md      ← L3 项目级 BUG 经验库

│   ├── ARCHITECTURE.md        ← L2 子文档（按需创建）

│   └── DOC-SYSTEM-BLUEPRINT.md ← 蓝图（搭建体系的说明书）

│

~/智能体配置

    └── GLOBAL-BUG-EXPERIENCE.md  ← 全局经验库（跨项目共享）

三层结构：层级文件读取时机行数上限L1 必读MEMORY.md每次会话必读空项目 ~150 行，成熟 ≤1000 行L2 按需ARCHITECTURE.md 等任务涉及时读每个 ≤1000 行L3 按需BUG-EXPERIENCE.md 等编码阶段读每个 ≤1000 行全局GLOBAL-BUG-EXPERIENCE.md每次会话读（如已开启）不限

第一步：创建主记忆文档 MEMORY.md这是整个体系的核心。AI 每次开工先读它，收工后更新它。八章制结构：markdown

复制# 项目记忆文档（主文档）

> 版本: v0.1.0 | 最后更新: 2026-03-23

> 状态: 初始化 | 行数目标: ≤150 行（空项目）/ ≤1000 行（成熟项目）

---

## 编辑原则

- 写"是什么"，不写"怎么做"（How 放子文档或代码注释）

- 枚举信息全部表格化（文件索引、数值规则、状态列表）

- 每次更新后检查行数，接近 1000 行时拆分到子文档

---

## 导航：子文档索引

| 级别 | 文档 | 路径 | 行数 | 何时读取 |

|------|------|------|------|---------|

| L3 | BUG 经验库 | docs/BUG-EXPERIENCE.md | ~40 | 编码阶段必读 |

> 子文档按需创建，不提前创建空文件。

---

## ch1 项目概况

| 字段 | 值 |

|------|-----|

| 一句话描述 | （填写你的项目描述） |

| 技术栈 | UrhoX + Lua 5.4 + NanoVG |

| 目标平台 | （填写） |

| 当前阶段 | 开发中 |

## ch2 文件结构

（列出关键文件和职责，表格化）

## ch3 核心规则

（数值规则、架构规则、命名规则，全部表格化）

## ch4 业务流程

（核心状态流转）

## ch5 技术选型

（引擎/UI/物理/存储的选型和理由）

## ch6 模块注册表

（每个模块一行：文件、职责、依赖）

## ch7 决策日志

（重要技术决策，只写结论不写过程）

## ch8 开放问题

（未解决的问题和待确认事项）

## 变更日志

- v0.1.0: 初始化

关键设计决策：

第二步：创建 BUG 经验库每次修 BUG 后记录，避免 AI 重复犯同样的错。markdown

复制# BUG 经验库

> 版本: v0.1.0 | 累计: 0 条

## 记录格式

严重度标记:

  🔴 P0 崩溃/阻断 — 程序无法运行或核心功能完全失效

  🟡 P1 功能异常 — 功能不符合预期但不崩溃

  🟢 P2 体验/轻微 — 视觉瑕疵、性能可优化

每条记录 ≤15 行:

  BUG-XXX | 分类 | 严重度 | 简述

  影响: 哪些模块/功能受波及

  现象: 一句话

  原因: 一句话

  修复: 关键代码或操作

  教训: 通用规律（最重要，AI 以后怎么避免）

  对比:

    ❌ 错误写法

    ✅ 正确写法

## 分类索引

| 分类 | 编号列表 | 数量 |

|------|---------|------|

| 引擎 API | - | 0 |

| UI | - | 0 |

| 状态管理 | - | 0 |

| 其他 | - | 0 |

## 详细记录

（修复 BUG 后在此追加）

格式要点：

第三步：创建全局经验库（跨项目共享）放在 ~/智能体配置GLOBAL-BUG-EXPERIENCE.md，所有项目的通用教训汇总于此。三段式结构：markdown

复制# 全局 BUG 经验库（智能体准则）

> 累计记录: 0 条 | 经验模式: 0 条

## 第一部分 - 快速索引

（按分类索引表 + 按错误信息索引表）

## 第二部分 - 详细记录

（G-XXX 全局编号，每条含 ❌✅ 对比，标注来源项目）

## 第三部分 - 经验模式

（3+ 条同类 BUG 提炼为通用规则 P-XXX）

格式:

  模式 P-XXX: [名称]

  适用场景: 什么情况下需要检查

  规则: 一句话通用规律

  自检清单:

    - [ ] 具体检查动作

提升判断标准：

第四步：建立 AI 行为规则（15 个 Skill）Skill 是 AI 自动执行的规则。不要一次全部启用，按阶段渐进：第一批（立即启用） — 最小闭环：Skill名称作用1read-memory-docs开工读文档（含全局经验库）12update-memory-docs收工写文档2workflow-check模糊指令拦截第二批（开始写功能时） — 质量保障：Skill名称作用4five-step-pipeline调研→规划→批注→拆分→执行11dev-acceptance-sop五步验收3task-completion-verification多任务核验第三批（踩过第一个坑后） — 防御加固：Skill名称作用6api-guardAPI 校验7code-pattern-guard危险模式拦截15global-bug-syncBUG 提升到全局经验库其余 Skill（按需启用）：架构守护、代码重构、项目顾问等。

核心工作流每次会话开始

  │

  ▼

Skill 1: 读 MEMORY.md → 读子文档 → 读全局经验库

  │

  ▼

接收任务 → Skill 2 检查指令是否清晰

  │

  ▼

Skill 4: 五步流水线（调研→规划→批注→拆分→执行）

  │

  ▼

编码过程中 → 比对 BUG 经验库和全局经验模式

  │

  ▼

Skill 11: 验收（构建→日志→功能→边界→清理）

  │

  ▼

修复 BUG 时:

  ├→ Skill 12: 写入项目 BUG-EXPERIENCE.md

  └→ Skill 15: 评估通用性 → 提升到全局 GLOBAL-BUG-EXPERIENCE.md

  │

  ▼

会话结束

  │

  ▼

Skill 12: 更新 MEMORY.md（文件结构、模块注册表、决策日志）