Versioned architecture descriptor files for agent code navigation
Repository maintainers can add an architecture descriptor as a first-class file for coding agents, then measure whether it cuts navigation before they ask for more autonomous edits. The evidence here is more about wasted search than raw coding quality. In the controlled study, architecture context cut average navigation steps on a 22K-line Rust project from 5.2 to 3.4 with S-expressions or JSON, and to 2.9 with Markdown. In a second study on a 43K-line Rust project, an auto-generated 170-line descriptor reached 100% accuracy on 15 tasks, against 80% for blind search. That is enough to justify a concrete build: generate a repo descriptor that names components, symbol boundaries, constraints, and data flow, keep it in version control, and feed it to the agent at task start.
The near-term user is the team already running Claude Code, Cursor, or similar tools on a medium-sized codebase where agents spend too many turns on grep, file search, and module reading. The cheap check is simple: compare explore/edit ratios and tool-call counts on a fixed set of code localization and patch tasks before and after adding the descriptor. The format question looks secondary for model performance. The paper reports similar comprehension across S-expression, JSON, YAML, and Markdown, while JSON had the lowest silent corruption in error injection tests and S-expressions caught structural completeness errors more reliably. That points to an adoption path where teams pick the format that best fits their tooling and validation needs, then enforce it with schema checks in CI.