渐进式披露长期记忆文档模板

发表于2026-06-30|更新于2026-11-13

|总字数:14.2k|阅读时长:45分钟|浏览量:

前言

用AI编程的时间越长，我就越深刻地意识到一个问题——上下文，是AI编程中唯一真正稀缺的资源。

你可能觉得模型智力不够、觉得它生成代码的质量差、觉得它总是忘记你十分钟前刚说过的话。但这些问题的根源，绝大多数都可以归结为两个字：上下文。上下文不够，模型不懂你的项目；上下文太长，模型的注意力被稀释；上下文压缩，关键信息丢失；切换模型或新开会话，一切归零。

更致命的是，大模型有一个天然的结构性缺陷——上下文压缩。无论你的上下文窗口是200K还是1M，在一个工程级项目中迟早会溢出。一旦触发压缩，模型会自行决定保留什么、丢弃什么，而这个决定的依据并不是”对你来说什么最重要”，而是模型自身注意力机制下的统计学判断。压缩后它可能把 ArkTS / ArkUI 代码写成普通 TypeScript 或前端框架范式，也可能把 @State、@Prop 这类 ArkUI 状态装饰器的使用场景搞混，甚至凭空创造出一个看起来很合理但实际上根本不存在的 API。这些错误具有极强的隐蔽性——它们不一定会立刻报编译错，很多时候要到运行或联调阶段才会暴露，排查成本极高。

所以，我现在越来越关注一个概念——“大海捞针”（Needle in a Haystack）。大模型的核心能力，不在于它能不能”捞起针”——能不能在一段文本中找到答案——而在于它能不能在一片越来越大的干草堆里快速找到那根针。上下文越长，干草堆越大，找到针的难度就越高。而良好组织、分层索引的文档体系，本质上就是把干草堆按类别压实成一个个小捆，让模型不必翻遍整座草山。

大模型的能力体现在大海捞针时”找到针”的过程，而不在于”捞起针”这个动作本身。好的文档能让模型锁定针的位置，差的文档会让模型被干草淹没。

这就是我为什么要做 Memory Methodology Template 这个仓库。它不是一套提示词合集，而是一套结构化的、可迁移的、渐进式索引的文档脚手架。它的核心目标就一个：让AI知道该去哪里找什么东西，而不是记住所有东西。

🧠 Long-Term Memory · Template

Memory Methodology Template

一套面向 AI 编程的长期记忆文档脚手架——共享层沉淀跨项目方法论，项目层各自维护事实，用渐进式索引和可重建的本地检索索引把规则、需求、Bug、API 实践与交接状态拆成可定位的小块，让模型少靠脑补，多靠证据。

⌁

2 层共享层 + 项目层

21 条可执行工作区规则

REQ / BUG唯一入口归档

FTS5可重建检索缓存

工作区枢纽→项目 MEMORY→分区 README→条目证据

上下文工程AI Handover渐进式索引检索即缓存证据优先

查看 GitHub 仓库 ↗适合用于新项目初始化、AI 接力、上下文压缩恢复和长期工程知识沉淀。

如果你正在用 AI 编程却总被上下文压缩后乱写、模型遗忘关键约束、多人/多模型接力断层所困扰，这套模板或许能帮你的 AI 从一个”随缘编码的工具”升级为一个”有案可查的工程师”。

大模型的注意力缺陷与上下文困境

在深入模板设计之前，我想先聊聊”为什么”——为什么大模型需要这样一套文档体系？这要从两个根本性问题说起。

注意力不是无限的

OpenAI在早期对长提示词的研究中就曾发现：当单个文档中的提示词长度过长、包含太多需要注意的重点时，模型的注意力反而会被分散到不同的点上，导致无法集中于核心目标。最终模型输出的内容经常偏离主题，甚至前后矛盾。

这是个反直觉的结论。很多人觉得”提示词写得越长越详细越好”，但实际情况是——你写的每一条”重要提示”，都在争夺模型有限的注意力预算。当一份文档里有20个”注意”、30个”重点”时，模型大概率一个都记不住。

注意力是稀缺资源。一份文档只应该告诉模型一件事，而不是一百件事。

上下文压缩是你的隐形敌人

另一个更隐蔽的问题是上下文压缩。无论你的模型支持多大的上下文窗口——200K、500K、甚至1M——在工程级项目中，你一定会在某个时刻触发压缩。一旦触发，模型会自行决定保留什么、丢弃什么。这个决定不经过你同意，也不会通知你，而且结果具有极大的随机性。

压缩后常见的问题包括：

问题类型	表现
语法漂移	模型忘记当前语言/框架的语法规则，开始用其他语言的范式编写
接口幻觉	模型凭空创造出听起来合理但实际上不存在的API或导入路径
规则遗忘	你明文规定的核心约束被当作”不重要信息”丢弃
状态混乱	模型对当前代码的实际状态产生错误的”记忆”
逻辑断裂	同一段逻辑的前后两部分使用完全不同的实现思路

这些问题之所以致命，是因为它们往往不会直接报错——代码看起来”像模像样”，但运行时的行为完全不可控。

核心设计理念

基于以上认知，Memory Methodology Template 的设计围绕以下几条核心理念展开：

第一原则：渐进式索引

这是一切的基石。模板的设计哲学可以浓缩为一句话：

1 2	工作区枢纽 → 项目MEMORY → 分区README → 条目入口 → 子文档证据每一层保持精简，细节向下沉淀。

类比一下：这套结构就像一本书的目录体系。MEMORY.md 是总目录，各个分区 README 是章节目录，条目入口是具体小节，子文档则是附录和参考文献。AI 不需要一次读完整本书——它只需要先看目录，定位到相关章节，再展开阅读。

这样做的好处是显而易见的：

降低上下文消耗：AI 每次只读当前需要的那一小部分，不浪费 token
提高信息密度：每一步读到的都是精选过的、高信息密度的内容
降低压缩风险：单次读取的文档都很短，不容易触发压缩

