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

发表于2026-06-30|更新于2026-08-14

|总字数:9.5k|阅读时长:31分钟|浏览量:

前言

用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 实践、架构热点和交接状态拆成可检索的小块，让模型少靠脑补，多靠证据。

⌁

1 个全局入口 MEMORY.md

8 类分区索引目录

REQ / BUG唯一入口归档

Evidence证据驱动结论

根索引→分区 README→条目入口→子文档证据

上下文工程AI Handover渐进式索引最小变更证据优先

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

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

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

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

注意力不是无限的

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

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

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

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

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

压缩后常见的问题包括：

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

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

核心设计理念

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

第一原则：渐进式索引

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

1 2	根索引 → 分区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 保留一个主提示词源，再生成或适配客户端文件。这样可以避免不同客户端长期手工维护完整副本，导致规则、权限和工具语义逐渐分叉。

目录结构总览

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

portable-long-term-memory/
├── MEMORY.md                          # 全局导航索引
├── rules.md                           # 项目开发规则
├── document-authoring-rules.md        # 文档编写与维护规则
├── AI-handover.md                     # AI会话交接快照
├── agent-workflow.md                  # 主 Agent 与 sub agent 共用协议
├── subagent-routing.md                # 按需 sub agent 路由矩阵
├── 00-index/                          # 顶层导航锚点
│   └── README.md
├── 01-onboarding/                     # AI新会话启动上下文
│   ├── README.md
│   └── onboarding-prompt.md
├── 02-requirements/                   # 需求与分析
│   ├── README.md
│   ├── REQ-0000/README.md
│   ├── REQ-0001/
│   │   ├── README.md
│   │   ├── 分析报告.md
│   │   └── 实施记录.md
│   └── V1/README.md
├── 03-api-practices/                  # API使用规范
│   ├── README.md
│   ├── api-practices.md
│   └── feedback_callback_types.md
├── 04-operations/                     # 操作记录
│   ├── README.md
│   └── operation-log.md
├── 05-reference/                      # 项目参考文档
│   ├── README.md
│   ├── project-overview.md
│   ├── analysis-001-architecture-flow-audit.md
│   ├── analysis-002-current-architecture-hotspots.md
│   ├── analysis-003-harmony-skills-lookup-guide.md
│   ├── analysis-004-devecocli-docs-api-lookup.md
│   ├── analysis-005-devecocli-docs-investigation-process.md
│   ├── lessons-001-network-recovery.md
│   ├── lessons-002-exception-isolation.md
│   ├── lessons-003-bugfix-feature-methodology.md
│   └── lessons-004-agent-workflow-optimization.md
├── 06-code-review-fixes/              # CR整改记录
│   ├── README.md
│   ├── CR-001-sample-fix.md
│   ├── CR-002-sample-fix.md
│   └── CR-003-sample-fix.md
└── 07-bug-reports/                    # Bug报告与修复
    ├── README.md
    ├── BUG-0001.md
    ├── BUG-0001/
    │   ├── analysis.md
    │   ├── fix-plan.md
    │   └── log01.md
    ├── BUG-0002.md
    └── BUG-0002/
        ├── analysis.md
        ├── fix-plan.md
        └── log01.md

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

各目录详解

MEMORY.md：全局导航总入口

MEMORY.md 是整个长期记忆体系的唯一入口。AI 在任何新会话、任何上下文压缩恢复后，第一件事就是读这个文件。

它的内容分为几个关键模块：

Must Read 清单：列出 AI 在开始任何工作前必须阅读的核心文档，包括项目规则、文档编写规则、AI 交接文档、项目概览、架构热点、Bug修复方法论和技能查找指引。最新版本还把共享 Agent 工作协议、按需路由矩阵和优化摘要纳入入口。
Read by Task 路由表：根据当前任务类型（新会话交接、需求开发、Bug 修复、API 查询、参考资料），告诉 AI 应该从哪里开始阅读。这个表中的每一个链接都指向唯一入口，AI 不需要猜测 “我该去哪个目录找”。
目录地图：所有分区目录和它们的一句话简介，供 AI 快速扫描。
当前状态模板：项目名、版本、技术栈等基本元信息占位。
核心原则：复用优先、最小变更、外部数据零信任、证据优先、不存敏感信息，以及只有在具体问题信号存在时才启动 sub agent。

