Repository Understanding

How tools find the right slices

No single method suffices, so tools combine several. Semantic retrieval embeds files or chunks as vectors and returns the nearest neighbors of the embedded query, strong for intent-based questions such as "where is authentication handled?" where the wording does not match. Lexical and symbol search answer exact questions: ripgrep for raw text, and structural tools such as ctags, tree-sitter, and the Language Server Protocol (LSP) for where a symbol is defined and everywhere it is used. Dependency and call-graph traversal expands from a seed file along imports and call edges to its callers, callees, and types. Finally, cheap project signals, the README, configuration, and tests, reveal conventions and intended behavior.

Worked example: rename getUser everywhere

Consider the request "rename the function getUser everywhere and update its callers." Loading the whole repository would be wasteful and may not even fit the window. Instead the tool works structurally, pulling in only what the edit touches.

1. 1Resolve the definitionA symbol lookup, LSP go-to-definition, or a ctags or tree-sitter index, pinpoints where getUser is declared, distinguishing it from unrelated methods that share the name.
2. 2Enumerate the call sitesLSP find-references returns every caller with its file and line number; a scoped ripgrep pass backs it up for dynamic or string-based uses that reference resolution can miss.
3. 3Select the slicesOnly the definition file and the referencing files are pulled into context, a handful of files rather than the entire repository.
4. 4Apply the editsThe model renames the declaration and each call site within the loaded files, editing precisely the code it can see.
5. 5VerifyRunning the type checker and tests surfaces any missed or dynamically dispatched reference as an error to resolve in a follow-up pass.

Only a handful of files ever enter the context, yet the change is complete and verifiable, because the selection was driven by the code's structure rather than by a fuzzy guess.

Whole repo vs retrieval on demand

These two strategies trade simplicity against scale, and the right choice depends almost entirely on repository size.

Further reading

• Language Server Protocol Specification, how editors expose definitions, references, and symbols that coding tools reuse for exact navigation.
• tree-sitter documentation, incremental parsing that produces the syntax trees behind symbol extraction and chunking.
• Universal Ctags documentation, generating a symbol index for fast definition lookup across a repository.
• RepoCoder: repository-level code completion through iterative retrieval and generation, a research reference on retrieving relevant repository context for code models.