来源笔记
Formal Architecture Descriptors as Navigation Primitives for AI Coding Agents
摘要
正式的架构描述符能帮助 AI 编码代理用更少的探索步骤找到正确代码。论文认为，主要收益来自给代理提供明确的架构结构，而文件格式本身对模型理解的影响较小。
问题
- AI 编码代理会把很多工具调用花在代码库探索上，比如 grep、文件搜索和模块阅读，然后才能开始编辑代码。
- 现有的上下文文件，如
CLAUDE.md或AGENTS.md，比较非正式；自动生成的仓库映射能捕捉语法，但常常漏掉设计意图、约束和数据流。 - 这很重要，因为额外的导航会增加成本，也会影响任务成功率，尤其是在更大的代码库里，盲搜更难。
方法
- 论文提出了 intent.lisp，一种用嵌套 S-expression 编写的正式架构描述符，记录支柱、组件、符号、约束和数据流。
- 一个扫描工具会遍历仓库，并用 LLM 起草该描述符；然后编码代理在任务中把这个描述符当作导航入口点来阅读。
- 作者做了三项研究：一项跨上下文格式的受控代码定位实验，一项使用自动生成描述符、没有人工润色的 artifact-vs-process 测试，以及一项覆盖 7,012 个 Claude Code 会话的观察性现场研究。
- 他们还从写作侧测试了可靠性：让 LLM 生成 S-expression、JSON、YAML 和 Markdown 格式的描述符，再注入结构错误，比较解析失败和静默损坏。
- 论文对格式的判断很有限：S-expression 不是更容易被模型理解，但它更短，语法会强制层级结构，而且在生成出错时，比 YAML 或 Markdown 更容易退化。
结果
- 在一个 22K 行的 Rust 项目上，Claude Sonnet 4.6 完成 24 个代码定位任务时，架构上下文把平均导航步骤从 5.2（盲搜） 降到 3.4（S-expression）、3.4（JSON） 和 2.9（Markdown），减少了 33–44%；盲搜与上下文条件之间的差异显著，Wilcoxon p=0.009，效应量 d=0.92。
- 同一实验里，准确率的变化小于步骤变化：54%（13/24）盲搜、58%（14/24）S-expression、58%（14/24）JSON、63%（15/24）Markdown。另一项 20 题理解测试在四种格式下都得到 95% 准确率，格式间两两差异不显著。
- 在一个 43K 行 Rust 项目的 15 个任务上，artifact-vs-process 研究显示，一个 自动生成的 170 行描述符 达到 100% 准确率，对比 80% 盲搜，p=0.002，d=1.04。这说明描述符文件本身就能起作用，即使没有开发者清理或重构代码。
- 同一研究里，人工整理的 698 行描述符 达到 87% 准确率 和 2.9 个步骤，对比 AutoGen 的 3.9 和盲搜的 5.6。AutoGen 在准确率上超过 Curated，但 AutoGen 和 Curated 之间的差异 不显著（p=0.515）。
- 在 96 次生成运行中，可解析输出率分别是 JSON 100%、S-expression 95.8%、YAML 91.7%。在 96 次错误注入中，静默损坏分别是 JSON 21%、S-expression 50%、YAML 50% 和 Markdown 100%；S-expression 检测到了 100% 的结构完整性错误，而 YAML 只检测到该类错误的 50%。
- 在 7,012 个 Claude Code 会话 和 484,937 条消息 中，引入正式描述符后，探索/编辑比的 IQR 从 2.24 降到 1.08，行为方差减少了 52%。这项现场研究是相关性分析，论文也指出，更大的代码库和非定位任务还需要直接测试。