从一次修复到长期记忆：Agent 工作流里的知识沉淀

在传统软件工程中，我们推崇"代码复用"；但在 Agent 参与的工程中，能产生复利的东西从"代码复用"变成了"知识复用"。

日常开发中我们会常遇到一个问题：某个复杂的 Agent 框架踩了像是路由失效，或是上下文污染的坑，花了数小时定位并修复，顺手写了一篇详细的复盘文档丢进 Wiki。但在下周另一个同事开发新功能时，他依然会踩进同一个坑。

Wiki 一般会成为"只写不读"的文档坟墓。这不是因为复盘写得不好，而是因为它没有进入工作流------它只是被存了起来，却没有在下一次真正需要它的时候，自动出现在工程师或 Agent 的眼前。

在本文中我们将分享 Thinkroom 团队是如何知识沉淀，**实现每一次问题的解决，都必须让下一次的开发变得更容易。**接下来，我们看看这套系统是如何让历史知识在工作流中自动沉淀与捞取的。

Learning 是沉淀的最小单位

在这套系统里，每一次值得保留的研发经验都会被收敛为一个Learning（解决方案文档）。

Learning 是一个纯文本的 Markdown 文件，规范化地存放在代码仓的docs/solutions/<category>/路径下。每个 Learning 拒绝长篇大论的叙事，只围绕一个明确解决的工程问题展开，并在文件头部内嵌一段结构化的 Frontmatter。

这是一个真实样例：

YAML 复制代码

---
title: Always-on routing for interactive menus belongs inline in
       SKILL.md, not in references
date: 2026-04-28
category: skill-design
module: compound-engineering
problem_type: architecture_pattern
component: ce-plan
severity: medium
applies_when:
  - Authoring a skill that ends in an AskUserQuestion-style menu
  - Deciding whether per-option routing belongs in SKILL.md or a reference
  - Reviewing a skill where the agent renders a menu and stops
    at the user's selection without acting
tags: [skill-design, menu-routing, skill-md-vs-references, ce-plan,
       extraction-rule, load-bearing-rules]
related_issue: https://github.com/EveryInc/compound-engineering-plugin/issues/714
---

这段 frontmatter 的作用不是让人读起来更工整，而是让 Agent 更容易检索。它的设计是提高机器可读性，降低 Agent 的检索开销：

title与tags：作为第一层过滤的结构化字段初筛，Agent 不用执行文件 I/O 读正文，只要通过并发grep元数据就能完成高速匹配。
module与component：来精准判断当前开发的上下文是否触碰到了相同的底层模块。
applies_when：提供显式的自描述触发条件，未来的 Agent 读取这几行就能在几毫秒内判定当前任务是否命中此规则。

这里有一个关键字段problem_type。

如果知识库只盯着 Bug 修复，系统会漏掉大量高价值的隐性架构资产。技术团队在研发迭代中沉淀下来的，除了"某段代码在哪里崩了"这种局部清扫，还有更具工程价值的非代码实体的设计决策与边界约定。像是"为什么要采用特定的架构模式"、"某类抽象应当收拢在哪个层级"，以及"哪种看似合理的改动会带来隐藏的回归风险"这些软资产。

因此，Learning 分为两条并行轨道：

Bug 轨道：包括runtime_error、test_failure、logic_error、performance_issue等运行时缺陷。
知识轨道：包括 architecture_pattern、design_pattern、tooling_decision、convention、best_practice等架构与约定决策。

从线上仓库的实测数据来看，Thinkroom 当前已有的 35 个有效 Leanings 中，知识轨道的文档占据了绝大多数。整个系统运转的重心，已经从单纯的"线上故障修补记录"，演进成了"团队共享的工程判断准则库"。

图 2：docs/solutions census 图。35 个 Learning 在 skill-design、best-practices、integrations 等类别中的分布。

如何获取一个 Learning

知识沉淀的核心痛点在于"时效性引起的熵增"。

在 Bug 刚修复或技术决策刚达成的片刻，路径排查、失败尝试的排除、真正的根因以及 Diff 细节，在当前上下文窗口中的信息保真度最高。因此，这时候原地生成的 Learning 有非常高的信息密度。一旦到周报或复盘会时再补写，大量关键链路信息就会丢失，最终降级为"修复某配置错误"这种低价值的流水账，对后续的 Agent 指导产生不了大的作用。

因此，系统需要将知识捕获硬编码为调试流水线的终点。

在测试跑通的现场，工程师可以直接触发/ce-compound指令。系统会随之启动一套多 Agent 并发提取、单点串行写入的架构：

Context 分析器：负责判定 Category 分类、生成标准文件名并初始化 Frontmatter 结构；
解决方案提取器：全量审计当前 Session 对话、代码 Diff 以及测试断言结果，结构化提炼出问题表象、排查路径、最终解法与预防手段；
相关文档查重器 ：并发检索已有的docs/solutions/语料，做重叠度交叉比对，提示合并或引用，防御知识碎片化。