第二原则：先索引，再阅读

这是写给 AI 的元规则。任何新会话或上下文压缩恢复后，AI 必须第一时间返回长期记忆目录，重读 MEMORY.md 和相关模块文档，绝不凭”残存记忆”继续工作。

如果你觉得”这不是理所当然的吗”——不，实际情况是大多数模型在压缩后都会自信满满地凭残存记忆继续编代码。它们不会主动告诉你”我忘了”，只会默默地把接口写错、把规则忽略、把逻辑搞乱。

第三原则：稳定规则与实时状态分离

这一点特别重要。模板把文档明确分为两类：

稳定文档：rules.md、document-authoring-rules.md、各分区 README。这些是方法论和规范，不随具体任务变化。
实时状态文档：AI-handover.md、各 REQ-*/ 和 BUG-*/ 下的实施记录。这些反映当前进度，随任务推进持续更新。

为什么要分离？因为如果让 AI 在同一个文档里既读”永久规则”又读”临时状态”，它会混淆两者的权重。分离之后，AI 知道稳定文档是铁律，状态文档是参考。

第四原则：需求与 Bug 各自拥有唯一入口

每个需求、每个 Bug 都有且只有一个入口文档（REQ-XXXX.md 或 BUG-XXXX.md），配套一个同名子目录存放证据材料。

这样做避免了”一个需求分散在五个文档里，改了一处忘了改另一处”的常见问题。AI 只需要记住一个 ID，就能定位到所有相关信息。

第五原则：证据驱动

所有结论必须基于可查证的证据——源码、日志、截图、用户反馈——而非推测、印象或 commit message。

这个原则的关键在于：它不让 AI 去”猜”根因，而是要求它先收集证据再下判断。在我的实际使用中，这个原则显著降低了 AI 在调查 bug 时陷入”盲猜-验证-再盲猜”循环的概率。

第六原则：Agent 按需使用

最新版本的模板不再把 sub agent 设计成固定流水线，而是把它们当成可选的只读上下文工具。主 Agent 负责理解需求、确定范围、选择角色、核验证据、修改文件和请求授权；sub agent 只回答一个具体问题，例如定位历史入口、追踪调用链、分析日志或规划回归检查。

判断标准不是”这是不是代码任务”，而是任务中是否存在明确的不确定性、证据类型、工作区风险或影响面。目标文件、函数、改法和验收条件都已经明确，且没有历史不确定性、本地差异或跨模块影响时，主 Agent 直接处理即可。

这条原则带来一个很重要的停止条件：问题已经被回答，就停止继续调用 Agent；最多追加一批后续角色，除非用户明确要求深度审查。简单任务不应该因为涉及代码、框架文件或交付步骤，就自动消耗一组完整的上下文分析。

第七原则：协议统一，角色分离

Agent 工作协议、路由矩阵和专项提示词各自只承担一类职责：

工作协议：定义生命周期、证据标签、输出格式、停止条件和记忆写入流程。
路由矩阵：根据问题信号选择最小角色，并定义什么时候追加角色。
专项提示词：只保留某个角色的领域差异，不重复主协议。

当多个 AI 客户端同时使用这套模板时，每个 Agent 保留一个主提示词源，再生成或适配客户端文件。这样可以避免不同客户端长期手工维护完整副本，导致规则、权限和工具语义逐渐分叉。

第八原则：共享层与项目层分离

当模板只服务一个项目时，所有文档平铺在一起问题不大。但一旦多个项目共享同一份记忆库，”这个项目的 Bug 结论被套到另一个项目上”就会变成真实的风险。最新版本把整个结构拆成两层：

共享层：根部的 rules.md、agent-workflow.md、document-authoring-rules.md 和 shared/ 目录。只放项目无关的方法论——Bug修复方法论、规模化检索采用指南、真机验证工作流、官方文档查找流程。一个文档要进入共享层，它的规则和例子都必须与具体项目无关。
项目层：projects/<project-name>/ 下每个项目一个目录，各自维护自己的 MEMORY.md（项目导航与当前状态）、AI-handover.md 和编号分区目录。

两条硬性规则：共享文档永远不复制进项目层，在项目里复用共享方法时要把例子里的路径和标识符换成该项目自己的；一个项目的事实（源码契约、Bug 结论、commit 记录）绝不套用到另一个项目上，归属不明就先问。

第九原则：检索索引是缓存，不是事实来源

这是最新版本写入 rules.md 第 20 条的边界。当记忆库规模超过千份文档时，模板配套了一个基于 SQLite FTS5 的本地检索索引，但它的定位被刻意压得很低：

索引只负责定位入口，返回的是带路径、行区间和源文件 hash 的”候选引用”；
任何结论都必须回读原文并核对 hash 之后才能采信，引用失效会直接报错，而不是拿旧行号冒充当前引用；
Markdown + Git 是唯一事实来源，索引是可随时删除重建的缓存——删掉缓存目录，一切回退到 rg 加目录路由，别无其他变化。

目录结构总览

模板的完整目录结构如下：

