Formal Architecture Descriptors as Navigation Primitives for AI Coding Agents
Ruoqi Jin · 2026
Read Formal Architecture Descriptors as Navigation Primitives for AI Coding Agents by Ruoqi Jin (2026) in the Tower of Babel, a free online library of public-domain works preserved in clean, searchable text. No sign-up. The full text is served as a plain-text file at a predictable URL, where text is present: https://antarctic-labs.com/tower-of-babel/arxiv-2604-13108.txt.
Introduction
Jin tests whether formal architecture descriptors cut the roaming AI coding agents do when searching codebases. In controlled trials, architecture context cuts navigation steps by 33 to 44 percent, and an auto-generated descriptor hits 100 percent accuracy against 80 percent blind. A field study across 7,012 sessions shows 52 percent less variance, and format matters for failure: JSON fails atomically while YAML silently corrupts half of errors. Jin proposes intent.lisp, an S-expression descriptor, with the open-source Forge toolkit.
Catalog record
| CREATOR | Ruoqi Jin |
|---|---|
| YEAR | 2026 |
| COLLECTION | PAPERS |
| FORMAT | TXT |
| FILE SIZE | 17419 |
| LICENSE | http://creativecommons.org/licenses/by/4.0/ |
| RIGHTS | CC BY |
| SOURCE | arXiv |
Source: https://arxiv.org/abs/2604.13108
Browse the full library · About the Tower of Babel
Full text
The opening of the work, from the library's hosted text:
Formal Architecture Descriptors as Navigation Primitives for AI Coding Agents Ruoqi Jin Abstract . AI coding agents spend a substantial fraction of their tool calls on undirected codebase exploration. We investigate whether providing agents with formal architecture descriptors—structured documents declaring module boundaries, symbol signatures, constraints, and data flows—can reduce this navigational overhead. We present three complementary studies. First, a controlled experiment (24 code localization tasks × \times 4 conditions, Claude Sonnet 4.6, temperature=0) demonstrates that architecture context—regardless of format—reduces navigation steps by 33–44% (Wilcoxon signed-rank p = 0.009 p=0.009 , Cohen’s d = 0.92 d=0.92 ). No significant format difference was detected: a separate study (20 questions × \times 4 formats) found identical 95% accuracy across S-expression, JSON, YAML, and Markdown, though small differences cannot be ruled out given sample sizes. Second, a critical artifact-vs-process experiment (15 tasks × \times 3 conditions) demonstrates that an automatically generated descriptor—with zero human refinement and zero code restructuring—achieves 100% accuracy versus 80% blind ( p = 0.002 p=0.002 , d = 1.04 d=1.04 ), proving that the descriptor file itself has direct navigational value independent of any developer self-clarification effect. Third, an observational field study across 7,012 Claude Code sessions shows that formal declaration correlates with 52% reduction in agent behavioral variance. A writer-side experiment (96 generation runs, 96 error injections) reveals that all parseable formats achieve > > 91% generation reliability, but failure modes differ critically: JSON has the lowest silent corruption (21%) but fails atomically under structural error; YAML silently corrupts 50% of errors; S-expressions detect all structural completeness errors but have imprecise localization. We propose intent.lisp , an S-expression architecture descriptor, arguing that its value lies not in superior LLM comprehension but in the combination of non-atomic failure, compression density (22% shorter than JSON, 5:1–64:1 across 646K lines of production code), and syntactic enforcement of hierarchy. 1. Introduction Large language model (LLM)-based coding agents—Claude Code ( claude ) , Cursor ( cursor ) , GitHub Copilot Workspace ( copilot ) —have demonstrated remarkable ability to understand and modify source code. Yet on real-world codebases, these agents spend a substantial fraction of their interactions exploring rather than editing: grepping for symbols, globbing for files, and reading modules to reconstruct architectural context that exists only in the developer’s mind. This Navigation Paradox ( codecompass ) persists even as context windows grow larger: the bottleneck shifts from retrieval capacity to navigational salience. LoCoBench-Agent ( locobench ) identifies a 12-turn efficiency threshold beyond which agents exhibit sharply diminishing returns. SWE-agent ( sweagent ) found that iterative search can degrade performance relative to no search at all. Current mitigation approaches fall into two camps. Human-configured context files—CLAUDE.md, AGENTS.md ( agentsmd ) (adopted by 60,000+ projects), Cursor Rules—allow developers to describe projects in natural-language Markdown. A recent empirical evaluation found no statistically significant improvement in task success while increasing inference cost by over 20% ( agentbench ) . Automated approaches—Aider’s tree-sitter repo maps ( aider ) , CodexGraph ( codexgraph ) , RepoGraph ( repograph ) —extract structural information programmatically but capture only syntactic relationships, missing design intent and architectural constraints. A recent position paper ( archnoarch ) explicitly identifies the gap between informal instruction files and formal Architecture Description Languages (ADLs) ( medvidovic ) , but proposes no specific notation. We address this gap with intent.lisp : an S-expression architecture descriptor that functions as a structured channel through which human architectural intent is captured and consumed by AI agents. Our controlled experiment reveals that no significant difference in LLM comprehension was detected across formats . The value of S-expressions lies elsewhere: in the constraints they impose on the writing agent, their error resilience, the compression ratios they achieve (5:1–64:1 across production projects, weighted average 34:1), and the downstream tooling they enable—capabilities that unstructured formats cannot support. Our contributions are: (1) A controlled experiment demonstrating that formal architecture context reduces agent navigation steps by 33–44% ( d=0.92 , p=0.009 ), with no significant format difference detected. We note this effect is model-sensitive: stronger models reduce the blind baseline, compressing the marginal benefit. (2) An artifact-vs-process experiment showing that automatically generated descriptors (zero human refinement) achieve 100% accuracy versus 80% blind ( d=1.04 , p=0.002 )—proving that the descriptor artifact itself has direct value, independent of any developer self-clarification effect. (3) An observational field study (7,012 sessions) showing that formal architecture declaration correlates with 52% reduction in agent behavioral variance. (4) The intent.lisp format and design rationale: S-expressions are chosen not for LLM comprehension (which is format-agnostic) but for syntactic enforcement of hierarchy, graceful error degradation, and compression density. 2. Approach 2.1. The intent.lisp Format An intent.lisp file declares a project’s architecture as a nested S-expression tree. Each project is decomposed into pillars (top-level responsibility domains), components (modules within pillars), and symbols (function signatures, types, constants). ⬇ ( intent jarvis ( design - constraints ( three - pillars ( memory control tools )) ( communication ( must - use EventBus )) ( db - access ( only memory / storage ))) ( pillar memory ( purpose "Data ␣ capture, ␣ storage, ␣ analysis" ) ( component storage ( role "SOLE ␣ DB ␣ gateway" ) ( invariants "No ␣ raw ␣ SQL ␣ outside ␣ this ␣ module" ) ( data - flow "Event ␣ -> ␣ Storage ␣ -> ␣ PostgreSQL" ) ( symbols ( function save_message ( sig "async ␣ fn ␣ save_message(&self, ␣ ...)" )))))) In practice, humans do not write intent.lisp directly. The developer describes architectural intent in natural language; an LLM translates this into S-expressions; other LLM agents subsequently consume the result. The descriptor thus functions as a structured channel for intent transmission—analogous to how Protocol Buffers serve microservice communication: not because the format is easier to read, but because it constrains the producer. Four properties make S-expressions well-suited for this role: Syntactic enforcement of hierarchy. S-expressions permit exactly one structure: nested lists with atoms. Containment relationships are expressed through parenthesization—not by convention but by syntax. Our writer-side experiment (§ 3.2 ) finds that modern LLMs produce equally concise output in all formats at temperature=0—the syntactic discipline of S-expressions is a structural guarantee rather than an empirically observed generation difference. Compression density. Table 1 shows compression ratios across five production projects (646K total source lines). Ratios range from 5:1 (small projects with dense L3 descriptors) to 64:1 (large compilers with single-file descriptors), with a weighted average of 34:1. Table 1. Compression ratios across five production projects. Ratios vary with descriptor granularity. Project Source Lisp Files Ratio xiaojinpro-backend 469,594 7,877 32 60:1 missiond 107,986 5,846 14 18:1 jarvis-forge 44,321 698 1 64:1 jarvis 22,164 4,329 6 5:1 jarvis-mechanic 1,856 366 2 5:1 Total 645,921 19,116 55 34:1 Graceful error degradation. Our error injection experiment (§ 3.2 ) validates this empirically: JSON fails atomically —a single missing brace renders the entire file unparseable with 0% content recovery. YAML fails silently —50% of injected errors change semantic meaning without any parser warning. S-expressions detect 100% of structural completeness errors; while localization is imprecise, the content before the error remains structurally intact with a fault-tolerant parser. Formal parseability enables tooling. A recursive descent parser under 100 lines handles the full S-expression language. We note that JSON