你的 AI 代理正在盲目探索。教你如何为它们提供地图。

Source: Dev.to

Source: …

探索税

在多代理工作流中，每个代理在每个会话开始时都要缴纳探索税。在它能够做任何有用的事情之前，它必须先定位自己：

• 插件系统位于何处？
• 使用哪些命名约定？
• 哪些文件是子树管理且不可触及的？
• 已经做出了哪些决策？

在小型代码库中，这仅仅是令人烦恼而已。而在大型代码库——或是有多个代理并行运行的情况下，它就是令令牌消亡的地方。

常见的解决办法是编写 CLAUDE.md 或 AGENTS.md，用散文描述代码库。这有帮助，但散文是被动的。代理仍然需要将描述映射到它将要触及的文件上。这只是 README，而不是地图。

索引到底是什么

• 文档 解释。
• 索引 定位。

我们希望代理程序一开始看到的不是关于插件系统的段落——而是一张具体的地图，例如：

“Public functions go in scripts/plugins/. No underscore prefix. The dispatcher in scripts/k3d-manager loads them lazily. Here are the current plugins and their public functions.”

这是一种可导航的形式。代理程序可以直接读取它，立刻定位到正确的文件和相应的模式，而无需进行探索。

使用 Cline 作为索引器的背后理念：Cline 具备持久记忆，能够在多个会话中保持对代码库的结构化理解。我们并不是把它当作代码生成器来使用，而是将其作为专职的侦察代理——其任务是读取仓库、构建结构化地图并保持更新。随后其他代理只需使用这张地图，而不必再次进行探索。

索引包含内容

一个有用的代码库索引包含三个层次：

结构 — 位置与原因

scripts/
  k3d-manager       # dispatcher — maps function names to plugin files
  lib/              # core libraries; subtree‑managed via lib‑foundation
  plugins/          # lazy‑loaded modules; one file per tool
  tests/            # BATS suites; pure logic, no cluster mocks

合约 — 代理必须遵循的规则，以事实而非建议的形式编码

- New plugins: scripts/plugins/.sh
- Public functions: no underscore prefix
- Private functions: _ prefix
- Privileged commands: _run_command --prefer-sudo, never bare sudo
- if‑count limit: ≤ 8 per function; see etc/agent/if-count-allowlist for exceptions
- Subtree‑managed: scripts/lib/foundation/ — edit upstream only

状态 — 正在进行、已决定、被阻塞的内容

Active branch: k3d-manager-v0.9.17
Current task: _antigravity_ensure_acg_session
Blocked on: lib‑foundation v0.3.14 (5 fixes pending)

第三层已经由 memory-bank/activeContext.md 提供。前两层则是 Cline 可以自动生成和维护的内容。

工作流程

模式：

1. Cline 只索引一次 – 读取完整代码库，生成 docs/index/structure.md 和 docs/index/contracts.md，并将其提交。
2. Cline 在更改时更新 – 当文件移动或模式变化时，Cline 更新索引。这是它的循环任务，而不是人的。
3. 其他代理从索引开始 – Claude、Codex、Gemini 将索引作为上下文窗口的一部分，跳过探索，直接开始实现。

结果：代理有方向地启动。它们不再在每次提交时重新发现插件模式，探索成本消失。

这有什么变化

• Token efficiency – 代理将上下文窗口用于任务，而不是重新学习代码库。在 200 k 令牌的窗口中，这非常重要。
• Consistency – 每个代理都从相同的映射开始。Codex 不会创造 Claude 不知道的命名约定；两者读取相同的合约。
• Handoff clarity – 当你在任务中途切换代理时，新代理会从上一个代理离开的地方继续。索引告诉它已决定的事项；记忆库告诉它正在进行的内容。无需重新简报。

更深层的模式

多代理工作流面临共享上下文问题。每个模型都有自己的上下文窗口，每个会话都是全新开始。代码库是它们唯一共享的东西——但它并未以上下文的形式组织；它只是代码。

索引就是桥梁。它将仓库的隐式结构显式化，使其可导航，并可被任何会话中的任意代理所使用。

代理并没有变得更聪明；它们只是不再盲目起步。

代码库是共享的上下文。索引是关键。