portable-long-term-memory/
├── MEMORY.md                          # 工作区枢纽：项目地图 + 启动阅读顺序 + 共享层路由
├── rules.md                           # 工作区规则（所有项目共用，20条）
├── agent-workflow.md                  # 主 Agent 与 sub agent 共用协议
├── subagent-routing.md                # 按需 sub agent 路由矩阵
├── document-authoring-rules.md        # 文档编写与维护规则（含分层放置与检索索引政策）
├── shared/                            # 共享层：跨项目方法论
│   ├── README.md
│   ├── analysis-001-memory-index-and-retrieval.md        # 规模化检索采用指南（阈值/方案/实测）
│   ├── analysis-004-devecocli-docs-api-lookup.md         # 官方文档只读查找流程
│   ├── lessons-003-bugfix-feature-methodology.md         # Bug修复与功能开发方法论
│   ├── lessons-004-agent-workflow-optimization.md        # Agent 按需编排优化摘要
│   └── lessons-005-opt-in-device-validation-workflow.md  # Opt-In 真机验证工作流
├── tools/
│   ├── README.md
│   ├── memory_index/                  # SQLite FTS5 本地检索索引（只读工具 + 20个单元测试）
│   └── automation/                    # 本地 Git 钩子门禁：pre-commit 检查 / post-commit 审计
└── projects/                          # 项目层：一个真实项目一个目录
    ├── README.md                      # 项目层约定
    ├── project-a/                     # 完整脚手架示例（复制即用）
    │   ├── MEMORY.md                  # 项目级导航与当前状态
    │   ├── AI-handover.md             # 项目级交接快照
    │   ├── 00-index/                  # 顶层导航锚点
    │   ├── 01-onboarding/             # AI新会话启动上下文
    │   ├── 02-requirements/           # 需求与分析（含拆分工作流与 scoped 规则模板）
    │   ├── 03-api-practices/          # API使用规范
    │   ├── 04-operations/             # 操作记录
    │   ├── 05-reference/              # 项目参考文档
    │   ├── 06-code-review-fixes/      # CR整改记录
    │   └── 07-bug-reports/            # Bug报告与修复
    └── project-b/                     # 最小项目层示例：枢纽入口 + 交接快照 + 按需目录

接下来我逐个目录讲解它的设计目标、使用方法和预期效果。

各目录详解

MEMORY.md：从全局入口到工作区枢纽

MEMORY.md 是整个长期记忆体系的第一入口。AI 在任何新会话、任何上下文压缩恢复后，第一件事就是读这个文件。双层结构改造后，它的角色发生了一个重要变化——从”单项目的总目录”升级为”工作区枢纽”，只保留三类内容：

项目地图：一张表列出工作区里的每个项目——名称、别名、代码位置、记忆入口。外加一条识别规则：任务提到别名或标识符时，先映射到项目；绝不把一个项目的源码事实、契约、Bug 结论或 commit 记录套到另一个项目上，归属不明就先问。
启动阅读顺序：本文件（识别目标项目）→ rules.md（工作区规则）→ 目标项目的 MEMORY.md（当前事实与进行中的工作）→ 再沿渐进式索引下钻，只打开当前任务需要的部分。已采用检索索引时，先用索引定位历史条目入口，回读原文后再采信；索引失效则回退 rg 加目录路由。
共享层与目录地图：指向根部规则文件、agent-workflow.md、document-authoring-rules.md、shared/ 方法论层和 tools/ 工具层的一句话路由。

原来那些”Must Read 清单、Read by Task 路由表、当前工作快照”并没有消失——它们整体下沉到了每个项目自己的 projects/<项目名>/MEMORY.md 里。项目级入口同样列必读文档、按任务类型的路由表和分区目录地图，只是它导航的是本项目的事实，不再混杂其他项目。

这个文件的设计目标是：AI 读完根 MEMORY.md 之后，应该知道当前任务属于哪个项目、共享规则在哪里、该项目自己的入口在哪里；读完项目 MEMORY.md 之后，应该知道当前项目是什么、进行中的工作有哪些、遇到问题该去哪里找。全程不需要自己猜。

rules.md：项目的宪法

rules.md 是 AI 在项目中的行为准则。它定义了 AI 在开发、修改、归档等所有场景下必须遵守的规则。

模板中包含21条规则，覆盖了从任务边界到验证回归的全流程。这里我挑几条最有代表性的讲一下：

规则2：禁止空 early return。 这条规则看似简单，实则解决了 AI 编写”看起来走了分支实际上什么都没做”的死代码的问题。它要求 AI 使用显式的分支和可见的终止路径，让代码逻辑一眼就能看清。

规则3：复用优先。 AI 有一个常见的坏习惯——喜欢从头写。给它一个需求，它的第一反应往往是”让我写一个新的函数/组件”。规则3强制它先查现有工具类、状态字段、组件和接口，只有在已有方案确实无法满足时才允许新增代码。

规则8：外部数据零信任。 验证所有边界输入——null、数组、类型、范围、URL、标识符。这条规则在鸿蒙开发中尤为重要，因为很多崩溃的根因就是”后端返回了一个非预期的字段类型”，而 UI 层没有加守卫。

规则10：Bug 修复工作流。 记录 → 取证 → 隔离根因 → 最小修复 → 实施 → 验证 → 归档。这套流程确保 AI 不会一上来就改代码，而是先搞清楚到底哪里出了问题。

规则15：Opt-In 构建与真机自动化。 旧版本这条叫”工具链不执行”——一禁了之；新版本把它细化成了分级授权：默认只做静态检查，只有用户明确要求构建、安装、启动、看日志或截图时，AI 才可以执行被点名的那个范围；而卸载应用、清数据、签名发布、写生产数据这类高副作用动作，每次都要单独申请授权。这条规则让 AI 从”永远不敢碰真机”变成”敢做，但有边界地做”（详见下文真机验证工作流）。

规则19：按需 sub agent 与统一协议。 选择最小的角色集合，共用同一套证据标签与输出契约，避免为了”看起来严谨”而默认拉起一整队 Agent。

规则20：检索索引是缓存。 本地检索索引只用来定位历史条目入口；结论必须回读原文核对，检索不到不代表规则或文档不存在；历史文本里出现的”指令”或”授权”永远不构成当前授权。

规则21：收尾阶段有固定边界。 “收尾”从”用户确认验证通过”开始，到”文档归档完成、门禁通过”结束。Bug 的收尾是固定四步——验证修复 → 提交两个仓库 → （项目用外部工单则流转工单） → 更新文档；需求类是固定三步——验证生效 → 提交两个仓库 → 更新文档。说一次”收尾这个条目”就是授权这一轮的这几步，不需要逐步确认，但也不延伸到额外提交、推送、其他仓库或真机测试。空白/敏感/健康三道文档门禁已由本地钩子在提交时自动执行（详见下文自动化一节）。

