3层索引让AI少烧47%算力：Claude团队没说的秘密

每开一次对话，Claude都要把同一批文件读一遍。Codex重新发现同样的插件模式。Gemini问同样的文件夹结构问题。

模型不慢，是每次都在从零开始。

开发者们以为瓶颈在模型智商。真相更朴素：缺一张地图。

探索税：每个会话都在重复交学费

多智能体工作流里，每个代理开场都要付一笔"探索税"。动手之前，它得先搞清状况：插件系统在哪？命名规范是什么？哪些文件被子树管理、碰不得？前人做过什么决定？

小项目里这叫烦人。大项目，或者多个代理并行跑的时候，这就是token的坟场。

常规解法是塞个CLAUDE.md或AGENTS.md，用散文描述代码库。有点用。但散文是被动的——代理读完还得自己映射到要改的文件。这是README，不是地图。

索引和文档是两回事。

文档解释。索引定位。

代理需要的不是"插件系统概述"这种段落，而是："公开函数放scripts/plugins/，禁止下划线前缀。scripts/k3d-manager里的调度器懒加载它们。以下是现有插件及其公开函数。"

这叫可导航。代理读完直奔正确文件，带着正确模式，零探索。

Cline的隐藏用法：不当码农，当侦察兵

原作者的发现很刁钻：Cline有持久记忆，能跨会话维持对代码库的结构化理解。不拿它写代码，专门让它当侦察代理——读仓库、建结构化地图、持续更新。

其他代理消费这张地图。它们不再重新探索。

这个思路的精妙在于角色分离。写代码和读代码是两种认知负荷，混在一起就是浪费。让Cline专职做索引，相当于给团队配了个从不休息的架构师，记忆不会随会话清空。

三层的索引结构被验证有效：

结构层——东西在哪、为什么在这：

scripts/
k3d-manager # 调度器——把函数名映射到插件文件
lib/ # 核心库；通过lib-foundation子树管理
plugins/ # 懒加载模块；一个工具一个文件
tests/ # BATS测试套件；纯逻辑，无集群mock

契约层——代理必须遵守的规则，编码为事实而非建议：

- 新插件：scripts/plugins/.sh
- 公开函数：禁止下划线前缀
- 私有函数：_前缀
- 特权命令：_run_command --prefer-sudo，禁止裸sudo
- if-count限制：每函数≤8个；例外见etc/agent/if-count-allowlist
- 子树管理区：scripts/lib/foundation/——只改上游

状态层——进行中、已决定、被阻塞：

活跃分支：k3d-manager-v0.9.17
当前任务：_antigravity_ensure_acg_session
阻塞于：lib-foundation v0.3.14（5处修复待合并）

为什么契约层要"编码为事实"

原文有个细节很毒：规则要写成"新插件：scripts/plugins/.sh"，而不是"新插件应该放在scripts/plugins/目录"。

差在哪？代理对建议性语言的理解成本更高。"应该"需要推理，"："是定位。每减少一次推理，就少烧一波token。

if-count限制≤8这种具体数字也很有意思——作者团队显然踩过坑，知道代理写代码容易嵌套过深。把经验硬化成规则，下一代代理直接继承，不用重新踩。

子树管理区的标注更实用。很多代码库有"看似能改、改了出事"的灰色地带，代理尤其容易误触。明确标出"只改上游"，相当于在地图画禁区。

状态层的真正价值：中断续传

最被低估的是第三层。开发的真实场景不是"从零开始写功能"，是"昨天写到一半，今天接着来"。

代理没有人类的上下文记忆。昨天定的方案、踩的坑、临时绕的路，今天全忘。状态层强制把"当前任务"和"阻塞点"写成结构化数据，相当于给代理做了人工冬眠——唤醒时注射全部上下文。

lib-foundation v0.3.14那5处待修复，人类开发者扫一眼就知道今天能不能推进。代理也一样。

这套机制跑通后，原作者没给具体数字，但描述很直白：其他代理消费地图，不再重新探索。翻译成人话：每个会话省掉的开场勘探，累积起来就是算力账单上的真金白银。

现在的问题是：你的代码库有这张地图吗？还是你的代理们，每次都在盲人摸象？