这个文件的设计目标是：AI 读完 MEMORY.md 之后，应该知道当前项目是什么、规则在哪里、遇到问题该去哪里找、以及需要遵循什么基本原则。全程不需要自己猜。

rules.md：项目的宪法

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

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

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

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

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

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

规则15：工具链不执行。 明确禁止 AI 在没有授权的情况下执行编译、打包、安装等操作。这条规则防止 AI 在调试过程中”顺手”运行一些不该运行的东西。

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

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

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

它的核心内容包括：

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

这个文件的定位是”给维护者看的”，不是给 AI 看的。它保证了这套文档体系本身不会随着时间推移而熵增。

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

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

内容分五个部分：

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

这个文档的价值在于：当上下文压缩后 AI 回来，或者换了一个模型继续工作时，只需要花两分钟读这个文件，就能恢复到接近压缩前的状态。

00-index：顶层导航锚点

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

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

它的规则是：不存业务代码、不存私密信息，只做导航。

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

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

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

分类：明确任务类型、目标、范围、现有证据、写入范围和结束条件。
渐进式读取：先读启动指令、全局索引和项目规则，再按任务进入需求、Bug、API、审查或参考入口；文档编写规则只在文档发生实质变化时读取。
按需编排：选择最小角色集合，并行执行独立角色；问题已回答就停止。
合并证据：给结论标注来源性质，避免把建议、静态分析或提交记录包装成更强的事实。
执行与收尾：按最小变更修改，检查 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 的一层路由即可定位到任何细节。

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-004~005`	DevEco CLI 文档/API 查找与调查过程
`lessons-001~003`	可复用的经验教训——网络恢复、异常隔离、Bug修复方法论
`lessons-004-agent-workflow-optimization.md`	Agent 按需编排、证据协议、多客户端同步和迁移检查清单

这个目录的设计哲学是：一次分析，永久复用。每当你和 AI 花了大量时间排查清楚一个架构问题或总结出一个方法论，就把它沉淀到这里，以后遇到类似问题直接链接。

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 我上周是不是已经修好了”的尴尬。

使用流程

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

阶段一：首次接入

将模板复制到项目工作区
用项目实际信息替换所有 <placeholder>
在 AI-handover.md 中填写当前项目快照
在 project-overview.md 中记录项目架构和主要入口点
在 operation-log.md 记录初始化操作
如果要接入多个 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/

阶段四：上下文压缩恢复

AI 检测到上下文压缩后，第一时间返回长期记忆目录
重读 MEMORY.md → AI-handover.md
根据当前任务类型，重读对应的分区 README
只有任务确实涉及 Agent 编排或工作流维护时，才继续读取 agent-workflow.md 和 subagent-routing.md
确认当前代码状态、保护差异和证据标签后再继续工作

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

常见误区

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

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

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

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

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

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

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

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

把历史记录或提交信息当成当前事实。 历史结论需要和当前源码核对，commit 只能说明变更发生，不能说明行为已经验证。只有明确的测试、人工操作、设备运行或外部系统结果，才能标记为 已验证。

最后总结

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

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

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

这套模板我已经开源到了 GitHub：memory-methodology-template。截至 2026 年 7 月 19 日，本地仓库最新 commit 为 f5fb0c2e7a5592d8de819413b643b3ac60f0beaa，提交标题是“添加 Agent 工作流优化内容摘要和相关链接”。它新增了 05-reference/lessons-004-agent-workflow-optimization.md，并同步更新 MEMORY.md 和 05-reference/README.md；前一个 commit de5df514e3179e9452f2f87af1bf180ad186956b 则引入了 agent-workflow.md 和 subagent-routing.md，把按需 Agent 机制接入 README、规则和 onboarding。这里的 commit 信息属于代码/文档事实，只能证明这些文件变更已经提交，不能替代测试或人工验证结果。

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