代码智能体需要多少静态结构？——一项关于确定性锚定的研究

摘要

基于LLM的代码代理通过关键词搜索浏览代码仓库，但会遗漏定义软件实际运作方式的结构关系（如调用图、继承层次和配置依赖）。这使代理的导航行为具有随机性，且难以跨运行复现。我们探索了轻量级静态分析能否为这类代理提供确定性锚点：将稳定的结构事实以纯文本注释形式注入，约束概率探索过程，使导航更具可预测性。以OpenAI Codex作为强基线，我们系统性地注入不同粒度的结构注释，并测量其对定位能力、轨迹行为及运行间稳定性的影响。研究发现了所谓的"确定性锚定效应"：静态结构的作用更多体现在使导航行为更规范、更可复现，而非让代理变得更"智能"。三项观察结果支持该发现：（1）锚定有效：轻量级调用/继承拓扑能提升函数级定位能力（Func@5+2.2个百分点），并缩短交互轨迹（-1.6轮）；（2）锚定对规模敏感：最优粒度和方向性取决于仓库特征，密集语义呈现递减效应，而枢纽型项目更适合仅暴露"谁调用了我"的逆链路（排除前向边）；（3）锚定增强稳定性：标签将链路遵循率从0.15-0.18提升至0.21-0.24，运行间方差约减半，在中型仓库中单次运行可靠性提升（Pass@1+3.4个百分点），但代价是增加约10%的输入令牌。这些观察结果提供了实用指南：中型项目默认采用轻量级拓扑，大型仓库需裁剪前向边，隐式依赖场景则应保留密集标签。

English

LLM-based code agents navigate repositories through keyword search but miss the structural relationships, such as call graphs, inheritance hierarchies, and configuration dependencies, that define how software actually works. This makes agent navigation stochastic and difficult to reproduce across runs. We investigate whether lightweight static analysis can provide deterministic anchors for these agents: stable structural facts injected as plain-text comments that constrain probabilistic exploration and make navigation more predictable. Starting from a strong baseline, Codex from OpenAI, we systematically inject varying granularities of structural annotations and measure their effects on localization, trajectory behavior, and run-to-run stability. Our study identifies what we call the deterministic anchoring effect: static structure helps less by making agents "smarter" and more by making their navigation disciplined and reproducible. Three observations support this finding: (1) Anchoring works: lightweight call/inheritance topology improves function-level localization (+2.2pp Func@5) and shortens trajectories (-1.6 interaction rounds); (2) Anchoring is scale-sensitive: the optimal granularity and directionality depend on repository characteristics, where denser semantics show diminishing returns and hub-heavy projects benefit from inverse-only links that expose "who-calls-me" without forward edges; (3) Anchoring stabilizes: tags raise link-following rate from 0.15-0.18 to 0.21-0.24, roughly halve run-to-run variance, and improve single-run reliability (Pass@1 +3.4 pp) on medium-scale repositories, at the cost of roughly 10% more input tokens. These observations suggest practical guidelines: default to lightweight topology on medium projects, prune forward edges in large repositories, and reserve dense tags for implicit-dependency cases.