1. 先聊聊"八股"是怎么来的：AI 只是缺一本"项目手册"
如果你用过 AI Agent 做实际项目，大概率有过这种体验：问它一个具体的技术问题，它给出的答案逻辑完整、层次分明、语言规范，但就是感觉"哪里不对"——它建议的技术方案跟你们项目的技术栈对不上，它写的代码风格跟你们团队的不一样，它给出的排错步骤根本走不通。
问题出在哪？很多人以为是模型能力不够，换个更强的模型就好了。但我的实际经验是：问题不在模型，在于 Agent 手里没有你们项目的"手册"。
你可以把 AI Agent 想象成一个能力很强但刚入职的实习生。你让它"写一个用户登录接口"，它能把 OAuth2、JWT、Session、SSO 各种方案都给你列出来，每个方案都能讲得头头是道。但你问它"我们项目该用哪个"，它就懵了——因为它不知道你们项目是单体架构还是微服务，不知道你们已有的用户体系长什么样，不知道你们安全团队有没有硬性规范，不知道你们老板偏好哪种方案。
一个刚入职的实习生，拿到需求之后会怎么做？他会先翻项目文档、看已有代码、问同事技术选型。但 AI Agent 不会主动做这件事，因为它没有"常识"——它不知道你的项目在哪个仓库、文档在哪、哪些决策是已经被讨论过并定下来的。它只能基于训练数据里别人的项目经验来生成回答，而别人的项目经验不等于你项目的实际情况。
这就是"AI 八股文"的根源：Agent 在做题，但手里没有考纲，只能凭感觉写。
那怎么解决？答案就在标题里——把知识沉淀给 AI Agent。不是让它"学习"你的项目，而是你主动把项目的领域知识整理好、喂给它，让它每次做决策、写代码、回答问题时，都能先查阅这本"手册"，再结合自己的通用能力给出真正契合项目情况的输出。
我见过太多团队在 AI 工具上投入了大量精力，各种框架、中间件、 Prompt 工程堆了一堆，但最后效果就是"看起来很智能，用起来很鸡肋"。核心原因就是：大家都忙着教 AI"怎么说话"，却忘了告诉它"你们项目是怎么回事"。
在我自己的实践里，一旦想通"给 Agent 喂知识"这个方向，项目落地的手感完全不一样。下面把我整理的这套方法拆开来讲，包括知识怎么分层、怎么组织、怎么让 Agent 真正用起来，以及我在实操中踩过的坑。这一篇延续上一篇对"八股文"的反感，不整虚的，全部是可以直接拿去用的东西。
2. 知识沉淀的"三明治"结构：规则层、资料层、技能层
知识沉淀这个词听起来很虚，一听就让人想起写不完的文档、没人看的 wiki。后来我换了个思路——不要为了沉淀而沉淀，要让知识在 Agent 工作的每一个环节都被消费掉。基于这个目标，我把知识分成三个层次，自己给它起名叫"三明治结构"。
2.1 规则层：告诉 Agent"你是谁、边界在哪"
规则层对应的是项目的"宪法"，是最顶层的约束。它的作用是让 Agent 在任何对话、任何任务中始终知道：你在为哪个项目工作，这个项目有什么不可逾越的规则。
具体包括：
- 项目的基本信息：项目名、定位、目标用户、核心业务场景
- 技术栈清单：前端框架、后端语言、数据库、中间件、部署方式
- 硬性规范：比如"生产环境禁止直接修改数据库""所有对外接口必须走网关""代码必须通过 CI 检查才能合并"
- 权限边界：哪些信息不能对外输出，哪些操作 Agent 不能擅自建议
规则层不追求"多"，追求"准"。我见过有人把几十页的公司规章制度全塞给 Agent，效果反而更差了——Agent 不知道哪些是高优先级约束，赶紧给它一份精炼的"项目宪法"，控制在十到二十条以内。每条规则都应当是项目强约束的真实反映，而不是可有可无的建议。
这一层知识通过系统提示词（System Prompt）或者项目级配置文件注入。实操里我会在项目的.agent/目录下放一个RULES.md，用固定的格式写清楚，然后让 Agent 在每次会话开始时自动加载。
2.2 资料层：给 Agent 准备一个"项目知识库"
规则层解决的是"知道你是谁"，资料层解决的是"了解你做过什么"。这一层对应的是项目的各种过程资料和沉淀文档，包括：
- 历史技术决策记录（ADR）：当初为什么选这个框架，放弃了哪个方案
- 架构设计文档：模块划分、数据流、接口约定
- 已复盘的问题记录：线上故障、生产事故、踩坑复盘
- 代码模块说明：核心模块的职责和边界
- 业务术语表：项目里特有的名词、缩写、内部叫法
资料层的知识量大、种类杂，光靠塞进系统提示词肯定不行——这会撑爆上下文窗口。正确的做法是接入检索增强生成（RAG）：把文档拆成小块，做向量化索引，Agent 在需要的时候按相关性检索出对应的片段，拼接到上下文里。
比较实用的做法是在团队知识库（比如 Confluence、Notion）之外，单独维护一个"Agent 专用知识库"，把高价值的决策记录、复盘文档、架构说明扔进去。内容不求面面俱到，优先收录那些"项目里踩过坑才知道"的知识——这些恰恰是通用模型训练数据里永远不会有的。
2.3 技能层：把高频操作变成"肌肉记忆"
技能层是我自己用了之后觉得提升最明显的一层。它解决的是"Agent 会做，但做得不够贴合你们项目"的问题。
什么叫项目级技能？举个例子。你们项目里有一个自定义的代码生成模板，团队内部约定所有新模块都得按这个模板建，Controller-Service-Mapper-Entity 一套下来，命名规范、异常处理、日志格式都有固定写法。你说"帮我新建一个订单模块"，Agent 如果不知道这套约定，它给出的结构就是通用的三层架构，跟你们项目风格格格不入。
但如果把"新建模块"的完整流程封装成一个技能（Skill），里面写清楚：
- 模板文件在哪
- 生成步骤是什么先后顺序
- 命名规范是什么
- 生成之后要改哪些配置
- 有哪些容易遗漏的检查项
那 Agent 执行起来就是"肌肉记忆"级别的准确。技能层我见过不少团队在尝试了，有人用 LangChain 的自定义工具（Tool），有人用 Claude 的 Skills 机制，也有人用简单的 Prompt 模板 + 脚本组合。形式不重要，核心是把"反复重复且有固定套路"的操作标准化下来。
技能层的维护成本是最低的，因为它是按需调用的——Agent 只有接到对应任务时才去加载对应的技能定义。我目前维护了大概十几个项目级技能，覆盖了模块生成、接口联调、数据库迁移、依赖升级、发布检查等高频场景，日常开发里使用频率非常高。
三明治结构的好处是知识各归其位：规则层放在每天每个会话的上下文里，资料层按需检索，技能层按任务触发。既不互相干扰，也不会因为知识量太大把 Agent 拖垮。
3. 从"能用"到"好用"：Agent 落地前的最后一公里
知识喂进去了，Agent 是不是就能用了？还差一步。我把它称作"最后一公里"——让 Agent 不是偶尔翻到你的知识，而是每次决策都强制参考你的知识。
3.1 别让 Agent"凭感觉"回答，逼它先查资料
我在项目里遇到过很多次这样的情况：知识库已经建好了，文档也喂进去了，但 Agent 回答问题时还是不参考，依然凭训练数据里的通用经验来回答。后来我发现，问题出在"知识消费"的机制设计上。
如果你只是简单地把文档扔给 Agent，说"你需要时可以查阅"，那 Agent 大概率不会查——它可以"凭感觉"直接生成答案，这符合语言模型的本能习惯，毕竟它在训练时就是靠下一个词预测来输出的。你要做的是在 Prompt 层或者工作流层强制它先检索再回答。
我用的办法比较直接：在规则层加了一条硬性约束——"在回答本项目相关的技术问题之前，你必须先从知识库检索相关文档；如果检索结果与你的通用知识冲突，以检索结果为准"。同时在上层应用里调整了 Agent 的执行流程：技术问答这个动作被拆成"检索知识 → 阅读结果 → 结合通用知识 → 组织回答"四个步骤，前面三步是串行强制的，不允许跳过。
效果非常明显。在没加这个机制之前，让 Agent 写一个导出功能，它建议用 POI 直接操作 Excel；加了之后，它先检索到知识库里有一篇"导出功能必须走异步任务、生成后上传 OSS 再推送下载链接"的架构说明，整个方案立刻就不一样了。
3.2 知识要"可检索"，更要"可消费"
建了知识库不等于知识能被有效消费。这里需要说说 RAG 检索的一些细节。
刚开始我图省事，直接把 Markdown 文档整个切成长文本块扔进向量库，结果检索质量很不稳定——相关性高的片段经常排不到前面，Agent 引用的内容经常是"看起来相关实则无关"的段落。
排查后发现几个问题：
第一，切块粒度不对。整篇文档变成一个向量，检索时是"文档级"的命中，但内容不够聚焦。我改成按标题层级切块，每个章节单独建索引，相关性一下子精准了很多。
第二，纯向量检索不够。向量检索擅长语义匹配，但项目知识里很多是"精确匹配"的诉求——比如检索"JWT 过期时间配置在哪"、"数据库连接池参数"，这类问题有明确的关键词。我把检索策略改成关键词搜索 + 语义搜索的混合检索，再用一个简单的重排（Rerank）步骤把两条路径的结果合并排序。
第三，元数据过滤能省很多事。给每块知识打上标签，比如所属模块、文档类型、更新日期，检索时先按标签过滤再相似度排序。这就像在书架上先按分类找书，再在书里翻页，比直接从头翻整本书高效得多。
改完这三处之后，知识库的"调用率"才真的上来了——这个指标是我评估 Agent 落地效果的北极星指标：每次对话里有多少比例引用了项目沉淀知识。引用率高，说明 Agent 真正"用上了"你们的知识资产。
3.3 举个例子：同样写登录，有知识和没知识差别有多大
为了更直观地说明"知识有没有喂进去"的差距，我用自己项目里的真实场景做个对比。
需求：给一个新的内部管理系统加一个用户登录功能。
没有知识库的 Agent给出的方案是：
- 使用 Spring Security + JWT
- 客户端传用户名密码，服务端校验后签发 JWT
- 设置 token 有效期 24 小时
- 前端在请求头里带 Authorization
方案没有问题，但完全没法直接用。因为我们项目的实际情况是：统一认证已经接了公司内部的 SSO + OIDC 协议，新系统的登录不走用户名密码，而是跳转企业微信扫码；服务端拿到 code 换 token，再做本地会话管理；另外安全组有规定，内网系统 token 有效期不能超过 8 小时，并且要支持主动吊销。
这些约束在通用知识里没有，但对我们项目的落地是决定性的。知识库里有相关文档，Agent 检索后给出的方案就完全不同了：
- 接入企业微信扫码登录，走 OIDC 授权码流程
- 服务端用已沉淀的
AuthStateManager组件管理 state 防止 CSRF - 按安全规范设置 token 有效期 8 小时，并接入统一会话管理平台，支持吊销
- 前端路由守卫里按项目现有约定做免登录逻辑
两个方案的差距不是"优化"级别的，是"能不能用"级别的。基于这个对比，我再看到有人说"AI Agent 做不了实际项目开发"，会忍不住想：你确定不是把 Agent 饿着肚子干了一整天的活吗？
4. 最容易翻车的三个隐性坑：知识库不是建了就完事
把知识沉淀给 AI Agent，听起来是"文档 + 向量库 + 检索"这么简单。实际做下来翻车的地方不少，而且每个坑都会实打实地影响落地效果。我想把最常见的三个坑单独拿出来讲讲，因为这些是我踩过之后才真正想明白的。
4.1 知识库的"保鲜期"问题：文档更新滞后，Agent 反而误事
知识库最隐蔽的坑就是过时。项目是活的，每天都在变。三个月前的架构决策可能已经不好使了，上周刚发的规范说明可能这周就改了。如果知识库里的信息没有及时更新，Agent 检索到的是过时内容，它给出的方案就会错得非常理直气壮——毕竟它引用的可是"你们项目自己的文档"。
我经历过一次真实场景，想起来很后怕。问 Agent 项目里某个老模块的接口设计，它检索知识库后给出了答案，看起来完全合理。但那个模块在两周前刚刚做了一次大的重构，接口已经全部改版了。旧文档没有归档、没有标记废弃，Agent 就像那个看了一本过期地图的人，信心满满地把你引向了错误方向。
解决思路不能指望大家自觉更新文档——靠自觉的事最后基本都会黄。我在团队里做了一个简单的方案：文档每周自动检查一次"最近更新时间和对应代码提交记录的匹配程度"，明显滞后的文档会在检索结果里降低权重；同时在知识库操作后台加了一个"内容修订提醒"功能，代码提交信息里带着某个知识库文件的路径，说明这个知识需要重新审核了。
更重要的是，我定了一个规矩：知识文档与代码同源入库。凡是影响技术方案的内容（架构说明、接口约定、部署流程），必须与对应的代码变更在同一个合并请求里提交。这一步把"代码改了但文档没改"的时间差从"永远"压缩到了"提交时"。
4.2 把不该喂的都喂了：知识越权与安全边界
知识沉淀还有一个容易被忽视的问题：知识库不是装得越多越好，尤其是一些敏感信息。
我见过有人把生产环境的数据库连接信息直接写进知识文档里，理由是"方便 Agent 排查问题"。这个想法相当危险——RAG 知识库的访问权限通常只覆盖一小部分人，但 Agent 的对话记录可能被同步给很多协作成员。如果知识库被检索到敏感内容，等于把这些东西直接曝光了。
另外要小心权限控制。不同角色对 Agent 的知识可见范围应当是有差异的——架构师能看到的架构决策、数据库设计，一线开发不应通过 Agent 检索到；测试人员和运维人员需要的知识维度也不同。我给知识库按模块打标签、按角色做隔离：对话发起时先确认用户身份，检索时只对当前身份可见的知识做候选。
还有一条关于合规的底线：个人敏感信息（手机号、身份证号、内部系统的账号密码）不应当作为知识投喂给 Agent 的检索索引。有一次整理知识时差点把 OA 系统的导出功能说明里样例地址给索引了，里面的示例数据是真实的员工个人信息，幸好发现及时。从那次以后我加了一条硬性规则：所有进入知识库的文档必须先过一道脱敏检查。
4.3 知识"没拆开"导致 Agent 迷失在细节里
知识组织不当，Agent 会"只见树木不见森林"。我把一整份系统设计方案原封不动地扔进知识库，几十个章节拆成几百个向量块。等到 Agent 面对"用户改密码的流程是啥"这种问题时，它检索到的可能是市面上常见的通用流程，项目里特殊的"密码必须先发短信验证 + 历史密码不能重复用最近五次的"这个关键约束，被淹没在庞大的设计方案里了。
后来我的做法是给每份文档写一个**"摘要块"**：用三到五行话概括这份文档讲的核心结论，单独切成一个向量块放最前面。摘要块明确标注"这是文档的结论，优先参考"。这样 Agent 检索到一个主题时，最先命中往往就是摘要块，直接拿到结论；需要细节时再继续检索正文内容。这个"先结论后细节"的知识组织方式，穿透力比直接堆正文好很多。
另外，不同主题的知识不要混在一个文档里。我有一次把"代码规范"和"部署流程"写在同一篇文档里，Agent 在回答部署问题时检索到了代码规范片段，整个回答风格完全跑偏。拆开成独立文档，让检索主题更聚焦。
5. 一次真实"知识没喂对"的返工：排查链路完整复盘
前面讲的都是方法论，这一节我想把一次实践过程完整复盘一遍。这是我自己项目里真实发生的事——虽然最后解决了，但过程很能说明"知识喂给 Agent"这个事的核心难点在哪里。
5.1 现象：Agent 给了一个"完全正确但项目用不了"的方案
背景是这样的：项目要接入一个第三方支付渠道，我让 Agent 帮我写一版对接方案。当时我的知识库已经建好，里面放了支付模块的架构设计文档、接口约定、已有的支付渠道对比分析。
Agent 输出的方案写得非常好，结构清晰、时序合理、异常处理考虑得很周到——如果不了解我们项目，简直挑不出毛病。但它有两个致命问题：
第一，它推荐的支付渠道是 A 平台，理由是"接入成本低、文档完善"。但知识库里的渠道对比分析明确写过：A 平台在海外网络环境下不稳定，公司已经决策统一使用 B 平台，而且这个决策是在季度技术评审会上由架构组定的。
第二，它设计的回调处理逻辑是"同步修改订单状态 + 异步通知业务系统"的通用方案，但项目的实际架构里，订单状态变更必须走消息队列，由订单服务订阅消费，不能直接在回调里改库——这是为了避免分布式事务问题，知识库里有一篇专门的复盘文档讲这件事。
方案里每一句话都对，但合在一起不是我们项目能用的方案。这就是典型的"知识没喂对"的症状。
5.2 排查链路：为什么知识对了，Agent 还是没用到
开始排查之后，我按"知识有没有 → 检索能不能命中 → 命中后会不会用 → 用了会不会被别的约束覆盖"这个链路一步步查。
第一步查知识在不在库。我打开知识库后台，确认"支付渠道选型决策"和"订单状态变更架构说明"两篇文档都在库里，最近更新日期也正常。知识本身没有问题。
第二步查检索能不能命中。我把 Agent 当时收到的问题原样输入检索接口，看返回的前十条结果。这一查就发现问题了：排在最前面的几条都不是我要的文档片段，"渠道选型决策"排到了第十四位，"订单状态变更架构"排到了第九位。而排在前面的，全都是通用性的支付流程、支付安全规范这类内容——它们是训练数据里常见的通用知识，跟项目文档语义相似度也很高，结果把真正的项目知识挤到了后面。
第三步查Agent 拿到检索结果后怎么用。看对话中间过程的日志，Agent 确实检索了，但引用的是排名靠前的通用内容，真正的项目知识根本没进入它的有效上下文。再回头看当时的检索设置，向量化用的嵌入模型对中长文档的支持不够，切块后每个块丢失了很多上下文信息，导致语义匹配几乎失效。总之"知识在库，但检索没命中，Agent 于是退回到通用知识去发挥了"。
第四步查是不是被系统提示词里的其他约束覆盖。我检查了规则层文件，里面有一条"遵循业界标准方案"的约束，本来想表达的是"方案要规范"，结果在 Agent 看来成了"优先使用通用做法"的授权信号。规则层的话术会产生反效果，这是我完全没有预料到的。
5.3 修复方案：三个动作一次到位
三个问题分开修。
第一个动作，调整检索策略。放弃之前用的单一向量检索，改成 BM25 关键词检索和语义检索的混合检索，再用一个轻量的 Rerank 模型对两路结果做重排。改造之后，上述两篇关键文档在检索结果里的排名进到了前三。
第二个动作，优化切块策略。把按固定字符切块的逻辑改成按 Markdown 标题层级切块，保留小标题作为上下文锚点；同时把"摘要块"放在文档最前面作为第一优先级命中的内容。这样像"支付渠道选型决策"这篇文档，摘要里就写着"已确定统一接入 B 平台，A 平台不在考虑范围内"，Agent 一检索就能直接拿到结论。
第三个动作，修订规则层的话术。把"遵循业界标准方案"改成"在项目知识有明确规定时，以项目知识为准；在项目知识未覆盖时，再参考业界通用方案"。语气变了，约束的方向就变了，Agent 不会再"自作主张"地偏向通用方案。
修复之后重新跑了一遍同样的需求和问题，Agent 给出的方案基本可以直接用了，而且给出了关键理由："根据知识库中渠道选型决策，本方案基于 B 平台进行设计。"虽然这句话在成品方案里可以删掉，但从 Agent 的逻辑可以看出来，它的确是把项目知识当作决策依据了。
5.4 复盘：知识沉淀的关键不是"存储"，是"消费链路"
这次返工给我的启发很明确：知识沉淀真正要解决的不是"知识存在哪里"，而是"知识从存储到被消费的整条链路"。知识做得再好，检索命不中，就等于没有。而检索命中了，Agent 引用不当，也等于没有。
排查的时候还有个发现让我印象很深：当时知识包里除了支付相关的文档，还放了十几篇其他模块的内容，整个库的向量索引里项目知识的密度被稀释了。后来我把知识库按模块拆成了多个子库，并给 Agent 配置了"路由规则"——根据当前任务主题决定检索哪个子库。这个调整之后，检索命中率整体提高了不少。知识不在于多，而在于需要的时候能精准地拿到那一条对的。
6. 把"知识即代码"作为长期习惯
写到这里，整套方法的核心已经讲完了。最后再聊一个我自己的体会：知识沉淀这件事，一定要当成代码工程来做，而不是文档任务来做。
代码有版本管理、有 Code Review、有测试、有发布流程，但大多数团队的知识文档连最基本的版本管理都做不到——改完了就覆盖，旧版本找不回来，谁改的、为什么改，一概没有记录。这跟知识沉淀的诉求完全是背道而驰的。
我现在把项目知识跟代码放在同一条流水线里管理：项目手册、架构说明、决策记录、技能定义，全部以文本文件形式放在 Git 仓库里，参与 Code Review，随代码一起发布。规则层文本改了要走评审；技能定义改了要跑一次"技能自检"——其实就是让 Agent 在沙箱环境里按新技能定义跑一遍流程，验证没有语法错误和执行逻辑混乱；资料层的文档更新必须关联到对应的代码变更。
这个习惯的养成有个很实际的好处：知识会自然跟着项目的演化而演化。代码重构了，知识文档在同一次变更里更新，不会出现"方案文档还停留在上一代架构"的情况。新成员入职，不是去看一本可能已经过时的 wiki，而是直接基于 Git 历史回溯每个决策的上下文。
再分享一个小经验：给 Agent 用的知识文档，最开始写得越短越好。这不是偷懒，是因为知识需要先跑起来，再变厚。跟写代码一个道理，一上来就追求大而全，往往跑不动。先放三五篇最核心的文档，跑通"规则 + 资料检索 + 技能触发"的完整链路，再逐步补充更多内容。链路没有跑通之前堆再多的知识都是死数据。
最后说回标题里那四个字——知行合一。AI Agent 能不能让项目落地"知行合一"，取决于你自己有没有先做到知行合一：既要"知道"知识该沉淀，也要"做到"把知识消费链路跑通。知识库建了不去喂、喂了不去检索、检索了不去修正引用，每一层都打了折扣，Agent 给你交回来的自然也是打了折扣的"八股文"。反过来，每一层都卡到位了，它的输出会越来越贴合你的项目，到那个时候你会明显地感觉到：它不是在做题了，它是在干活了。