这里要留意并发的安全设计：为了避免多 Agent 并发修改导致代码仓库状态混乱或写冲突，子 Agent 仅负责内存中的内容提取，无权直接操作 Git 追踪文件。而编排器作为唯一网关，执行单点串行写入。

除了上述完备的交互式捕获，系统还提供了低成本的轻量化入口。例如，/ce-debug在完成根因定位后会主动挂载沉淀埋点；/ce-pov达成架构定论后可 headless 自动生成 tooling_decision词条。对于轻量碎片化经验，允许开启免查重快照模式，将一致性校验延迟交给后置的刷新机制处理。

图 3：The life of one learning 图。issue #714 说明一次事故如何变成修复、Learning、测试和 doctrine。

这便将知识沉淀从"事后靠人写总结"，重构为了"工作流 Pipeline 顺手完成的架构产出"。

按持久度分级的知识地图

在 Agent 工作流中，捕获到的知识并非都适合一股脑地塞进同一个文件或上下文中。

如果没有清晰的存储分级，记忆很快会在"无效噪音"与"高价值共识"的混杂中失效。Thinkroom 的 Memory Map 有一个非常清晰的解耦标准：资产级别的信息进入 Git 追踪；过程级别的信息留在临时目录。

图 4：持久化知识与临时缓存的架构边界

技术团队的知识资产可以划分为两条核心边界：

持久化链路：必须具备版本化、可审查、可长期保存的特征。这部分知识直接进入 Git 追踪，随代码库一同演进。主要有：
1. docs/solutions/：存放所有的 Learning 语料，是团队主要的长期记忆。
2. CONCEPTS.md：存放团队共享的领域词汇表，用于统一多 Agent 协同与人类开发者的概念认知，只定性，不写死 Spec。
3. STRATEGY.md：记录当前推进的主线任务与技术方向，作为 Agent 执行规划时的基础落地。
4. docs/plans/ 与 brainstorms/：固化技术决策的推演过程，用于后续追溯"当时为什么这么做"的依据。
临时/派生链路：这些属于中间产物，核心价值在于提升运行效率，不承担事实来源的职责：
1. repo-profile cache：在 commit 触发时动态生成的仓库画像快照，供 5 个以上的核心技能共享拉取。这类信息放在/tmp或本地缓存中，即便被意外删除，系统也可以在几秒内无损重构。

这套存储拓扑背后有一个工程评判准则：丢失后会让团队感到心疼、无法一键找回的隐性知识，必须进入 Git 接受审查；而随时可以低成本重新派生的物理快照，应当留在临时目录。

检索机制

许多复盘文档最终沦为"Wiki 坟墓"，本质上是因为传统检索是在考验团队的纪律性。Thinkroom 的检索设计直接将人进行解耦，放弃向人推送（Push），改为由工作流在关键节点主动拉取（Pull）。

检索系统通过底层的learnings-researcher协议，将历史知识的检索彻底硬编码到了日常研发最频繁使用的 5 个核心 Agent 技能中：

/ce-plan（规划阶段）：在结构化开发计划之前自动检索，将历史经验转化为当前的硬性约束条件与关键技术决策；
/ce-brainstorm（需求梳理）：在对齐需求时自动检索，利用过去的死胡同来划分当前设计的边界；
/ce-code-review（自动化审计）：作为 Always-on Reviewer 逐行扫描 Diff，把历史 Learning 直接转化为当前的审查判断；
/ce-debug（调试排查）：在报错并进行根因假设时，让已知根因模式直接跳过常规排查排队，实现优先匹配；
/ce-ideate（想法探索）：在生成构想时自动接入，避开历史上已经验证失败的技术方向；

图 5：Grep-First retrieval funnel 漏斗模型图，显示了从元数据初筛到高保真结论注入的完整执行链路

为了在大规模文档库下依然保持毫秒级的响应，该协议在底层采用了 Grep-First 漏斗模型：

结构化字段初筛：直接在操作系统层面并发grep所有文档头部的 Frontmatter 字段。此时不调用大模型，无需执行文件 I/O 读入正文，仅用轻量级匹配快速过滤出极少数候选文件。
候选全文精读：初筛出高概率候选文后，Agent 才真正对这几篇候选文档执行全文读取。
上下文动态注入：大模型介入，最终提炼出不超过 5 条的高保真研判定论，直接注入到当前任务的上下文窗口中。

这种低成本的过滤机制带来了两个工程实效：

极致的响应速度：即使未来面对成百上千篇 Learning，也无需支付高昂的 Token 和时间开销去深读全量语料。
极低的上下文噪声：Agent 在当前任务中面对的是高度提炼的确定性约束，有效避免了长文本导致的注意力失焦。

