Versioned architecture descriptor files for agent code navigation
仓库维护者可以把架构描述符作为编码代理的一级文件加入仓库,然后先测它是否减少导航,再决定是否让代理做更自主的编辑。这里的证据更指向减少无效搜索,而不是原始编码质量。在那项受控研究里,架构上下文把一个 22K 行 Rust 项目的平均导航步数从 5.2 降到 3.4(S-expression 或 JSON),Markdown 则降到 2.9。在第二项针对 43K 行 Rust 项目的研究里,一个自动生成的 170 行描述符在 15 个任务上的准确率达到 100%,而盲搜只有 80%。这些结果足以支持一个具体方案:生成一个仓库描述符,写清组件、符号边界、约束和数据流,把它放进版本控制,在任务开始时交给代理。
短期内的用户是已经在中等规模代码库里使用 Claude Code、Cursor 或类似工具的团队,代理在 grep、文件搜索和模块阅读上花了太多轮次。低成本验证很直接:在一组固定的代码定位和补丁任务上,对比加入描述符前后的 explore/edit 比例和工具调用次数。格式问题对模型表现来说次要。论文报告了 S-expression、JSON、YAML 和 Markdown 的理解结果相近;在错误注入测试里,JSON 的静默损坏最低,而 S-expression 对结构完整性错误的检测更可靠。这指向一条落地路径:团队选一个最适合自己工具链和校验需求的格式,然后在 CI 里用 schema 检查强制执行。