--- title: "Reference coding for AI coding agents" canonical: "https://xerj.org/science/reference-coding" updated: "2026-11-14" source: "content/science/reference-coding.md" --- # Reference coding for AI coding agents **Short answer** (updated 2026-11-14): In AI coding, what is reference coding? It is how a coding agent looks up an API it does not already know. The agent clones libraries that already solved the problem, indexes them with XERJ, and reads a cited passage before it writes. On 8 tasks, the same model used 9,982 output tokens with XERJ against 26,477 with grep. **Key number:** On 8 tasks, the same Claude Code model used 9,982 output tokens with XERJ against 26,477 when it grepped the source, 2.7 times fewer, and solved 16 of 16 both ways. (as of 2026-08-06; source: [/case-studies/reference-coding](/case-studies/reference-coding)) **TL;DR** In AI coding, reference coding is how an agent looks up an API it does not already know. It clones libraries that already solved the problem, indexes them, and reads a cited passage before it writes. ## Agent prompt ```text Act as a coding agent. Read https://xerj.org/llms.txt, install XERJ, start a local node, index one folder I point you to, and run one search so I can see a cited passage. ``` *Figure: The 9,982 vs 26,477 output-token counts, and the 16 of 16 solve rate, are from the published reference-coding case study (8 tasks, 16 runs per arm). This walkthrough does not add a new measurement.* ## How it works The agent picks open-source repositories close to the task, clones them, and indexes them. Before it writes, it searches for how those libraries solved the same kind of problem, and it reads a passage with a file and line. It then adapts the idea and checks the licence. That is retrieval before generation, applied to code. It is tighter than grepping the tree and opening every match. ## How XERJ uses it XERJ is the index and the search step. `xerj autoindex` builds the index. The agent searches with the CLI or over MCP, and quotes file:line. The measured write-up is the [reference-coding case study](/case-studies/reference-coding). On 8 tasks, the same Claude Code model used 9,982 output tokens with XERJ against 26,477 when it grepped the source, 2.7 times fewer, and solved 16 of 16 both ways. A second study on unfamiliar contract domains is where the 6.5 times cheaper figure comes from, against a memory-only arm, not against native grep. A practical setup guide is [how to index a reference library](/answers/index-reference-library-for-coding-agent). For the token-budget idea, see [context engineering](/science/context-engineering). ## History and research The product name is XERJ's. Related public research includes retrieval-augmented generation, introduced by Lewis and colleagues in 2020 ([Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks](https://arxiv.org/abs/2005.11401)). The numbers on this page come only from XERJ's published case study. ## Guides See it in practice: the [reference coding case study](/case-studies/reference-coding), [index a reference library for a coding agent](/answers/index-reference-library-for-coding-agent) and [Corpus Hub](/docs/corpus-hub). ## Related terms [Context engineering](/science/context-engineering) and [syntax-aware search](/science/syntax-aware-search). ## FAQ ### What is reference coding in AI coding? It is a loop in which an AI coding agent retrieves a real implementation from reference libraries before it writes code, instead of guessing an API from memory. It is not medical coding. ### How does XERJ use reference coding? The agent clones and indexes the repositories closest to the task, then searches them with XERJ and reads a cited passage. The case study is the measured write-up. ### Is this the same as grepping the source? No. Grep lists lines. Reference coding retrieves a ranked passage with file:line from an index of the reference libraries, then the agent writes. ### Where are the token numbers from? The published case study: 9,982 vs 26,477 output tokens on 8 tasks, 16 of 16 solved both ways. A second study on unfamiliar contracts is where the 6.5 times cheaper figure comes from, against memory-only. ## Evidence - On 8 tasks, the same Claude Code model used 9,982 output tokens with XERJ against 26,477 when it grepped the source, 2.7 times fewer, and solved 16 of 16 both ways. — [/case-studies/reference-coding](/case-studies/reference-coding) ## Related - [Reference-coding for Claude Code](/case-studies/reference-coding) - [How do I set up reference coding so the agent retrieves a mechanism before writing code?](/answers/index-reference-library-for-coding-agent) - [Local code search MCP that uses fewer tokens than grep](/answers/local-code-search-mcp-fewer-tokens-than-grep) - [What is context engineering?](/science/context-engineering) - [What is syntax-aware search?](/science/syntax-aware-search) - [What is agentic memory?](/science/agentic-memory) (same intent: Science) - [BM25 vs vector search](/science/bm25) (same intent: Science) - [What is Corpus Hub?](/science/corpus-hub) (same intent: Science)