记忆防腐机制

代码在重构，架构在演进，团队的约定也会随时更新。一个写于几个月前的 Learning，里面记录的文件路径和调用设计很可能已经被彻底改掉。如果 Agent 依然盲目死记硬背，历史经验就会变成新的错误来源。

为了解决这个问题，记忆系统并没有"让人定期大扫除"，而是默认"记忆必然会过期"，在工作流中内嵌了三道防腐线：

第一道防线：当下证据获胜 ：在learnings-researcher读取阶段，如果某个历史 Learning 的断言与当前仓库里的物理代码实体发生冲突，系统会强制要求 Agent 标记冲突，并以当前的代码为准。历史文档只作为排查线索，权重不超过当前事实。
第二道防线：相干邻域审计 ：当使用/ce-compound新增或修改CONCEPTS.md中的核心领域词条时，Agent 会被强制要求同步审计与该词条存在直接引用关系的"邻域词条"。一旦发现概念漂移，立即在有证据的范围内进行修补。这种设计有效地锁定了审计边界，拒绝发起昂贵的全库刷新。
第三道防线：按需主动刷新 ：在团队经历了大型业务重构、或者发现某个模块的历史 Learning 明显滞后于最新代码时，工程师可以通过指定的 Scope 命令进行定向清扫：/ce-compound-refresh <scope-hint>。

图 6：read time、write time、on demand 三种刷新节奏

实战闭环案例：一个新技能特征的完整流转

为了看清这套系统在日常研发中是如何流转的，我们以 Thinkroom 最近刚上线的一个新技能/ce-explain为例。

在这整个端到端的合入过程中，系统在各个阶段自动触发了知识系统，整个演进过程完全不需要人类。

Brainstorm 阶段（需求梳理）：在没有向开发者提出任何问题之前，Agent 先从共享缓存中拉取了当前仓库的画像快照（repo-profile cache）。在此次运行中，由于没有命中缓存，系统在后台动态派生了新的快照并将其持久化，以便供接下来的 9 个关联技能直接使用。有了这个快照，Agent 得以快速扫描现有系统，提前摸清了所有的历史相似设计。
Plan 阶段：在规划阶段，检索协议自动捞出了 5 篇历史 Learning 注入上下文。在撰写技术方案时，其中 3 篇被标记为"必须遵循"的硬性条件，包括：之前踩坑换来的菜单内联路由机制（Issue #714 的血泪遗产）、$ARGUMENTS可移植性，以及SKILL_DIR脚本锚定规则。最终，这 3 篇 Learning 沉淀为了本轮开发计划中"关键技术决策"的核心依据。
Implementation 阶段（代码实现）：在真正的编码阶段，Agent 严格执行了规划中的设计约束。不仅如此，针对历史 Learning 中提到的各类边界防御手段，新技能在生成的过程中，还在测试侧对应长出了属于它自己的镜像回归测试。
Review 阶段（自动化审查）：在提交代码后的审计阶段，自动化 Review 工具对照 8 篇相关的历史 Learning 全量扫描了本次合入的 Diff，给出了全部通过的判断。在此期间发生了一个插曲：一名人类工程师曾提出一个看似更优雅的优化意见，但 Review 验证器利用由 Learning 沉淀演进来的AGENTS.md直接驳回了该提议，因为那个改动会重新引入历史上的已知漏洞。记忆在此处不单单是指引工作，而是在防御代码回退。
Vocabulary & Residue（概念沉淀与演进残留）：当 Brainstorm 阶段刚刚敲定需求边界的瞬间，新抽离出的概念Explainer与Check-in就已经被同步写入了领域概念字典CONCEPTS.md中。同时，本次 Review 遗留下来一个非阻断式的优化项，被团队故意延后并提为了 Issue #1057。

小结

在 Agent 工作流中，系统的长期价值不仅取决于单个任务的执行速度，更取决于它能否将本次任务的经验无缝留给下一次。如果每次修复都流失在当前会话窗口里，哪怕大模型再聪明，团队在工程层面上依然会陷入反复"失忆"的死循环。

这套方案最核心的借鉴意义，不在于倡导大家去"多写文档"，而在于把知识流动的管道彻底建在现有工作流里：在修完问题时原地捕获，做计划前深度检索，写代码时强制遵守，审查 Diff 时自动化校验，发现过期时精准刷新。知识沉淀不再是额外的人力负担，而是变成了智能体工程系统天然的一部分。

传统软件工程里，我们习惯于复用代码和组件。而在迈向智能体工作流的进程中，更值得被复用和固化的，是那些从真实工程泥潭里提炼出来的技术判断、团队约定与架构经验。

一次 Bug 修复结束的地方，本就应当是下一次开发变得更轻松的开始。