

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

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

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

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

![](https://developer.qcloudimg.com/http-save/yehe-12464096/be9c17a38d593316f4e7d8b04406d912.png)

## 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 分为两条并行轨道：

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

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

![](https://developer.qcloudimg.com/http-save/yehe-12464096/8a0e32329ed1fd3860a6357219bb1baf.png)

图 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`词条。对于轻量碎片化经验，允许开启免查重快照模式，将一致性校验延迟交给后置的刷新机制处理。

![](https://developer.qcloudimg.com/http-save/yehe-12464096/d4995c6e1f61f68fc0bc867c9fd50ed2.png)

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

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

## 按持久度分级的知识地图

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

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

![](https://developer.qcloudimg.com/http-save/yehe-12464096/a8522fd50cf8238c50a4d7ae4c2ecffa.png)

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

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

1. 持久化链路：必须具备版本化、可审查、可长期保存的特征。这部分知识直接进入 Git 追踪，随代码库一同演进。主要有：
    
    1. `docs/solutions/`：存放所有的 Learning 语料，是团队主要的长期记忆。
        
    2. `CONCEPTS.md`：存放团队共享的领域词汇表，用于统一多 Agent 协同与人类开发者的概念认知，只定性，不写死 Spec。
        
    3. `STRATEGY.md`：记录当前推进的主线任务与技术方向，作为 Agent 执行规划时的基础落地。
        
    4. `docs/plans/` 与 `brainstorms/`：固化技术决策的推演过程，用于后续追溯“当时为什么这么做”的依据。
        
2. 临时/派生链路：这些属于中间产物，核心价值在于提升运行效率，不承担事实来源的职责：
    
    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`**（想法探索）：在生成构想时自动接入，避开历史上已经验证失败的技术方向；
    

![](https://developer.qcloudimg.com/http-save/yehe-12464096/7f74116ed908a00cba4b96845839121c.png)

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

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

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

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

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

## 记忆防腐机制

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

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

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

![](https://developer.qcloudimg.com/http-save/yehe-12464096/b40ed374fc3b91c606901073ad314a01.png)

图 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。
    

![](https://developer.qcloudimg.com/http-save/yehe-12464096/43c3d7e4bf4a1fd8999a9b14276cbd8f.png)

## 小结

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

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

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

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

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

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

Thinkroom 提出“知识复用”替代传统“代码复用”，将每次问题解决沉淀为结构化、机器可读的 `Learning`（Markdown 文档），嵌入研发全流程：调试后自动捕获、规划前智能检索、编码时强制遵循、审查中实时校验。知识按持久性分级存储，辅以防腐机制与毫秒级 Grep-First 检索，让历史经验真正驱动下一次开发——知识不再沉睡于 Wiki，而活在工作流中。

人工智能

开发工具

后端

在Agent工程中，知识复用比代码复用更重要。本文分享Thinkroom团队如何将研发经验转化为结构化Learning文档，通过自动化捕获、分级存储和智能检索机制，让历史知识在工作流中自动沉淀与应用，避免重复踩坑，提升开发效率。

软件工程

回归测试

代码解释

智能体

路由

Agent

2026上云采购 | AI焕新·智启新局

lexiang

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

从一次修复到长期记忆：Agent 工作流里的知识沉淀-腾讯云开发者社区-腾讯云

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

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

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