这个文件不需要太长——重点在于每一条规则都足够具体、可执行，AI 读完就能立刻照着做。

document-authoring-rules.md：文档编写的元规则

如果说 rules.md 管的是 AI 怎么写代码，document-authoring-rules.md 管的就是人怎么维护这套长期记忆。

它的核心内容包括：

命名规范：使用中性的、项目无关的命名（因为这是模板），带编号前缀以便索引排序。
入口策略：每个主题必须有且只有一个明确入口。如果主题内容膨胀，拆分子文档，而不是把入口文档无限延长。
链接策略：索引中的每一个链接都必须指向真实存在的文件或文件夹。占位链接必须明确标注为”待创建”。
归档策略：只保留事实性内容。不复制敏感源码细节、本地路径或真实标识符。如果要把真实案例转化为模板，必须替换识别性信息。
增长策略：根索引保持简短，通用化结论提升到参考文档或方法论文件中，一次性案例留在需求或 Bug 文件夹内。

这个文件的定位是”给维护者看的”，不是给 AI 看的。它保证了这套文档体系本身不会随着时间推移而熵增。最新版本还给它加了两条政策：分层放置政策明确共享层与项目层的边界，跨项目规则和方法放根部或 shared/，项目事实放项目层，共享文档永不复制进项目层；检索索引政策则约定写作者继续写普通 Markdown，索引器从路径和标题自动派生条目、片段和别名——更新上级索引的义务不因索引存在而免除。

AI-handover.md：会话交接快照

这个文件是整个体系里”最短命”但”最高频”的文档。它的作用是在会话开始或模型切换时，为 AI 提供一个极简的项目快照。

内容分五个部分：

项目快照：项目名、代码位置、版本、语言、技术栈、关键依赖——一张表说完。
必读清单：引导 AI 去读规则、交接文档、证据，而不是凭印象干活。
当前工作快照：列出当前进行中的需求和 Bug 及其状态，每个条目都有直达链接。
当前热点：列出当前版本最敏感的风险区域，以及对应需要关注的环节。
下一步行动：告诉 AI 接下来该做什么——读索引、找相关文档、收集证据、设计最小方案、验证、归档。

这个文档的价值在于：当上下文压缩后 AI 回来，或者换了一个模型继续工作时，只需要花两分钟读这个文件，就能恢复到接近压缩前的状态。双层结构后，这份快照下沉到每个项目层各自维护（projects/<项目名>/AI-handover.md），根部不再保留全局交接文件——跨项目的”交接”由根 MEMORY.md 的项目地图承担。

00-index：顶层导航锚点

这个目录最小也最简单。它的唯一作用是提供一个稳定的导航入口，指向全局索引 MEMORY.md。

为什么需要它？因为在某些工具链或 Agent 中，AI 可能不知道从哪里开始。00-index/README.md 提供了最简单的路由表：去读 MEMORY.md、去读 rules.md、去查需求、去查 Bug。

它的规则是：不存业务代码、不存私密信息，只做导航。双层结构后，它跟随项目层移动到 projects/<项目名>/00-index/，职责不变。

agent-workflow.md：主 Agent 与 sub agent 的共用协议

这是最新版本新增的核心文件。它把主 Agent 和可选 sub agent 的边界写清楚：主 Agent 拥有决策权、编辑权、验证结论和授权请求；sub agent 是只读的上下文工具，负责收集定向证据、追踪链路、审查风险或准备验证清单。sub agent 的结论不能自动变成项目事实，主 Agent 必须核对关键路径、声明和 diff。

协议把一次任务拆成五个阶段：

分类：明确任务类型、目标、范围、现有证据、写入范围和结束条件。
渐进式读取：先读启动指令、全局索引和项目规则，再按任务进入需求、Bug、API、审查或参考入口；文档编写规则只在文档发生实质变化时读取。已采用检索索引时，优先用它定位历史条目入口，命中结果仍是候选引用——回读原文后再采信；索引失效则回退 rg 加目录路由，不阻塞任务。
按需编排：选择最小角色集合，并行执行独立角色；问题已回答就停止。
合并证据：给结论标注来源性质，避免把建议、静态分析或提交记录包装成更强的事实。
执行与收尾：按最小变更修改，检查 diff、链接、索引和保护差异，区分实际执行的静态检查与人工/设备验证；提交记忆树时本地钩子自动执行文档门禁——提交被阻断即收尾未闭环，修复后重新提交。

协议还规定了统一输出顺序：适用性、检查范围、代码事实、历史结论、风险与待确认、建议下一步、停止原因。这样主 Agent 不必从一段泛化的长报告中猜测哪些内容真的与当前任务有关。

subagent-routing.md：按需路由矩阵

路由文件不负责解释所有 Agent 的工作方法，只回答一个问题：当前问题最小需要哪个角色，什么情况下才追加角色？

问题信号	最小角色	追加条件
历史入口不清	`memory-router`	找到相关条目后停止
目标文件有本地差异	`workspace-guardian`	只检查指定文件和 diff
新行为或复用关系不清	`chain-mapper`	发现跨模块后追加 `architecture-reviewer`
Bug 调用链不清	`bug-path-tracer`	有日志时追加 `log-analyzer`
存在日志、崩溃报告或多步复现	`log-analyzer`	需要源码对应时追加路径追踪
跨模块、全局状态或公共服务变化	`architecture-reviewer` + `chain-mapper`	再按任务类型追加 Bug 或验证角色
框架状态、生命周期、手势或 API 风险	`domain-compliance-reviewer`	纯样式和资源调整跳过
复杂改动需要人工回归	`verification-planner`	影响面明确后再启动
多个文档需要交接同步	`handoff-summarizer`	单行索引修改跳过

