生成压缩索引，让编码代理真正靠谱了

有个软件项目需要给编码代理一份紧凑的文档索引，比让它现搜答案表现好太多。他们的评估结果是——用“地图法”（索引法）任务成功率100%，而让代理主动查找时只有79%。

同一个代理，同样的任务，就上下文处理方式不同。这就是能跑通和跑不通的区别。

我立刻明白了关键：要是能让Claude Code稳定获取这些内部知识，还不用它自己决定啥时候查资料，那人们在我们代码库里干活的方式就得彻底变样。

所以我们动手做了。

上下文的问题

编码代理有令牌限制——一次能处理的信息量有天花板，就像人的工作记忆。你没法一次性把整个代码库和文档库都甩给Claude Code，太多了。

传统解法是给代理“查找技能”：让它自己判断啥时候需要信息，主动去搜。“我得了解认证机制，搜一下这个。”听着合理，实际却有三个坑：

1. 决策瘫痪：代理得琢磨啥时候该查文档，经常猜错；

2. 异步延迟：每次查找都是一次往返请求，打断思路；

3. 顺序冲突：探索代码和查文档的时机老打架。

Vercel的法子反着来：让Claude Code开工前，先拿到一份压缩过的文档索引——哪些文档存在、在哪儿找。索引小到每轮对话都能塞进上下文，所以它时刻知道有啥可用。真需要细节时，直接读具体文件。不用决策，不用查找，没冲突。

为啥压缩这么重要

核心创新就在“压缩”。完整的文档树（所有文件夹结构、文件名、分类）占地方不小，每轮对话都加进去就太臃肿。

我们用简单的管道分隔格式压缩索引，能缩掉约80%：

[epilot文档索引]|根目录: ./.epilot-docs|00-通用:{tech-stack.md, business-context.md, ci-cd.md}|01-API:{api-design.md, calling-apis.md}|02-epilot360微前端:{env-vars.md, local-dev.md}|...

这一行就告诉代理：

• 文档在哪儿（.epilot-docs/）

• 分了哪些类（00-通用、01-API等）

• 每类里有啥文件

这就像目录，不是整本书。但够了。代理看了“地图”就知道有啥可用，需要时直接拽具体文件。决策负担没了。

这事儿为啥重要

准确率提升确实明显（100%对79%），但不是重点。

重点是“降低贡献门槛”后会发生啥。有了对的上下文，最懂问题的人就能直接修，不管头衔是啥。产品经理能修bug，设计师能调组件行为，支持工程师能补数据漏洞。瓶颈没了——上下文和权限集于一人。

编码代理是平衡器，但效果全看你给的上下文咋样。

多数公司会把Claude代码扔到代码库上，然后纳闷结果为啥时好时坏。代理瞎编模式、做错误假设、写出不符合规范的代码……差的就是上下文：关于代码库怎么运作的结构化、压缩过、随时可用的上下文。

咋自己搭一个

方法很简单，说下我们在epilot的做法：

1. 整理代理友好文档：梳理内部知识——规范、API、架构模式、框架用法、代码风格；

2. 按领域分类：把相关文档归组（通用、后端、前端、基建等）；

3. 用描述性文件名：代理在压缩索引里先看文件名再开文件。api-design.md比guidelines.md强，error-handling.md比errors.md清楚。让文件名可搜且具体；

4. 自动更新：尽量拉实时数据（OpenAPI规范、模式定义、框架文档）；

5. 生成压缩索引：用简单格式（管道分隔就行），把文档树缩掉约80%；

6. 嵌进代理上下文：把索引加到CLAUDE.md或AGENTS.md里——这是Claude代码启动时读的上下文文件。

   
   

划重点：我们不仅放内部文档，还打包了重度用的框架和库文档（single-spa、openapi-backend、i18next、Volt UI等）。Claude Code想知道i18next复数咋处理、咋注册single-spa微前端，答案已经在那了。不瞎编，不用过时Stack Overflow帖，只有准的框架文档。

这能带来啥

团队已经在天天用：开发切换不同服务上下文更快，非工程师直接贡献代替提工单。

但真正潜力更大：既然压缩上下文对技术文档有用，为啥不扩展到别处？

• 操作手册和事件响应：值班工程师秒获应急流程；

• 客户领域知识：支持团队掌握产品行为上下文；

• 业务逻辑：保存产品决策及其依据，随时可查。

模式都一样：梳理知识→压缩→嵌上下文→让代理干活。

门槛正在消失

几十年了，参与代码库得有深厚技术知识——懂语言、框架、架构模式、隐性规范，门槛高得很。

编码代理把它降低了。Claude Code、Cursor这类工具不取代工程师，是让技术知识更易获取。有了对工具和上下文，产品经理能修bug，设计师能调样式逻辑，支持工程师能补数据漏洞。

问题不是“能不能”，是“你能多快适应”。

能让更多人贡献的组织跑得更快。工具现成，研究也清楚，缺的是执行。

从简开始

不用一开始就全写完，从最让人头疼的知识入手：

• 代码风格规范（TypeScript写法、命名模式、文件结构）；

• 常见模式（认证、API调用、错误处理咋搞）；

• 框架细节（不明显的用法）；

• 内部API（有OpenAPI规范更好）。

  
  

建个简单文档结构：

docs/  
  00-通用/  
    code-style.md  
    tech-stack.md  
  01-API/  
    api-design.md  
    calling-apis.md  
  02-后端/  
    error-handling.md  
    database-patterns.md

生成压缩索引（管道分隔，每个目录一行），加到CLAUDE.md或AGENTS.md里——Claude代码启动时读的上下文文件。搞定。

压缩索引法管用！🎉 Vercel研究证明了：用它任务成功率100%，不用只有79%。我们在内部验证过了。现在就看你比竞争对手早不早用上了。