“AI智能体在复杂代码库里改代码改着改着就开始胡言乱语、乱删文件、把A模块的变量名套到B模块上”——这个场景在2025年已经不算新闻了。随着AI编程助手从“单文件补全”进化到“跨仓库任务执行”一个尴尬的事实摆在所有团队面前基座模型的推理能力在提升但智能体在一堆互相耦合的旧代码里依然像金鱼一样——只有七秒记忆。我去年带团队做内部智能体工具链时在这上面栽过不少跟头。一开始以为是模型不够强后来换了更强的模型问题依旧。直到我们开始把“上下文”当作一个正经的工程问题来治理效果才出现质的飞跃。这篇文章就是把我们这一路踩坑、试错、沉淀出来的方法做个梳理主要面向正在做AI编程助手、代码智能体或者准备把AI接入存量代码库的工程师。如果你以为这又是一篇讲“怎么拼Prompt”的文章那可以关掉了——上下文工程远不止写Prompt那么简单。1. 为什么强模型在复杂代码库面前也“智商掉线”问题不在推理在上下文先把根子上的问题说清楚。很多团队面对AI智能体在代码库中表现不佳的第一反应是换更大的模型、或者堆更详细的指令。但实际测试下来模型在单文件、小项目上确实聪明得吓人一旦放进一个几十万行、模块间靠隐式约定互相调用的老项目里立刻原形毕露。这不是模型变笨了而是它的上下文窗口里装的“料”出了问题。现在的智能体执行一个稍微像样点的任务——比如“给订单服务加一个超时熔断”它可能要翻阅十几个文件、理解好几层调用链、还要记住项目里约定俗成的错误处理风格。如果这个过程只是把一堆文件一股脑塞进上下文大概率会出现三种典型症状注意力稀释真正的关键逻辑被淹没在大量无关的样板代码里模型被噪音干扰抓不住重点。事实冲突不同文件里的旧接口签名和新调用方式互相矛盾模型一会听A文件的一会听B文件的改出来的代码自己都圆不上。短期遗忘虽然上下文窗口理论上有几十万token但模型对“离当前修改位置较远”的信息注意力会自然衰减经常前面刚分析完调用链后面改代码时就忘了。打个比方这就好比让一个顶级外科医生做手术但他面前摆的不是一张清晰的手术图谱而是这座医院过去十年的全部病历堆。医生能力再强也没法在纸堆里高效找到他要切开的那根血管。所以核心结论先摆在这智能体在复杂代码库里的可靠性不取决于你能塞进多少上下文而取决于你能否让它“在正确的时候只看到正确的那一小撮上下文”。这也是“上下文工程”这个说法存在的意义——它不是Prompt Engineering的换皮而是指对模型所见信息进行采集、筛选、压缩、编排的一整套系统设计。1.1 从“长窗口崇拜”到“上下文预算”一个反直觉的指标我们团队早期犯过一个错就是被厂商宣传的“超长上下文”带着走总觉得窗口越大越好。后来做了一批对照实验发现了一个反直觉的结论在两千行以内的中小型代码库上超长上下文确实能提升任务完成率但一旦代码库规模超过五万行盲目的塞入反而导致任务成功率明显下滑。后面的分析也印证了这个判断——不是窗口不够大而是窗口里的“信噪比”太低了。模型需要从海量无关内容中自行筛出关键依赖而这一行为本身就消耗了模型的注意力和推理资源。所以我更建议团队给自己的智能体设立一个“上下文预算”的概念不是“这个任务最多能喂多少token”而是“这个任务最少需要哪些信息”。把上下文当稀缺资源来管理这算是上下文工程的第一性原理。2. 上下文采集层先把代码库变成智能体“看得懂”的知识图谱要想让智能体能做到“只看到该看的”首先得让它知道“代码库里有什么、分别在哪儿、彼此什么关系”。这一步我习惯称为上下文采集层也是整个上下文工程的地基。大多数团队的现状是代码库没有经过任何结构化处理直接裸奔给智能体。效果基本靠赌赌模型的代码检索能力足够强。但实际情况是模型的代码检索只是在做“关键词/符号名匹配”根本理解不了“这个Service为什么依赖那个Repository”、“这两个Module之间为什么不能互相引用”这类架构层面的信息。2.1 代码库地图Repo Map的生成与维护我们最早的方案是让智能体在接到任务时先去根目录读一遍README和目录结构。后来发现这个方案太脆弱了——README经常过时目录结构只能反映物理分层反映不了真实的调用关系。后来参考了一些开源IDE插件的思路实现了一个轻量的代码库地图生成器把项目解析成抽象语法树AST提取出所有模块、类、函数、接口以及它们之间的导入关系、调用关系、继承关系。再按模块聚合生成一个带“依赖边”的拓扑图。最关键的一步是要把这个拓扑图压缩成一个精简的文本摘要而不是把整棵AST扔给模型。这份“地图”的体感大致如下一屏能看完的模块清单模块名、职责一句话、对外暴露的关键接口模块之间的依赖箭头只标跨模块的不标函数内部的细粒度调用全局可能用到的公共约定错误处理风格、命名规范、配置加载方式无论任务是什么这份地图始终是喂给模型的第一层上下文。相当于给模型发了一张“游乐园导览图”它才知道接下来该往哪个方向走而不是进了园区瞎转。2.2 语义分块比“按行截断”优雅得多的切法很多团队在做知识库时喜欢“按字符数截断”或者“按文件硬切”这两种方式对代码库场景都有问题。按字符截断会拦腰砍断一个函数的定义和它的文档字符串按文件硬切又会把一个大文件里几个无关逻辑硬绑在一起。我们后来实践下来效果比较好的是“结构感知分块”——以函数、类、方法为单位保留它们的完整签名、文档注释和函数体再打上元信息标签所在文件、所属模块、定义位置、被哪些地方调用。这样分出来的每一块都自带上下文锚点。这一步做没做扎实直接影响后面检索的准确率。打个比方同样是检索“支付超时”按关键词硬搜可能出来一堆“timeout”相关的无关代码但结构感知分块后检索系统能理解“这是一个处理支付超时异常的函数”召回结果精准得多。2.3 增量索引代码库天天在变地图不能是张旧图纸代码库和静态知识库最大的不同是——它是活的。每天都在产生commit开发分支同时有好几个。如果代码地图和索引是离线一次性生成、定时重建的那智能体拿到手的很可能是一张过期图纸照着改着就出事故。所以我们的实践里上下文采集层必须挂在代码托管平台的Webhook上每次提交、每次合并请求触发时做增量更新。只重新解析变更涉及的文件同时维护一个失效标记关联到受影响的模块和函数。这样智能体看到的代码地图永远比代码库实际状态落后不超过几分钟。千万别小看这一步。我们在内测阶段就遇到过两次事故都是因为索引过期智能体对着旧接口写代码编译期都过不了。这玩意儿做扎实之后整体可靠性提升是立竿见影的。3. 上下文检索层别逗“关键词搜索”了要的是“精准定位”有了结构化的代码知识下一步就是在智能体执行任务时按需把最相关的上下文捞出来塞进窗口。这一层我称为检索层。市面上这类工具已经不少了但很多团队抄回去效果不好原因在于没有搞清楚代码检索和普通RAG检索的核心差异。3.1 代码检索的“双通道”符号图谱 语义嵌入纯靠向量相似度的RAG在代码场景下容易翻车。代码里的“相似”和自然语言里的“相似”完全是两码事。两个函数做的事情类似但变量名和注释风格完全不同向量相似度可能很低。反过来两个函数只有变量名有点像实际功能毫无关系向量上又可能莫名挨得很近。我们的做法是“双通道检索”缺一不可通道A符号检索精确但窄。基于前面建的AST索引支持按符号名精确查找包括类名、函数名、参数名、导入路径。这个通道速度快、零幻觉适合已知目标名字的场景。通道B语义检索宽但不精。用嵌入模型对代码块做语义向量化支持用自然语言描述去搜相关代码。这一路主要用来处理“我不知道具体符号名但我大概知道我要做什么”的场景。两个通道的结果做加权融合再按“引用热度”和“与当前任务的隐式关联”重排。一个很实在的优化是提升“被引用量高的符号”权重——因为高引用量的方法通常承担着核心业务逻辑被需要的概率也更大。3.2 一个被低估的参数检索结果的数量和密度做RAG的同学都熟悉一个词叫“TopK”但在代码场景里我劝你先别急着抄超参数。我们在测试中发现对一个三五十万行的工程给智能体一次性注入超过10个文件的信息它的判断力就开始明显下降注入超过25个文件时错误率几乎成倍增长。所以现在我们的策略是“金字塔式供给”第一轮先给地图和任务描述让智能体自己提“我要看哪个文件”如果需要再按它提的需求精准返回对应函数、对应依赖的子片段。这套交互虽然多了一轮但效果比一次性把所有可能相关的文件全塞进去要稳得多。另外一个很反直觉的经验是对于“明星文件”几百上千行的核心模块一次性把整个文件塞进去反而不如只给“这个文件对外暴露的接口签名近期变更记录”好用。细节需要看的时候再展开这比让模型先啃完整文件再找重点要高效得多。3.3 检索质量怎么度量别只看“召回率”要看“任务完成率”做工程的人都有个习惯——拿离线评测集来量化效果。但代码检索这个环节光看“召回的代码块和标准答案的重叠度”是不够的。因为代码任务的成败与否在“下游”你要是给模型检索出来了正确文件但摘掉了它的关键函数那召回率再高也白搭。所以我们的评测体系里除了召回率、准确率这类传统指标还加了一个“端到端任务成功率”的指标池。具体做法是拿一批真实的历史Issue我们修过的、能追溯正确提交的做成回归集。每次改动检索策略、调整分块逻辑、改重排公式都要拿这个回归集跑一遍端到端任务看最终生成的代码能否通过同样的单元测试。所有离线指标过了都不算数端到端跑通了才算有效。4. 上下文的组织与传递怎么把“找到的资料”编排成“模型的行动指南”检索做得再好如果上下文塞进窗口时是一团乱麻模型依然会懵。这一层是上下文工程里最“软”但也最容易被忽略的部分——上下文组织。我们内部有个口号“上下文不是资料的堆砌而是模型的行动指南。”4.1 信息分层从“全局约束”到“局部细节”再到底层代码实际喂给模型的上下文我们按重要程度分成三个层次约束层优先级最高约几百token。任务目标、完成定义、必须遵守的架构约定、禁止触碰的红线模块。比如“新增接口必须遵循现有的RESTful风格”、“改支付模块时不许碰账户模块的数据库表”。这些是模型的“军规”放在最前面确保它不会跑偏。导航层第二层地图依赖链。这部分就是前面说的代码库地图的浓缩版加上和当前任务相关的模块依赖链。帮助模型建立“我要改的这个文件在整个系统里处于什么位置、我的改动会影响谁”的全局认知。细节层第三层按需展开的具体代码。这一步才是放具体函数、具体类实现的片段。并且另外加一层“防呆机制”——如果某个文件被引用次数过多我们会主动提示模型“这是高频共用模块修改需格外谨慎优先考虑扩展而非修改。”4.2 别让模型“猜”代码意图显式标注比优美行文更重要每个代码片段进入上下文时我们都会强制附加几行元信息而不是光秃秃地贴代码。举个例子文件位置src/services/order-service.ts订单微服务 职责订单创建、状态流转、过期未支付关闭 对外依赖payment-client支付客户端、inventory-client库存扣减 关键约束所有对外暴露方法必须捕获内部异常并转为OrderErrorCode不得直接抛底层异常这行文字看起来普通但对模型的效果提升非常明显。因为模型不需要再自己“阅读理解”代码意图了遇到相关异常处理问题时直接就有现成的规范给它参考。这个做法是我们内部一致认为“性价比最高”的一条优化——几乎不增加任何工程成本但对模型生成结果可靠性的提升非常显著。4.3 上下文压缩长对话协作中的“记忆整理术”智能体在一个任务上卡壳、反复试错时对话轮次会不断增长历史里塞满了失败的尝试和废弃的方案。如果不做整理模型会被自己之前犯的错带偏。我们的做法是引入一个“对话记忆管理器”每当对话超过一定轮数就对历史做一次摘要压缩。只保留“当前状态”、“已验证的方法失败原因”、“下一步计划”三个字段其余全部丢弃。这个设计参考了人类的记忆机制——长期工作记忆只需要保留结果和结论过程细节随时可以被丢弃。这个小机制特别顶用。有一次我们让智能体修一个并发bug它前面五六轮排查方向全跑偏了但压缩后下一轮它突然跳出了之前错误的框架很快就定位到了真正的问题。看起来像“顿悟”其实只是——它终于不用被自己前面的错误假设反复套牢了。5. 工具与工作流设计为什么智能体改代码比写代码更容易翻车进入这一节之前先说一个观点我们做上下文工程最终的落地载体并不只是一个RAG系统而是一套由检索、地图、记忆管理、任务拆解共同组成的智能体工作流。代码智能体要可靠工作光有上下文信息还不够它得有一套明确的工作流协议。5.1 先规划后动手把“让模型直接改”变成“让模型先说怎么做”复杂的代码库任务面前如果一上来就让模型天马行空地生成一大堆代码改动翻车概率非常高。我们后来强制加入了一个“规划步骤”而且是写在系统提示词最前面优先级极高。流程是这样的智能体收到任务后第一步不是写代码而是先输出一份“行动计划”包括我要改哪些文件、加哪些函数、动哪些模块为什么这么改附上代码地图里的关键依赖证据预计影响哪些调用方有没有兼容性风险如果这份计划存在明显问题比如它要动的模块和任务需求冲突这时候让人工review或让校验器拦截成本远低于等它全部改完再让人工review。而且就我们观察强制先做规划后写代码这个步骤本身就能让最终生成代码质量提升不少——因为规划过程就相当于让模型自己先把思考链条理顺了而不是直接凭感觉输出。5.2 工具协议的边界让智能体“只动它该动的”控制智能体在代码库上的“破坏面”是第二个关键点。我们内部给智能体定义了严格的操作边界只允许通过标准工具接口改文件不允许直接写任意路径改文件前必须先diff预览、再写变更说明、然后才落盘每个文件改动都要记录“为什么改”的原因方便回溯熔断机制如果单次任务想改超过10个文件或者改到了敏感模块比如核心支付逻辑强制进入人工审核状态这套协议的本质是“最小权限原则”代码智能体不需要有对整个代码库的无限写权限给它授权之前先确保它是真的需要动这些地方。5.3 验证闭环上下文工程不是“喂完资料就完事”最后也是最重要的——上下文工程必须有闭环验证。我们内部每条任务完成的必经之路是跑单元测试、跑静态检查、检查是否满足架构约束比如是否违规新增了跨层调用。只有三轮全过了任务才算“可接受完成”。这一条看着像废话但我和不少团队交流时发现很多智能体Demo阶段看着完美一到生产就崩就是因为他们只做了“检索生成”完全没有“验证-反馈”的闭环。没有闭环智能体就没有纠错的机会当然也没法从纠错中学习。6. 回看一路踩的坑那些文档里不会告诉你的上下文工程教训因为前面每一节多少都掺杂了实战教训就不做系统性重复了。这里挑几个尤其容易忽略的点再单独拎出来讲。6.1 教训一别迷信“自动检索”必要的时候给智能体一个“人工指路”的入口这可能是从很多产品里学到的看似“倒退”的做法——对于关键任务不再完全依赖智能体自己去检索上下文而是允许开发者在任务开头手动指定“你优先看这几个文件”。就这一步我们在某些核心模块的任务上效果拔群。原因其实也好理解。有些架构约束、潜规则并没有文本化石在代码库里。靠检索永远检索不到“为什么这里不能用async”这类隐性知识而开发者脑子里有。给一个手动注入入口相当于在上下文工程中打通了“隐性知识显性化”的最后一公里。6.2 教训二伪代码/注释也是上下文的一部分但优先级要不一样代码库里的注释和文档信息密度差异极大有高质量的设计文档也有“TODO: fix this later”这种无意义注释。如果检索时一视同仁很容易把“顶级噪音”喂给模型。我们的做法是分析注释的“信号强度”能解释业务原因、设计选择、调用约定的注释标记为高优git提交信息、变更记录中的背景说明次之“TODO”“FIXME”这类再降权。这个优先级写在检索排序的公式里不算什么高深技术但对最终效果影响还真不小。6.3 教训三上下文工程要和“人的工作流”融合而不是替代最后想提醒一句——上下文工程再完善它服务的对象依然是“人机协作”这个更宏观的命题。我们在一开始踩过一个产品方向上的坑试图做一个“全自动修Bug智能体”目标是开发者在旁边看着就行。结果每次它出错误开发者的信任度就掉一层后来大家干脆不用了。转折点是重新定位产品的方向从“全自动修Bug”改成“智能副驾驶”的定位——它负责自动检索相关资料、生成初步修复方案、圈定影响面而开发者根据自己的经验判断是否采纳。就这个小改动内部使用率直线上升项目也从Demo阶段活到了生产环境。原因不复杂上下文工程提升的是“信息获取和方案形成的效率”但最终决策权还是要留给开发者。智能化不是把人赶出决策环而是把人从机械劳动中解放出来让他把精力集中在他最该做的事情上——判断、决策、把控方向。现在我们的智能体每天都在处理真实需求从修bug到加功能、从重构到写迁移脚本稳定性已经做到相当可用了。但我始终会提醒自己和团队每一次让我们工作更顺利的优化几乎都和“让上下文更精准”有关而不是“让模型更大”。把上下文当产品做把智能体当员工带——这大概就是上下文工程最好的总结。