因此，改一个颜色、尺寸、文案、资源或单文件参数，通常不需要 sub agent；有日志的运行时 Bug 优先分析日志，只有源码调用链不清时再追加路径追踪；跨模块需求则先确认现有链路和架构影响，再决定是否生成验证矩阵。

证据标签与验证边界

最新协议把容易混淆的结论拆成六类：

标签	含义
`代码事实`	当前源码、配置或 diff 直接证明的内容
`历史结论`	长期记忆或旧方案中的记录，必须重新核对
`用户/测试反馈`	用户、测试人员、设备运行或外部系统提供的结果
`推断`	基于证据形成、但尚未完全证明的解释
`待确认`	缺少源码、日志、测试数据或用户确认
`已验证`	有明确验证结果支持的结论

这里有一条尤其值得强调的边界：commit 可以证明某次文档或代码变更存在，但不能证明测试已经通过。同样，静态分析不能写成编译或设备验证结果，sub agent 的建议也不能写成“已加载的 skill”。

01-onboarding：AI 新会话启动区

这个目录放的是 AI 接手一个新会话时最需要的最小上下文。

核心文件是 onboarding-prompt.md，它包含：

项目快照占位：项目名、语言、技术栈、版本。
必读清单：按优先级列出 AI 必须阅读的文档，并明确 Agent 工作协议和路由矩阵只在相关场景读取。
工作规则：最小变更、复用优先、外部数据零信任、证据优先、不存敏感信息，并且不默认启动一组 sub agent。
风险区域：状态漂移、弱校验、超大修改范围、缺失的验证、跨模块责任不清——这些都是实际项目中踩过坑的高风险区。
输出风格：交接文档应包含当前状态、未决问题、已收集证据、下一步行动和验证状态。

这个目录的关键在于”最小化”——只放新会话启动绝对需要的内容，其他一切下沉到具体目录。新版本通过“按需读取”降低启动成本：只有 sub agent 编排或工作流维护进入范围时，才展开读取 Agent 协议和路由文件。

02-requirements：需求与分析

这是整个体系中内容最富集的目录之一。每个需求对应一个 REQ-XXXX/ 子目录，包含：

文件	作用
`README.md`	需求入口，总览状态、涉及模块、子文档索引
`分析报告.md`	范围界定、证据收集、根因分析、方案推荐
`实施记录.md`	决策记录、变更清单、验证结果、后续事项

此外还有一个版本维度的索引 V1/README.md，用于按版本追溯需求流。

这个目录的设计目标是：一个需求的所有信息——从原始描述到分析到实施到验证——全部归拢在同一个目录下，通过 README 的一层路由即可定位到任何细节。

最新版本还给这个目录补了一套需求拆分与局部规则工作流（requirement-decomposition-and-local-rules-workflow.md），解决两个老问题：一个大型版本文档怎么拆成可追溯的需求条目，以及一个版本或需求内部的稳定重复流程要不要单独立规矩。

拆分判断很朴素：只有当一个条目拥有独立的用户目标、入口点、数据契约或验收结果，能独立调查、实施、验证或交付，或者留在版本 README 里会掩盖范围、归属、状态或未决依赖时，才给它单独开目录。改个措辞、补一张截图这种小事，并入既有条目即可。

局部规则则遵循”用最窄的适用规则，不复制上级政策“的层级：工作区规则 → 分区工作流 → 版本级 rule-*.md → 需求级 rule-*.md / workflow-*.md。更窄的规则只能为它声明的范围补充细节，不得悄悄削弱上级定义的授权、安全、证据和验证边界。配套的 templates/scoped-rule-template.md 提供了模板——先由工作流确认确有”稳定、重复、目标单一、有停止条件”的流程值得沉淀，再把填好的规则文件放进归属它的版本或需求目录，并在入口处索引。

03-api-practices：API 使用规范与技术约束

这个目录沉淀的是”写代码时不能踩的坑”。

核心文件 api-practices.md 定义了 API 使用的通用模式：

先读契约
验证所有输入
显式类型转换
遇到非预期形状时 fail closed
保持 UI 层和数据层同步

它的重心在于：把”为什么这个 API 不能这么用”讲清楚，而不是罗列 API 参数表。对于鸿蒙这种训练语料少的领域，这个目录的价值极高——它告诉 AI “别用你训练数据里学到的前端写法，这里不适用”。

04-operations：操作记录与日志

这个目录很小但很重要。核心文件 operation-log.md 记录了关键操作的时间线：

1 2	- 2026-06-30: 创建模板结构 - 2026-06-30: 添加索引、规则和参考占位

你可以把它理解为项目的”航(zuò)海(sǐ)日志”——什么时候做了什么关键操作、有没有回滚、为什么回滚。当几个月后回头排查一个历史问题时，操作日志往往能提供关键的时间线信息。

05-reference：项目参考文档

这是内容最丰富的目录，存放的是”不太会变但很有用”的参考信息：

文件	内容
`project-overview.md`	项目的抽象事实——名称、版本、技术栈、仓库布局、主要入口点
`analysis-001-architecture-flow-audit.md`	针对某条架构链路的聚焦分析
`analysis-002-current-architecture-hotspots.md`	当前版本的风险热点地图
`analysis-003-harmony-skills-lookup-guide.md`	领域技能查找指引——什么场景该加载哪个 skill
`analysis-005` / `report-001`	DevEco CLI 文档调查过程与专项调查报告
`lessons-001~002`	项目内可复用的经验教训——网络恢复、异常隔离

注意 lessons-003（Bug修复方法论）、lessons-004（Agent 工作流优化）、lessons-005（真机验证）和 analysis-004（官方文档查找）已经迁出到共享层 shared/——它们脱敏后的规则和例子已经项目无关。留下来的都是还带着本项目具体路径、编号或工具语境的分析。

这个目录的设计哲学依然是：一次分析，永久复用。每当你和 AI 花了大量时间排查清楚一个架构问题或总结出一个方法论，就把它沉淀下来，以后遇到类似问题直接链接——只是现在要先判断它属于项目层还是共享层。

shared/：跨项目方法论层

双层结构新增的共享层，收录”规则和例子都与具体项目无关”的方法论文档：

文档	回答的问题
`analysis-001-memory-index-and-retrieval.md`	记忆库规模到什么程度该上本地检索索引、怎么上、效果如何
`lessons-003-bugfix-feature-methodology.md`	Bug修复与功能开发的证据链、根因隔离、最小变更与验证格式
`lessons-004-agent-workflow-optimization.md`	Agent 按需编排、证据协议、多客户端同步与迁移检查清单
`lessons-005-opt-in-device-validation-workflow.md`	真机构建、部署、日志、UI 操作与截图验证的授权边界
`analysis-004-devecocli-docs-api-lookup.md`	框架/厂商官方文档的只读查找流程与记录要求

进入共享层有一条硬门槛：一个文档只有在规则和例子都项目无关时才能迁入；例子引用了某个项目的目录、编号或工具路径，就必须先泛化，否则留在那个项目的 05-reference/ 里。共享文档被 rules.md 或项目索引引用时还必须保持文件名稳定——重命名意味着要同步更新每一个上级索引。

Opt-In 真机验证工作流

8 月的更新补上了一块此前的空白：AI 到底能不能碰真机。旧规则 15”工具链不执行”是一刀切的禁止，结果是 AI 永远只能交付”静态检查通过”，最后的验证矩阵全部压给人。新工作流（shared/lessons-005-opt-in-device-validation-workflow.md）把它细化成一个分级授权模型：

默认：实现、修复、检查、验证类请求不授予任何工具链或设备控制权限，AI 只做静态检查并准备人工验证矩阵。
限定范围自动化：用户明确要求构建、安装、启动、看日志、截图或操作应用时，AI 只执行被点名的范围——发现并选定测试设备、调试构建与同包覆盖安装、按应用/关键词/严重级/时间窗过滤日志、限定范围的点击滑动返回和截图核对。授权不延续到后续任务、其他应用、其他账号或无关测试矩阵。
高副作用单独授权：卸载应用、清应用数据、改永久权限或账号状态、发帖点赞关注收藏分享删除购买、写生产数据、签名上传发布、处理真实凭据——每一项具体动作都要单独申请，且永不把”卸载”当作安装或签名问题的默认应对。

工作流还划了一条 AI 与人的分工线：AI 负责可重复的构建部署、窄日志、布局检查、确定性交互和截图取证；人负责复杂导航、信任弹窗、登录验证、主观体验和大范围回归。双方都只汇报实际执行过的场景——一次构建成功，不等于整个应用或版本通过了。

tools/memory_index：规模化的本地检索

当记忆库还小的时候，渐进式索引加 rg 就是全部检索手段。但规模上去之后，纯文本检索的四个痛点开始真实计费：按编号找入口要翻好几层目录；英文工具对连续中文子串基本无效；每个会话都在重复读同一批入口文档；同编号多入口被静默合并。最新版本配套了一个脱敏泛化后的检索工具 tools/memory_index/——基于 SQLite FTS5 的只读索引加命令行：

python3 tools/memory_index/cli.py build                                  # 全量或增量构建
python3 tools/memory_index/cli.py search "BUG-0001" --project project-a  # 按编号查入口
python3 tools/memory_index/cli.py search "<中文关键词>" --format json    # 中文子串检索
python3 tools/memory_index/cli.py verify-source <path> <line_start> <line_end> <hash>  # 引用回读核对

它的架构原则先行于任何表结构：Markdown + Git 是唯一事实来源；索引器只读原文，hash 是唯一变更依据（mtime 和 size 只作提示、不作判断，它们会骗人）；不做常驻服务、不做文件监听，查询前懒刷新；歧义不裁决——同编号多入口全部返回，绝不静默合并。检索上走词表（unicode61）加 trigram 双通道融合排序（RRF 加权），后者专门解决”从中文句子中间截三个字来查”这个普通分词的命门；一到两字的中文短词则显式回退限定范围的扫描，不静默漏结果。

该不该上这套东西？配套的采用指南（shared/analysis-001-memory-index-and-retrieval.md）给出了规模分层：

总量	建议方案
< ~100 份 / < 1 MiB	只用渐进式索引 + `rg`，定位任意入口 ≤ 3 步
~100–1,000 份 / 1–10 MiB	渐进式索引 + 文档健康检查（链接/锚点/启动路由门禁）+ `rg`
≥ ~1,000 份，或升级信号出现两条以上	引入 SQLite FTS5 本地索引

一次真实落地的实测数字（语料为通用方法论文档库）：1,483 份文档 / 16.6 MiB 全量初建 5.4 秒，得到 16,251 个片段；无变更增量刷新约 0.2 秒；混合查询 P95 约 300 毫秒；中文两字/三字/整句片段均可达；跨项目误混 0；引用回读一致率 100%。代价也有：索引体积约 230 MiB（trigram 正文副本是主要开销），以及初建加 50 条人工金标查询集加单元测试的数人日前期投入。回退成本则被刻意压到最低——删掉缓存目录，一切回到 rg 加目录路由，原文与 Git 历史零影响。

tools/automation：收尾门禁的自动化执行

最新的更新把规则 21 的门禁从”靠 AI 记得跑”变成了 Git 提交时的机械执行。这个仓库刻意保持纯本地——没有托管 CI、没有常驻服务，本地 Git 钩子就是它的”CI”：

组件	触发时机	行为	是否阻断
`hooks/pre-commit`	每次提交	空白检查；暂存 Markdown 的敏感模式扫描（私钥块、密钥赋值、Bearer 凭据、口令赋值、手机号、URL 凭据参数——只报 file:line，不输出命中内容，避免扫描器自己成为泄露通道）；存在健康检查器时顺带执行	阻断；`--no-verify` 绕过必须留档理由
`hooks/post-commit`	每次提交	已采用索引时输出 memory_index 审计摘要；`stale_check.py` 给出状态陈旧提示	仅警告，不阻断

安装只有一行：sh tools/automation/install.sh（本质是把 core.hooksPath 指向钩子目录），每个克隆装一次；可选组件缺失时自动降级，不报错不摆烂。

配套的术语定义把”收尾”的边界钉死了：起点是用户确认验证通过，终点是文档归档完成且门禁通过——之前的一切是开发/验证，之后的回归、发布、外部系统关闭都不属于收尾，也不被”收尾”这个词授权。Agent 的职责因此从”记得跑门禁”变成”读钩子结果并处理阻断”：提交被阻断即收尾未闭环，修复后重新提交即可恢复流程；用 --no-verify 跳过必须在任务文档里记录理由，且永远不算”门禁通过”；只有钩子未安装、被跳过或目标仓库不是这个记忆树时，才回退为手动跑健康检查器和 git diff --check。还有一条很克制的边界：所有脚本对源文档只读、不改任何东西、不授予任何权限——自动化输出只是证据输入，不是授权凭证。

projects/：项目层

项目层一个真实项目一个目录。project-a 是完整脚手架示例：自己的 MEMORY.md、AI-handover.md，加上原来的八个编号分区（00-index 到 07-bug-reports）——前文详解的那些目录现在都住在这一层。project-b 则示范了多项目记忆的最小形态：一个枢纽入口、一份交接快照、任务目录按需创建，不用一上来就复制整套脚手架。

新增项目只有三步：创建 projects/<项目名>/ 并从 project-a 复制所需目录、清空示例内容；在根 MEMORY.md 的项目地图里登记别名、代码位置和记忆入口；如果项目有自己的编号约定，把它们加进检索工具的实体抽取配置。

06-code-review-fixes：CR 整改记录

这个目录按 CR-XXX 编号存放 Code Review 中发现的问题和修复摘要。每个记录包含：

问题描述：Review 中提出了什么
修复方案：最小改动是什么，什么保持不变
涉及文件：改了哪些文件
验证方式：怎么确认修复有效

它的存在价值在于：当类似的问题在后续 Review 中再次出现时，可以直接引用既有记录，而不是重新分析一遍。

07-bug-reports：Bug 报告与修复

Bug 管理是整个文档体系中结构最严谨的模块。每个 Bug 有：

一个唯一入口文件 BUG-XXXX.md：包含状态、描述、环境、复现步骤、根因摘要、修复摘要、验证状态。
一个同名子目录 BUG-XXXX/：存放深度分析、修复计划、日志文件、截图等证据材料。

Bug 的状态流转遵循明确的定义：

状态	含义
To triage	已记录，尚未分析
Investigating	根因分析进行中
Ready to implement	方案已确定，等待编码
Fixed, pending verification	代码已修改，等待验证
Verified	已通过验证
Rolled back	错误修复已回滚

这套结构解决了一个非常实际的问题：当你同时追踪多个 Bug 时，每个 Bug 的调查进度、证据链和修复状态都清晰可查，不会出现”这个 Bug 我上周是不是已经修好了”的尴尬。

使用流程

了解了每个目录的作用之后，再来看这套模板在实际开发中的完整使用流程：

阶段一：首次接入

将模板复制到工作区，把 projects/project-a/ 复制为你的 projects/<项目名>/ 并清空示例内容
在根 MEMORY.md 的项目地图中登记项目：别名、代码位置、记忆入口
用项目实际信息替换所有 <placeholder>
在项目层的 AI-handover.md 中填写当前项目快照
在 project-overview.md 中记录项目架构和主要入口点
在 operation-log.md 记录初始化操作
每个克隆执行一次 sh tools/automation/install.sh 安装本地收尾门禁
复用共享层方法论时，把例子里的路径换成该项目自己的；不要把共享文档复制进项目层
文档规模尚小时不要急着引入检索索引——出现升级信号再按采用指南落地（见上文检索一节）
如果要接入多个 AI 客户端，为每个 sub agent 确定一个主提示词源，并先在隔离目录执行迁移 dry-run

阶段二：需求开发

先分类任务：明确目标、范围、证据、写入范围和结束条件
按拆分工作流判断是否值得独立条目，然后在项目层 02-requirements/ 下创建 REQ-XXXX/ 目录；版本或需求内确有稳定重复流程时，再落一个被入口索引的局部规则文件
在 README.md 中记录需求原始描述和范围
只有存在历史不确定性、链路不清、跨模块影响或验证复杂度时，才按路由矩阵选择最小 sub agent 集合
进行分析，将结论写入 分析报告.md，并区分代码事实、历史结论、推断和待确认项
AI 设计方案，人工审核
AI 实施修改，完成后更新 实施记录.md
更新 AI-handover.md 中的当前工作快照

阶段三：Bug 修复

在 07-bug-reports/ 下创建 BUG-XXXX.md 和同名子目录
记录现象、环境、复现步骤
根据证据类型选择最小角色：有日志优先 log-analyzer，调用链不清时再追加 bug-path-tracer
收集日志和截图放入子目录
隔离根因，写入 analysis.md
设计最小修复方案，写入 fix-plan.md
实施修复
单独记录实际静态检查、人工验证和设备验证，不能用 commit 信息替代测试结果
验证并更新状态为 Verified
按收尾阶段定义闭环：验证修复 → 提交两个仓库 → （有工单则流转工单） → 更新文档；本地钩子自动执行门禁，提交被阻断即收尾未闭环
如果发现是可复用的教训，沉淀到 05-reference/（项目无关的泛化后进共享层 shared/）

阶段四：上下文压缩恢复

AI 检测到上下文压缩后，第一时间返回长期记忆目录
重读根 MEMORY.md（识别目标项目）→ rules.md → 目标项目的 MEMORY.md → 项目 AI-handover.md
根据当前任务类型，重读对应的分区 README
只有任务确实涉及 Agent 编排或工作流维护时，才继续读取 agent-workflow.md 和 subagent-routing.md
已采用检索索引时，可先用它定位相关历史条目，但结论仍以回读原文为准
确认当前代码状态、保护差异和证据标签后再继续工作

这套流程的核心思想就一句：把大模型当成一个每次睡醒都会失忆的同事。你需要给它留一张工位上的便签，告诉它项目是什么、资料在哪、昨天做到哪了、今天要干什么。

常见误区

最后聊聊我在实际使用中观察到的一些常见误区：

把所有的规则都塞进一个超长文档。 这是最常见的错误。一个 5000 行的提示词文件不是”全面”，而是”无效”。模型读完前三段的时候注意力已经被稀释到无法聚焦任何一条规则了。

只写目录不写更新规则。 文档体系最大的敌人是熵增。如果没有明确的更新规则（谁改、什么时候改、改完后怎么同步索引），这套结构在两个月内就会变成一堆过时的废话。

把临时想法和稳定规范混在一起。 临时调试笔记、想法草稿、未经验证的假设，这些东西应该放在各自主题的子目录里，不要污染入口文档和索引。

让 AI 自己脑补项目 API。 AI 在缺少上下文时会自动调用它训练数据中的”经验”，而这个经验很可能跟你的项目完全不沾边。对于鸿蒙这种小众技术栈，一定要在规则文件中明确约束”只允许使用项目中已经出现过的 API”。

文档量不大就急着上检索索引。 规模化检索指南明确写了反指标：低于约 1,000 份文档时，渐进式索引加 rg 已经够快，而建库的前期投入和持续一致性维护是实打实的成本。索引会多出一个需要与文档演进保持同步的派生物——升级信号出现两条以上再动手不迟。

把 --no-verify 当成绕过门禁的常规手段。 本地钩子阻断提交说明收尾没有闭环——正确反应是修复问题后重新提交。确需跳过时必须在任务文档里记录理由，而且跳过永远不等于”门禁通过”；门禁的语义不会因为被绕过而消失。

只记录成功方案，不记录失败尝试。 有时候，”这个方案行不通以及为什么行不通”比”最终用了什么方案”更有价值。失败的尝试记录能防止 AI 在下一次遇到类似问题时重复走弯路。

把 sub agent 当成固定流水线。 新版本已经明确：sub agent 是可选的只读上下文工具，不是每个任务都必须经过的阶段。简单、明确、单文件的修改由主 Agent 直接完成；只有具体问题信号出现时，才启动最小角色集合。

把不同客户端的提示词复制后手工维护。 多份完整副本迟早会产生语义差异。正确做法是维护一个主提示词源，在隔离目录中 dry-run，生成客户端适配文件，再检查名称、描述、开发者指令、工具语义和权限差异。

把历史记录或提交信息当成当前事实。 历史结论需要和当前源码核对，commit 只能说明变更发生，不能说明行为已经验证。只有明确的测试、人工操作、设备运行或外部系统结果，才能标记为 已验证。检索索引的命中同理——它们只是候选引用，回读原文核对 hash 之后才能采信；检索不到也不代表规则或文档不存在，直接查目录。

最后总结

长期记忆本质上不是一堆越写越长的提示词，而是一套给 AI 使用的项目资料库，同时也是 Agent 的导航和证据边界。它需要有入口、有索引、有分层、有操作日志、有明确的更新规则，还要知道什么时候不应该启动额外 Agent。

回到”大海捞针”这个比喻：我们给 AI 堆上下文，就像往干草堆里扔更多的干草——草堆变大了，但针的密度变低了，找到针的难度反而增加了。而一套良好设计的长期记忆体系，是在草堆里插上路标、画上地图、建好索引。AI 不需要翻遍整座草山，它只需要看路标，走到正确的位置，拿起那根针。

如果说普通的提示词是在”临时指挥”AI，那么长期记忆就是在给一个会失忆的同事搭建工位；Agent 工作协议则是这间工位的工作纪律。资料放在哪里、遇到问题先读什么、什么时候找同事帮忙、什么证据可以下结论、做完事情记录到哪里——这些看似琐碎的规则，才是让 AI 能够长期、稳定、高质量地参与工程开发的基础。

这套模板我已经开源到了 GitHub：memory-methodology-template。截至 2026 年 11 月 13 日，本地仓库最新 commit 为 5e0b698e291d70614ca25be4808ad6899554c04f，提交标题是”docs: local automation hooks and closure-stage term definition”。它新增 tools/automation/ 本地自动门禁（pre-commit 空白/敏感/健康检查、post-commit 索引审计与陈旧提示），并在 rules.md 第 21 条给出”收尾阶段”的术语定义——提交被阻断即收尾未闭环。它前面是 c31d6d9c7d9711e0b011c92e377c42f66fea6f29（重构为共享层加项目层的双层结构，根 MEMORY.md 升级为工作区枢纽，新增规模化检索采用指南和 tools/memory_index/ 检索工具）与 2426c1c879fe73fb8ac19873e5ceff6ff1faaa1a（新增需求拆分与局部规则工作流、Opt-In 真机验证工作流，并把规则 15 从”工具链不执行”细化为分级授权）；更早的 Agent 工作流演进见前文各章节。这里的 commit 信息属于代码/文档事实，只能证明这些文件变更已经提交，不能替代测试或人工验证结果。

它是一个起点，不是一个终点。你可以根据自己的项目结构、技术栈和团队习惯进行调整。唯一不变的核心原则是：